Forem: Richard Haines

How to create a GraphQL API with Prisma and Nexus

Richard Haines — Mon, 08 Mar 2021 13:24:53 +0000

As part of my learning everything there is to know about Prisma I've decided to write some tutorials for you as much for me. There may be some knowledge gaps and I may not have a great grasp on some things yet, so if you find an error or something that I have explained that is fundamentally wrong, feel free to message me on Twitter @studio_hungry and we can duke it out!

What you will build

You are going to build a GraphQL api backed by a postgres database. This api will hold data for showing different competencies within companies. For example, each company will have roles within their organization (Software Engineer, Cloud Specialist) which require certain skills (Scala, React).

Once complete you will have learnt how to setup your own GraphQL api, how to use Prisma as an ORM layer and how to use Nexus as a means of producing code first GraphQL schemas.

Prerequisites

This tutorial assumes basic knowledge of databases, APIs and how to setup a project and install packages. The tutorial borrows heavily from the awesome docs for Prisma and Nexus.

What is Prisma and Nexus?

Prisma is an ORM (Object-Relational-Mapping) layer that sits on top of your database. It ships with a query builder which allows you to write type safe queries as JavaScript (or TypeScript) objects. It's built to work with TypeScript, has it's own vscode extension and offers a lovely abstraction over SQL databases. For a full (and in depth) rundown of what Prisma is you can check out their docs page, Why Prisma?.

Nexus is a declarative, code first approach to writing GraphQL schemas. It's created by a team at Prisma and works seamlessly with it. Nexus allows you to house your schema and resolver logic in one place and write it with one common language such as JavaScript or TypeScript. You'll learn more about this approach during the tutorial. If you wish to read further you can checkout their excellent docs page Why Nexus?.

Setup the project

Create a new directory in your project location of choice and begin by installing the required packages.

This tutorial will use NPM to run the application, you can use Yarn if you wish.

npm init -y
npm i --save-dev prisma ts-node-dev typescript
npm i @prisma/client apollo-server graphql nexus

The article uses the following versions:

  "devDependencies": {
    "prisma": "^2.17.0",
    "ts-node-dev": "^1.1.1",
    "typescript": "^4.1.5"
  },
  "dependencies": {
    "@prisma/client": "^2.17.0",
    "apollo-server": "^2.21.0",
    "graphql": "^15.5.0",
    "nexus": "^1.0.0"
  }

Next create a tsconfig.json file at your projects root and add the following boilerplate:

{
    "compilerOptions": {
        "target": "ES2018",
        "module": "commonjs",
        "lib": ["esnext"],
        "strict": true,
        "rootDir": ".",
        "outDir": "dist",
        "sourceMap": true,
        "esModuleInterop": true
    }
}

Finally add some build scripts to the package.json

"dev": "ts-node-dev --transpile-only --no-notify api/app.ts",
"build": "tsc"

Now that everything is installed you'll need to create some files and folders. All the code will live in an api folder at the projects root. The structure will look like this:

api
- graphql
- index.ts
- app.ts
- context.ts
- db.ts
- schema.ts
- server.ts

Setup the database

This tutorial uses Postgres as it's database. If you don't already have an instance of Postgres installed on your machine you can grab it from the download page on their site. The default postgres installation comes with the user postgres. This tutorial will assume that user from here onwards, though you can swap that out for your own user if you wish. This tutorial will also use psql for interacting with the database at certain times. psql is a tool for writing SQL queries from the command line, it comes with the installation of Postgres.

Once you have it installed login and create a new database.

// Login
psql -U postgres;

// Create database
CREATE DATABASE companyCompetenceDatabase;

// Confirm database creation
\l;

Adding the Prisma schema data models

To setup Prisma you must first invoke the CLI by running npx prisma then npx primsa init. A new folder will be created at the projects root called prisma which will house a schema.prisma file. A .env file will also be created and pre-populated with a placeholder connection string.

The DATABASE_URL is the connection string that will be used to hook up to your Postgres database. In the .env file change the placeholder to the following, replacing the password for your own, the user for your own if you have a different one and the database name if you choose a different name.

DATABASE_URL="postgresql://postgres:test1234@localhost:5432/companycompetencedatabase?schema=public"

Note that although you gave the name of the database in camelCase when creating it, Postgres converts that to all lower case once the database is created. I have left the creation string as camelCase for readability.

Inside schema.prisma add the following models below the client generator.


// 1-n with trade and role
// company can have many roles
model Company {
  id            Int      @id @default(autoincrement())
  name          String?
  contactPerson String?
  bio           String?
  email         String?
  website       String?
  roles         Role[]
}

// 1-n with skill, n-1 with company
// a role can have many skills
// a company can have many roles
model Role {
  id        Int     @id @default(autoincrement())
  name      String?
  skills    Skill[]
  company   Company? @relation(fields: [companyId], references: [id]) // not in db, used by Prisma to set relation
  companyId Int? // the foreign key, this is in the db
}

// 1-n with role
model Skill {
  id     Int    @id @default(autoincrement())
  name   String?
  role   Role?   @relation(fields: [roleId], references: [id])
  roleId Int?
}

Let's dive into what all this means. The Prisma data modal is a schema that maps to your database schema. In it you define the shape of your data and any relationships that may exist between tables. If you have never worked with SQL databases some of fields may seem confusing. Let's break them down.

In SQL land relationships between tables are defined by foreign keys. These are ids that map to other tables. In the example above you can see that the Role model has a field called companyId, this is a foreign key that will be added to the database and represents the link to the primary key (the id field) in the Company model. In the Company model you can see an array of roles. This represents a collection or list of roles, the many in the 1-many relationship that the Company (1) and Roles (many) can have. The ? next to many of the field denotes that they are nullable.

A more explicit example of a one-many relationship can be viewed below:


model One  {
  id        Int @id @default(autoincrement()) // Primary key
  hasMany   Many[]
}

model Many  {
  id                Int @id @default(autoincrement()) // Primary key
  oneRelationField  One @relation(field: [foreignKey], references: [id]) // Not in db, used by Prisma to describe relation
  foreignKey        Int // The foreign key, this is in the db
}

The foreignKey references the id on the One model, this tells the database that the primary key from One is used as the foreignKey on Many. The foreignKey is designed to allow multiple instances of the value from which it references. Only the foreign key is used in the actual database table, the oneRelationField is used by Prisma when creating relations.

Now that you have created your data model you can run a migration and map the models to the database schema. The following command creates a new SQL migration file named init and runs the migration against the database. This creates the tables in the format described by the models.

npx prisma migrate dev --name init --preview-feature

Using the Nexus objectType

The traditional way to setup a GraphQL schema is to build a schema using the GraphQL Schema Language which is written as a template string. A resolver is also created to resolve the endpoint and return whatever data is requested. In Apollo this is done by creating a typeDefs file and declaring the schema types and queries. Inside the typeDefs file you would create the the GraphQL types (which look quite similar to the Prisma Schema Language (PSL)) and queries inside an exported template string on a GraphQL tag, an example how this might look can be seen below:


exports.typeDefs = gql`
type Query {
    allCharacters: [Character]!
    characterById(_id: ID!): Character
    characterByName(name: String!): Character
}

type Character {
    _id: ID
    name: String!
    house: String
    patronus: String
    bloodStatus: String
    role: String
    school: String
    deathEater: Boolean
    dumbledoresArmy: Boolean
    orderOfThePheonix: Boolean
    ministryOfMagic: Boolean
    alias: String
    wand: String
    boggart: String
    animagus: String
}
`

This file would then be added to every time you wanted to introduce a new data type or query definition, this works so long as the number of data models is small but is not very modular and wouldn't be easy to scale if you were to introduce multiple new data types and queries. Another way to accomplish defining your GraphQL types and schema is to use Nexus and to take a code first approach by giving each type its own file and using the objectType function.

Inside api/graphql create a new file called company.ts and add the following:

import { objectType } from 'nexus';

export const Company = objectType({
    name: 'Company',
    definition(t) {
        t.nonNull.int('id');
        t.string('name');
        t.string('contactPerson');
        t.string('bio');
        t.string('email');
        t.string('website');
        t.int('roleId');
        t.nonNull.list.nonNull.field('roles', {
            type: 'Role',
            resolve: (parent, _, ctx) => {
                return ctx.db.company
                    .findUnique({
                        where: { id: parent.id },
                    })
                    .roles();
            },
        });
    },
});

The objectType function is used to fetch the fields from your schema. It's combined with a resolver and describes the schema models in code. The definition method allows you to define the fields of your object type as well as the relationships.

Let's dissect the relations field to make sure we understand what is happening here.

t.nonNull.list.nonNull.field('roles', {
    type: 'Role',
    resolve: (parent, _, ctx) => {
        return ctx.db.company
            .findUnique({
                where: { id: parent.id },
            })
            .roles();
    },
});

The field is not nullable, that is, it can't be null t.nonNull, it's an array (a list) of values which can also not be null, t.nonNull.list.nonNull. In the field you have given it a name that corresponds to the name used in the schema and set it's model type, Role, you then resolve the relationship. The first argument in the resolver is the parent or root node, this is used to pass information from the parent to the child resolvers. The second is the arguments passed to the resolver and the third the schema context, which we will shortly be covering. The Prisma client (via the context) is used to query for the model and find the record where the id matches. So in this case the query will resolve to find zero or one Company that matches the filter.

The full contents of api/GraphQL

// company.ts
export const Company = objectType({
    name: 'Company',
    definition(t) {
        t.nonNull.int('id');
        t.string('name');
        t.string('contactPerson');
        t.string('bio');
        t.string('email');
        t.string('website');
        t.int('roleId');
        t.nonNull.list.nonNull.field('roles', {
            type: 'Role',
            resolve: (parent, _, ctx) => {
                return ctx.db.company
                    .findUnique({
                        where: { id: parent.id },
                    })
                    .roles();
            },
        });
    },
});

// role.ts
export const Role = objectType({
    name: 'Role',
    definition(t) {
        t.nonNull.int('id');
        t.string('name');
        t.field('company', {
            type: 'Company',
            resolve: (parent, _, ctx) => {
                return ctx.db.role
                    .findUnique({
                        where: { id: parent.id || undefined },
                    })
                    .company();
            },
        });
        t.list.field('skills', {
            type: 'Skill',
            resolve: (parent, _, ctx) => {
                return ctx.db.role
                    .findUnique({
                        where: { id: parent.id || undefined },
                    })
                    .skills();
            },
        });
    },
});

// skill.ts
export const Skill = objectType({
    name: 'Skill',
    definition(t) {
        t.nonNull.int('id');
        t.string('name');
        t.field('role', {
            type: 'Role',
            resolve: (parent, _, ctx) => {
                return ctx.db.skill
                    .findUnique({
                        where: { id: parent.id || undefined },
                    })
                    .role();
            },
        });
    },
});

Finally, export the types from the api/GraphQL/index.ts file:

export * from './company';
export * from './role';
export * from './skill';

Creating the server

Begin by opening api/schema.ts. This will be where you make a schema with Nexus. You will pass in the defined types from the api/GraphQL/index.ts file and set the output paths. These paths will be where Nexus writes the generated TypeScript definitions that are derived from the Prisma schema. It will also output a GraphQL schema, this file should not be edited directly.

schema.ts

import { makeSchema } from 'nexus';
import { join } from 'path';
// It is considered best practice to pass your types directly from a "star import" like we've done above. Under the hood, Nexus will unwrap the types. This prevents from constantly having to manually export & import every single type of your API.
import * as types from './graphql';

export const schema = makeSchema({
    // GraphQL types that will be used to construct your GraphQL schema.
    types,
    outputs: {
        // Output path to where nexus should write the generated TypeScript definition types derived from your schema. This is mandatory to benefit from Nexus' type-safety.
        typegen: join(__dirname, '..', 'nexus-typegen.ts'),
        // Output path to where nexus should write the SDL (schema definition language) version of your GraphQL schema.
        schema: join(__dirname, '..', 'schema.GraphQL'),
    },
    contextType: {
        // Path to the module where the context type is exported
        module: join(__dirname, './context.ts'),
        // Name of the export in that module
        export: 'Context',
    },
});

Open the server.ts file and add the following:

import { ApolloServer } from 'apollo-server';
import { schema } from './schema';
import { context } from './context';

export const server = new ApolloServer({ schema, context });

Here you are instantiating the ApolloServer instance and exporting it while passing in the schema and context. Next you will create the context.

Finally open app.ts and add the following, which will start the server when the dev script is run.

import {server} from './server';

server.listen().then(({url}) => {
    console.log(`Server ready at ${url}`)
})

The GraphQL context

The GraphQL context is an object which is shared across all the resolvers, the GraphQL server creates and destroys a new instance between each request. To create a context open the api/db.ts file.

import { PrismaClient } from '@prisma/client';

export const db = new PrismaClient();

Then the api/context.ts file

import { db } from './db';
import { PrismaClient } from '@prisma/client';

export interface Context {
    db: PrismaClient;
}

export const context = {
    db,
};

Now the context has been created and passed to the GraphQL server. The context can be used to store and/or check information too. One such use case might be an authenticated user, are they authorized to do a certain mutation? In any case, your context is a simple object which will suffice for now.

Writing queries and mutations

The API isn't much good if you can't make any requests against it. Begin by opening back up the companies.ts file. Under the objectType creation of the Company type, add the new Query and Mutation types.

export const Company = objectType({
    name: 'Company',
    definition(t) {
        t.nonNull.int('id');
        t.string('name');
        t.string('contactPerson');
        t.string('bio');
        t.string('email');
        t.string('website');
        t.int('roleId');
        t.nonNull.list.nonNull.field('roles', {
            type: 'Role',
            resolve: (parent, _, ctx) => {
                return ctx.db.company
                    .findUnique({
                        where: { id: parent.id },
                    })
                    .roles();
            },
        });
    },
});

export const CompanyQuery = extendType({
    type: 'Query',
    definition(t) {
        // get all companies
        t.list.field('companies', {
            type: 'Company',
            resolve(_root, _args, ctx) {
                return ctx.db.company.findMany();
            },
        });
        // get company by id
        t.field('company', {
            type: 'Company',
            args: {
                id: nonNull(intArg()),
            },
            resolve(_root, args, ctx) {
                return ctx.db.company.findUnique({
                    where: { id: args.id },
                });
            },
        });
        t.list.field('roles', {
            type: 'Role',
            resolve(_root, _args, ctx) {
                return ctx.db.role.findMany();
            },
        });
    },
});

export const CompanyMutation = extendType({
    type: 'Mutation',
    definition(t) {
        // create a new company
        t.nonNull.field('createCompany', {
            type: 'Company',
            args: {
                id: intArg(),
                name: nonNull(stringArg()),
                contactPerson: nonNull(stringArg()),
                bio: nonNull(stringArg()),
                email: nonNull(stringArg()),
                website: nonNull(stringArg()),
                roleId: intArg(),
                roles: arg({
                    type: list('RoleInputType'),
                }),
            },
            resolve(_root, args, ctx) {
                return ctx.db.company.create({
                    data: {
                        name: args.name,
                        contactPerson: args.contactPerson,
                        bio: args.bio,
                        email: args.email,
                        website: args.website,
                        roles: {
                            connect: [{ id: args.roleId || undefined }],
                        },
                    },
                });
            },
        });
        // update a company by id
        t.field('updateCompany', {
            type: 'Company',
            args: {
                id: nonNull(intArg()),
                name: stringArg(),
                contactPerson: stringArg(),
                bio: stringArg(),
                email: stringArg(),
                website: stringArg(),
                roleId: intArg(),
                roles: arg({
                    type: list('RoleInputType'),
                }),
            },
            resolve(_root, args, ctx) {
                return ctx.db.company.update({
                    where: { id: args.id },
                    data: {
                        name: args.name,
                        contactPerson: args.contactPerson,
                        bio: args.bio,
                        email: args.email,
                        website: args.website,
                        roles: {
                            connect: [{ id: args.roleId || undefined }],
                        },
                    },
                });
            },
        });
        // delete a company by id
        t.field('deleteCompany', {
            type: 'Company',
            args: {
                id: nonNull(intArg()),
            },
            resolve(_root, args, ctx) {
                return ctx.db.company.delete({
                    where: { id: args.id },
                });
            },
        });
    },
});

Let's dissect that massive block of code. Starting with the Query block, the queries available to you in the playground are defined using much of the same syntax as when the object itself was defined with fields and resolvers.

// get all companies
t.list.field('companies', {
    type: 'Company',
    resolve(_root, _args, ctx) {
        return ctx.db.company.findMany();
    },
});

The query to get all of the companies uses the GraphQL context to run a prisma query and the method findMany() to return all of the companies in the database. The findMany() method can take optional parameters which are filters on the query, for example to return only the first 10 company in the database you could pass an object with the key take and the value 10 like so:

// get all companies
t.list.field('companies', {
    type: 'Company',
    resolve(_root, _args, ctx) {
        return ctx.db.company.findMany({ take: 10 });
    },
});

This value could be passed into the query as an argument too instead of being hardcoded. Let's look at passing arguments to queries.

To get a company by it's id you'll make use of the second paramter of the resolver function, args.

// get company by id
t.field('company', {
    type: 'Company',
    args: {
        id: nonNull(intArg()),
    },
    resolve(_root, args, ctx) {
        return ctx.db.company.findUnique({
            where: { id: args.id },
        });
    },
});

Here a different method is used on the GraphQL Prisma context, findUnique(). A filter is passed which asks for only companies where it's id matches the id passed in as a parameter. Above the resolver the args types are defined. Here an id is defined as a nonNull integer, that is, a number value that cannot be null. Which makes sense as you wont run this query without actually passing a value to it. If you were to not add the nonNull function the arg would be nullable be default. (Though you can also import nullable from nexus and explicitly state that fact that it is nullable). The roles query works the same way as the get all companies query in that it returns all of the roles related to this company.

Moving onto the mutations and creating a new company in the database.

        // create a new company
        t.nonNull.field('createCompany', {
            type: 'Company',
            args: {
                id: intArg(),
                name: nonNull(stringArg()),
                contactPerson: nonNull(stringArg()),
                bio: nonNull(stringArg()),
                email: nonNull(stringArg()),
                website: nonNull(stringArg()),
                roleId: intArg(),
                roles: arg({
                    type: list('RoleInputType')
                })
            },
            resolve(_root, args, ctx) {
                return ctx.db.company.create({
                    data: {
                        name: args.name,
                        contactPerson: args.contactPerson,
                        bio: args.bio,
                        email: args.email,
                        website: args.website,
                        roles: {
                            connect: [
                                {id: args.roleId || undefined}, 
                            ]
                        }
                    }
                })
            }
        })

Much of this code will now be familiar, the field type is given a logical name (which will be used to run the mutation) and a bunch of args are defined outlining what the resolver can expect and in what format the variables will be passed as. An interesting point to notice here is the roleId, which is the foreign key for the Role type, and the roles arg which uses a custom input type to tell the resolver what type to expect. As the Role isn't a primitive you have to declare a custom type which is used instead. As the plural name suggests, this argument is of type list. The RoleInputType is defined in the role.ts file and defines an id.

The resolver uses the create method on the Prisma context and defines a data object which maps the args passed through to the corresponding object keys. The roles arg uses the connect method and the foreign key to connect the new company to a previously defined role.

Running our queries and mutations in the Playground

In order to actually play about with the queries and mutations run the dev script from the projects root (npm run dev). This will open up a url at localhost:4000. The server has given you a GraphQL playground from which you can run your queries and mutations against the database in real time. This is an excellent way to check how your data behaves in the real world, outside of those console.logs.

Begin by creating a new skill.

mutation CreateSkill {
  createSkill(name: "GraphQL") {
    id
    name
  }
}

Here you are running your createSkill mutation passing in the name of the skill top be created and returning the newly created skills id and name. Next create a role.

mutation CreateRole {
  createRole(name: "Backend Developer" skillId: 1) {
    id
    name
  }
}

The createRole mutation accepts a name argument and an optional skillId, which is the foreign key to the skill you would like to link to the role. In this case you are creating a new Backend Developer role and assigning it the skill of GraphQL via the skills id.

Finally you can create a new company. By taking advantage of the foreign key (roleId) you can link not only a role but certain skills to the company. In this mutation your new company has a Backend Developer role which requires/uses a GraphQL skill.

mutation CreateCompany {
  createCompany(
    name: "My Super Cool Company"
    bio: "A super cool company"
    website: "mycomp.com"
    contactPerson: "Barry McBarry"
    email: "barry@mycomp.com"
    roleId: 1
  ) {
    name
    bio
    website
    contactPerson
    email
    roles {
      name
      skills {
        name
      }
    }
  }
}

Now that your database has some data in it you can query it to see how that data looks when returned.

# get all companies and their roles and skills
query GetCompanies {
  companies {
    id
    name
    contactPerson
    bio
    email
    website
    roles {
      name
      skills {
        name
      }
    }
  }
}

#get all roles and their skills
query GetRoles {
  roles {
    id
    name
    skills {
      name
    }
  }
}

#get all skills
query GetSkills {
  skills {
    id
    name
  }
}

Conclusion

As a predominantly frontend developer using Prisma and combining it with Nexus for the first time has been a relatively painless experience. Of course much of that is due to the excellent documentation which allows you to get up and running quickly and without fuss. Some areas where I did find myself rather confused was nested mutations and relations in the schema. People learn in different ways, I enjoy quite a lot of visuals with pictures forming a better understanding in my head as opposed to just blocks of text. Perhaps the docs could do with some more video instructions and interactive elements. That being said this was quite a text and code block heavy piece itself!

This was the first of many pieces about my journey learning Prisma and what it can do. This article only touched on some base concepts but I found it very helpful in getting a grasp of what is possible. My take away from this piece is that I need to dive deeper into relationships and how they are used as this seems to be a focal point of what you can do with Prisma.

Hit me up on Twitter @studio_hungry if you fancy a chinwag about any of this.

How to plan articles in 3 steps

Richard Haines — Wed, 17 Feb 2021 18:54:47 +0000

I've been trying to develop a more concise way to structure my article before I write them. That is, the process I go through before I even open vscode and start typing away.

This is a high-level view of my process that I would like to share as I've found it quite productive. It isn't some revolutionary new way of doing things. I had a google, read what other people had done, and made a patchwork copy to suit my style of doing things. Maybe you'll be able to take something from it that will help you.

Making notes before you start

This may seem obvious but it's quite essential to get your head in the right place and not have wild thoughts taking over as you write. By taking notes when you are learning "the thing" and having them available pre-writing, you're saving yourself time and headaches later. Once you have your notes you are ready to begin the process of brainstorming your article.

The pre-writing steps

I like to use Notion to configure my plan before I begin writing. The flow goes something like this:

Step 1:

Collect knowledge through doing the thing
List out all the headers as high-level topics - unordered (Notion allows you to drag and reorder everything because it's all built on blocks 😎)

Step 2:

The article should begin by answering the question: What is this article for? Not literally, but posing a question around the article's main topic and giving a short, concise answer draws the reader in while giving them a brief overview of what to expect.
Pick a title that is clear and descriptive
The first paragraph of every section should support the title and add context
Organize the headers so that they are in order and they flow. It could mean deleting any that no longer make sense.

Step 3:

Go through each step and add content. The content should support the heading and add context so that the reader can follow along.

Once I have my headers in order and have written a short paragraph for each one, I switch over to vscode and begin laying out the article. I find this method of planning enables me to focus on what I need to convey to the reader for them to get the most from what I'm writing.

Notes on react-three-fiber

Richard Haines — Tue, 09 Feb 2021 19:03:33 +0000

Originally published on my blog

This is a collection of notes im putting together to better understand how to work with 3D stuff in React. Im writing it as to myself, as that's who it is for, but if others find it useful then that's cool too. But it's not written as a tutorial or anything. Fair warning!

Setup

Install:

yarn add react-three-fiber three @react-three/drei

Set whole page to fill 100% width and height

* {
  box-sizing: border-box;
}

html,
body,
#root {
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 0;
}

What is all this stuff

The Canvas component renders threejs elements, not DOM elements. It takes the whole height and width of it container, so that is why, if you want to do a whole page 3D rendering of something then you need to set the containers (in our case the actual body, as we are only doing one page) width and height to 100%.

We cant directly use HTML elements within the Canvas though there is a way to do that which I will go over later.

Because the Canvas component renders threejs elements we can use stuff like mesh, sphereGeometry and meshStandardMaterial amongst many others. It provides all these via its context to any children rendered within it, translating the threejs API into React components that can be used as normal so we can also pass props to these elements/components too.

mesh, geometry and material

A mesh is like the base skeleton an object is made from, like a wire frame or modal.

The geometry is the shape the mesh will take and the material is what will cover the mesh, how it will look. You can use different types of materials which change the way you can interact with the object and how it behaves.

There are lots of different geometry and materials that can be used directly in Canvas like a HTML element. Such as meshStandardMaterial or sphereGeometry.

The attach prop on the geometry and material above attaches the element to its parent, in this case the mesh as the set value. So the sphereGeometry is attached to th4e mesh as the geometry and the meshStandardMaterial is attached to the mesh as the material.

Constructor arguments are passed with the args prop. The sphereGeometry takes a number of constructor args, the first three of which are the radius, width and height. See the SphereGeometry docs on threejs for more information. As an example, the constructor args for the sphere are:

radius — sphere radius. Default is 1.
widthSegments — number of horizontal segments. Minimum value is 3, and the default is 8.
heightSegments — number of vertical segments. Minimum value is 2, and the default is 6.
phiStart — specify horizontal starting angle. Default is 0.
phiLength — specify horizontal sweep angle size. Default is Math.PI * 2.
thetaStart — specify vertical starting angle. Default is 0.
thetaLength — specify vertical sweep angle size. Default is Math.PI.

Lights

If no sources of lights are provided then the object will be black. Which makes sense as without light we wouldn't be able to see ti in real life. A list of the light sources taken from a smashing magazine article:

Point. Possibly the most commonly used, the point light works much like a light bulb and affects all objects in the same way as long as they are within its predefined range. These can mimic the light cast by a ceiling light.
Spot. The spot light is similar to the point light but is focused, illuminating only the objects within its cone of light and its range. Because it doesn’t illuminate everything equally as the point light does, objects will cast a shadow and have a “dark” side.
Ambient. This adds a light source that affects all objects in the scene equally. Ambient lights, like sunlight, are used as a general light source. This allows objects in shadow to be viewable, because anything hidden from direct rays would otherwise be completely dark. Because of the general nature of ambient light, the source position does not change how the light affects the scene.
Hemisphere. This light source works much like a pool-table light, in that it is positioned directly above the scene and the light disperses from that point only.
Directional. The directional light is also fairly similar to the point and spot lights, in that it affects everything within its cone. The big difference is that the directional light does not have a range. It can be placed far away from the objects because the light persists infinitely.
Area. Emanating directly from an object in the scene with specific properties, area light is extremely useful for mimicking fixtures like overhanging florescent light and LCD backlight. When forming an area light, you must declare its shape (usually rectangular or circular) and dimension in order to determine the area that the light will cover.

Spheres with different materials.

The code for all three

<Canvas>
  <mesh
    visible // object gets render if true
    userData={{ test: "hello" }} // An object that can be used to store custom data about the Object3d
    position={[0, 0, 1]} // The position on the canvas of the object [x,y,x]
    rotation={[0, 0, 0]} // The rotation of the object
    castShadow // Sets whether or not the object cats a shadow
    // There are many more props.....
  >
    {/* A spherical shape*/}
    <sphereGeometry attach="geometry" args={[1, 16, 16]} />
    {/* A standard mesh material*/}
    <meshStandardMaterial
      attach="material" // How the element should attach itself to its parent
      color="#7222D3" // The color of the material
      transparent // Defines whether this material is transparent. This has an effect on rendering as transparent objects need special treatment and are rendered after non-transparent objects. When set to true, the extent to which the material is transparent is controlled by setting it's .opacity property.
      roughness={0.1} // The roughness of the material - Defaults to 1
      metalness={0.1} // The metalness of the material - Defaults to 0
    />
  </mesh>
  {/*An ambient light that creates a soft light against the object */}
  <ambientLight intensity={0.5} />
  {/*An directional light which aims form the given position */}
  <directionalLight position={[10, 10, 5]} intensity={1} />
  {/*An point light, basically the same as directional. This one points from under */}
  <pointLight position={[0, -10, 5]} intensity={1} />
  {/* We can use the drei Sphere which has a simple API. This sphere has a wobble material attached to it */}
  <Sphere visible position={[-3, 0, 1]} args={[1, 16, 16]}>
    <MeshWobbleMaterial
      attach="material"
      color="#EB1E99"
      factor={1} // Strength, 0 disables the effect (default=1)
      speed={2} // Speed (default=1)
      roughness={0}
    />
  </Sphere>
  {/* This sphere has a distort material attached to it */}
  <Sphere visible position={[3, 0, 1]} args={[1, 16, 16]}>
    <MeshDistortMaterial
      color="#00A38D"
      attach="material"
      distort={0.5} // Strength, 0 disables the effect (default=1)
      speed={2} // Speed (default=1)
      roughness={0}
    />
  </Sphere>
</Canvas>

Drei

Drei (three in german) is a super helpful package that contains loads of helpers and abstractions for react-three-fiber. One thing that I noticed was that using drei with Nextjs (as this site does) will throw an error when trying to import stuff - cannot use import statement outside a module. This is because Nextjs uses common js modules on server side rendering. We can use withTM from next-transpile-modules in the next.config file to transpile the common js stuff in drei. We also need to dynamically import the component using the drei components and disable server side rendering. See this issue and this PR.

If you are using Nextjs....

import dynamic from "next/dynamic";
const ThreeBall = dynamic(
  () => import("./../../src/components/post/three-ball"),
  { ssr: false }
);

next.config.js

const withTM = require("next-transpile-modules")([
  "three",
  "drei",
  "postprocessing",
]);

module.exports = withTM();

The main players

The Renderer in react-three-fiber(R3F) is the HTML canvas element which gets added dynamically to the DOM unless specifically added via an id or className.

The scene is the stage where everything plays out. The meshes encompass lights, groups, 3D positions and cameras. A scene can be thought of as a theater scene where the mesh or groups of meshes are the act that will play out, the lights give the mesh and its geometry and materials a purpose on the scene, they light them from angles and provide context to why they are there. The cameras and positions allow us to view them all from different angles.

A handy canvas component

I made a handy canvas component which i use to render any 3D stuff i want. It takes advantage of Chakra-ui but the styles can just as easily be used inline with a style tag or added from a CSS file.

import React, { Suspense } from 'react';
import { Canvas } from 'react-three-fiber';
import { Box } from '@chakra-ui/core';

/**
 * A container with a set width to hold the canvas.
 * @param {String} width - The width of containing element
 * @param {String} height - The height of containing element
 * @param {Array}  position - The position of the camera, [x, y, z] axis.
 * @param {Number} fov - The field of view of the camera. The higher the number, the further away the view
 * @param {Number} zoom - If the camera should be zoomed in. Provide a number. Defaults to 1.
 * ...rest = any styles you want to apply to the containing div
 */
const CanvasContainer = ({
  width,
  height,
  position,
  fov,
  zoom,
  children,
  ...rest
}) => {
  return (
    <Box height={height} width={width} {...rest}>
      <Canvas
        colorManagement
        camera={{
          position,
          fov,
          zoom,
        }}
      >
        <Suspense fallback={null}>{children}</Suspense>
      </Canvas>
    </Box>
  );
};

export default CanvasContainer;

Models

Working with models is very fun, and fairly painless using the tools the the Poimandres team have put together. Generally speaking you are going to be working with GLTF which is a specification for loading 3D content. It accepts both JSON (.gltf) or binary (.glb) formats. Instead of storing a single texture or assets like .jgp or .png, gltf packages up all that is needed to show the 3D content. That could include everything from the mesh, geometry, materials and textures. For more information checkout the Three docs.

You can use a package called gltfjsx which will take a gltf file which has to be stored in your public folder and then read that and create a React component out of it for you. If your gltf model has animations then the package will handle that for you too, creating the animations logic right inside the component. We can take an example, one of the birds from the Three repository examples.

The code for this bird is auto generated for us. It looks like this:

/*
auto-generated by: https://github.com/pmndrs/gltfjsx
*/
import React, { useRef, useState, useEffect } from "react";
import { useFrame } from "react-three-fiber";
import { useGLTF } from "@react-three/drei/useGLTF";
import * as THREE from "three";
import { PerspectiveCamera } from "@react-three/drei";

export default function Stork(props) {
  const group = useRef();
  const { nodes, materials, animations } = useGLTF("/stork.glb");

  const actions = useRef();
  const [mixer] = useState(() => new THREE.AnimationMixer());
  useFrame((state, delta) => mixer.update(delta));
  useEffect(() => {
    actions.current = {
      storkFly_B_: mixer.clipAction(animations[0], group.current),
    };
    actions.current.storkFly_B_.play(); // To play the animation we have to call the play method
    return () => animations.forEach((clip) => mixer.uncacheClip(clip));
  }, [animations, mixer]);
  return (
    <group ref={group} {...props} dispose={null}>
      <PerspectiveCamera makeDefault position={[-10, 50, 250]} />
      <hemisphereLight args={["white", 2, 2]} />
      <spotLight
        intensity={0.2}
        position={[20, 25, 14]}
        angle={0.15}
        penumbra={1}
        castShadow
      />
      <mesh
        material={nodes.mesh_0.material}
        geometry={nodes.mesh_0.geometry}
        name="mesh_0"
        morphTargetDictionary={nodes.mesh_0.morphTargetDictionary}
        morphTargetInfluences={nodes.mesh_0.morphTargetInfluences}
      />
    </group>
  );
}

useGLTF.preload("/stork.glb");

A handy model component

I made a handy gtlf model component too. This component accepts a number of props such as the path to the models .gltf file, the position the model should take up on the canvas, its rotation which is added in the Vector3 array format of [x, y, z] and any additional props to be passed onto the models mesh.

import React from 'react';
import { useGLTF } from '@react-three/drei';
import { useFrame } from 'react-three-fiber';

/**
 * A basic gltf modal renderer component.
 * @param {String} scenePath - The path to the scene file. Should be kept in the public folder
 * @param {Array} position - The position on the canvas the model should take
 * @param {Array} rotation - Optional rotation of the model. If provided [x, y, z] values are mapped to the useFrame hook which will rotate the model in the given direction(s)
 */
const GLTFModal = ({ scenePath, position, rotation, ...rest }) => {
  const gltf = useGLTF(scenePath, true);
  const mesh = React.useRef();
  useFrame(() =>
    rotation
      ? ((mesh.current.rotation.x += rotation[0]),
        (mesh.current.rotation.y += rotation[1]),
        (mesh.current.rotation.z += rotation[2]))
      : null,
  );
  return (
    <mesh castShadow ref={mesh} {...rest} position={position}>
      <primitive object={gltf.scene} dispose={null} />
    </mesh>
  );
};

export default GLTFModal;

It's then used like this:

  <GLTFModal
    scenePath="/scene.gltf"
    position={[0, -1, 0]}
    rotation={[0, 0.01, 0]}
  />

Load a custom font in Gatsby

Richard Haines — Tue, 09 Feb 2021 18:58:14 +0000

To load a custom font in a Gatsby project you will need to create a gatsby-ssr.js file and use the onRenderBody function. This will allow you to append a link to the sites head.

gatsby-ssr.js

const React = require("react");
export const onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    <link
      rel="stylesheet"
      href="https://indestructibletype.com/fonts/Jost.css"
      type="text/css"
      charset="utf-8"
    />
  ]);
};

// Can then be accessed like: font-family: Jost in your code

How to seed a postgres database with node

Richard Haines — Tue, 09 Feb 2021 18:54:48 +0000

This guide was originally posted on my blog richardhaines.dev

This guide will walk through seeding a Postgres database. It will cover creating a Node script to seed the data and touch on some of the pros and cons as to the chosen approach.

The source code for this guide can be found here: github.com/molebox/seed-postgres-database-tutorial

Prerequisites

You must have Postgres installed on your machine
You must have Node installed on your machine
It is assumed that you have Postgres setup and know-how to access its databases, though the guide will cover some basic commands towards the end.
This guide uses the default user postgres for accessing the database. If you have another user account you would prefer to use then swap in that.

The guide uses version 13.1 of Postgres and version 14.15.1 of Node. It was developed on a Windows machine.

What do we mean by seed?

The process of seeding (in the context of databases) is to insert or populate the initial data into the database. This can be either a manual or automated step in the setup of an application. Seeding can be used when testing different branches, for example, if you have a dev branch where you want to test some new sorting query against the database, seeding would be a good way to test against data that won't affect a production build. Of course, there are many reason one might choose to seed a database. In some instances, an applications database requires some form of data present before it will work properly, such as an admin account. But more often than not seeding would take place pre-install and thus allow the user to begin using the app without any issues.

The seed script

The seed script will aim to accomplish the following:

Create a database with a table.
Create a csv file and populate it with fake data using the faker library. It will default to 10 rows but allow the user to specify an amount if they like.
Parse that data and insert it into the table - seed the database.

Begin by creating a schema.sql file at the root of your project. This file will enable you to lay the groundwork for how your database and its table will look.

schema.sql

-- Seeing as we will be testing out this script alot we can destroy the db before creating everything again
DROP DATABASE IF EXISTS translationsdb;

-- Create the db
CREATE DATABASE translationsdb;

-- Move into the db
\c translationsdb

-- Create our table if it doesn't already exist
CREATE TABLE IF NOT EXISTS Translations
(
    key character varying(100),
    lang character varying(5),
    content text
);

-- Changes the owner of the table to postgres which is the default when installing postgres
ALTER TABLE Translations
    OWNER to postgres;

db.js

To interact with the Postgres database, you can install the node-postgres package, a collection of modules made for interacting with Postgres. You'll use it to establish an initial connection to the database and insert some fake data. Create a new file src/db.js and add the following:

const { Pool } = require('pg');
const { host, user, database, password, port } = require('./config');

// Create a pool instance and pass in our config, which we set in our env vars
const pool = new Pool({
    host,
    user,
    database,
    password,
    port,
});

module.exports = {
    query: (text, params, callback) => {
        return pool.query(text, params, callback);
    },
    connect: (err, client, done) => {
        return pool.connect(err, client, done);
    },
};

The Pool class takes some optional config and the values passed in enable a connection with the database. They are set as environment variables (env vars) and imported from a separate config file. This file exports two functions. The query, which will be used to run an INSERT statement, and a connect function which will be used to connect to the database.

config.js

Storing all the env vars in one place and exporting them means you have one source of truth and can easily swap them out from one place instead of multiple files. Create a new file and name it config.js.

const dotenv = require('dotenv');
dotenv.config();
// Single source to handle all the env vars
module.exports = {
    host: process.env.PGHOST,
    user: process.env.PGUSER,
    database: process.env.PGDATABASE,
    password: process.env.PGPASSWORD,
    port: process.env.PGPORT,
};

An example of how your env vars might look:

PGUSER=postgres
PGHOST=localhost
PGPASSWORD=test1234
PGDATABASE=translationsdb
PGPORT=5432

main.js

In a real-world scenario, you would perhaps have some data stored in a csv file. This example will make use of the faker library, and some other packages. Install the following:

yarn add dotenv faker fast-csv minimist pg validator

Use the Faker library by creating a function that will mimic the shape of the table set in schema.sql. It will return a template literal string to be added to a csv file later on.

const faker = require('faker');

// Create some fake data using the faker lib. Returns a template string to be inserted into a csv file as a single line
function createTranslation() {
    const key = faker.address.country();
    const lang = faker.address.countryCode();
    const content = faker.random.word();

    return `${key},${lang},${content}\n`;
}

Next, you will need to import fs and create a stream. This will write to an as yet non-existent csv file.

// other imports..
const fs = require('fs');

// The path to write the csv file to
const output = './src/output.csv';

// other functions..

// Create a stream to write to the csv file
const stream = fs.createWriteStream(output);

Enabling the user to choose how many rows they would like to seed the database with is an extra and worthwhile step. The minimist package helps with parsing argument options. In the case of the script, it allows the user the option to pass in an amount, if the user chooses not to pass any additional arguments then you can set a default value. Create a new function that will write the fake data to the csv file.

// other imports..
const args = require('minimist')(process.argv.slice(2));

// other functions...

async function writeToCsvFile() {
    // The user can specify how many rows they want to create (yarn seed --rows=20), if they dont specify anything (yarn seed) then defaults to 10
    let rows = args['rows'] || 10;
    // Iterate x number of times and write a new line to the csv file using the createTranslation function
    for (let index = 0; index < rows; index++) {
        stream.write(createTranslation(), 'utf-8');
    }
    stream.end();
}

Now that the csv file is created and populated with fake data, you can begin the process of actually seeding that data into the Postgres database. fast-csv is a library for parsing and formatting csv files. You'll use it in combination with the validator library and node-postgres.

// other imports...
const fastcsv = require('fast-csv');
const db = require('./db');
const contains = require('validator/lib/contains');

// other functions...

function insertFromCsv() {
    let csvData = [];
    return (
        fastcsv
            .parse()
            // validate that the column key doesn't contain any commas, as some countries do. This will break our insertion as it would be treated as an extra column and our table expects only 3 columns
            .validate((data) => !contains(data[0], ','))
            // triggered when a new record is parsed, we then add it to the data array
            .on('data', (data) => {
                csvData.push(data);
            })
            .on('data-invalid', (row, rowNumber) =>
                console.log(
                    `Invalid [rowNumber=${rowNumber}] [row=${JSON.stringify(row)}]`
                )
            )
            // once parsing is finished and all the data is added to the array we can then insert it into the db table
            .on('end', () => {
                // The insert statement
                const query =
                    'INSERT INTO translations (key, lang, content) VALUES ($1, $2, $3)';
                // Connect to the db instance
                db.connect((err, client, done) => {
                    if (err) throw err;
                    try {
                        // loop over the lines stored in the csv file
                        csvData.forEach((row) => {
                            // For each line we run the insert query with the row providing the column values
                            client.query(query, row, (err, res) => {
                                if (err) {
                                    // We can just console.log any errors
                                    console.log(err.stack);
                                } else {
                                    console.log('inserted ' + res.rowCount + ' row:', row);
                                }
                            });
                        });
                    } finally {
                        done();
                    }
                });
            })
    );
}

The function first validates the contents of the row using the contains function from the validator library. This is necessary because some countries can have an extra comma in their name. An extra comma in a csv file equates to an extra column and the table created and defined in the schema.sql file dictates that only 3 columns will exist. If this check fails fast-csvwill not accept the row and throw an event, which is used to print a message to the console to inform the user.

If the row is accepted then it is added to an array. Once the parsing is finished and all the row data is added to the array the connection is established with the Postgres database. The data array is then iterated over, for each row in the array a client instance is acquired from the pool and an INSERT query is used as an argument, along with the row data. If the row is successfully inserted into the table then its corresponding data is printed to the console, if any errors occur they are also printed to the console. Finally, the done function is called to release the clients back to the pool.

The final function called seed is where the data is written to the csv file, a stream is created to read the data from the output file and then the INSERT function is piped to the stream.

// all the other code from main.js

async function seed() {
    await writeToCsvFile();
    let stream = fs.createReadStream(output);
    stream.pipe(insertFromCsv());
}

seed();

Add two scripts to the package.json file. The first create-db will ask the user to login and connect to their Postgres database and then run the commands in the schema.sql file. The second script will run the first before running the seed function.

The user may run the script with additional arguments to set the number of rows created in the table.

Extra rows: yarn seed --rows=200
Default 10 rows: yarn seed

  "scripts": {
    "create-db": "psql -U postgres < schema.sql",
    "seed": "yarn create-db && Node src/main.js"
  },

Check the database

To check the database table you can run the following commands from your terminal:

// login and connect to the database
psql -U postgres -d translationsdb

// get all the rows in the table
select *  from "translations";

Final thoughts

There are many ways this could have been accomplished, in fact, there are many libraries that support using Node with Postgres. This method was chosen for its relative simplicity. It's not a generic solution that would fit all scenarios but it could be built upon to incorporate extra features.

Positive take-aways

The fact that no external API was used for the data removed the overhead of having to make any requests.
Using Nodes inbuilt process.argv combined with a small parser library meant the user could add some level of configuration when seeding.

Possible improvements

The function that creates the fake data could be added via config to match the schema definition of the table.
It would also work quite nicely with a CLI, this would enable the end user much more configuration.

Portfolio Challenge: Layout and Animate a Swiss Style Poster

Richard Haines — Thu, 21 Jan 2021 15:51:26 +0000

Often times when im looking for layout inspiration I find myself checking out old graphic design books I have laying around the house or old movie posters, which I used to collect. I find that with posters the creator has to be clever with their use of space and this leads to some wonderful shapes and arrangements.

There is a website by the artist Mike Joyce called swissted.com that has a plethora of amazing posters with intricate and exciting layouts. I highly recommend checking it out if you want to get inspiration or just have a layout you want to practice.

This tutorial will cover the re-creation of a poster with straight up HTML, CSS and JavaScript. We'll use [GSAP](https://greensock.com/) to animate elements of our poster and also learn how to load a custom font. The poster in question can be seen below, it is created by Mike Joyce and taken from their site.

The finished project can be view here: css-grid-and-gsap-poster-layout.netlify.app.

The source code can be viewed here: github.com/molebox/css-grid-and-gsap-poster-layout

We are not going to need to install anything, open vscode (or your choice of IDE) and create the following:

A font folder
A styles folder. Inside here create an index.scss file
An index.html file
An index.js file

We'll be making use of an extension called live server, I suggest installing that as a vscode extension. It will enable you to check on your progress with live updates on every file save.

Html

Let's begin by scaffolding out our html page.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Bring a poster to life with CSS grid and GSAP</t
itle>
    <link rel="stylesheet" href="./styles/index.css">
</head>
<body>
    <!-- main container -->
    <div class="outer-container">

        <!-- grid layout -->
        <main class="main-grid">

            <!-- the top info text -->
            <section class="info-section">

                <!-- text on the left -->
                <section class="section-left">

                </section>

                <!-- text on the right -->
                <section class="section-right">

                </section>

            </section>

            <!-- the main title section -->
            <section class="title-section">

                <!-- the main title -->
                <h1 class="title">pixies</h1>

                <!-- the subtitle -->
                <section class="subtitle">

                </section>

            </section>

            <!-- circles grid layout -->
            <section class="circles-grid">

            <!-- our circles will be added dynamically -->

            </section>

        </main>
    </div>

    <script src="index.js"></script>
</body>
</html>

We begin by linking our index.cssfile in the header and doing the same with our index.js at the bottom of the body tag. We have given our htmla basic structure of how we want the poster to be laid out.

Styling

Before we start implementing our classes to define how our poster will look we can do a global reset of the margin, padding and box size. We'll also add our posters colours as css variables so that we can access them within our file in differtent places without having to repeat ourselves.

/* global reset */
* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

:root {
    --white-color: #dee2d5;
    --green-color: #5ebd44;
}

Thinking about our poster we will want it to have the shape of a poster, that means that it wont take up the whole width of our viewport. The outer-container class will take care of sizing our poster.

outer-container

/* set this to the dimensions of an A4 sheet of paper */
.outer-container {
    max-width: 21cm;
    height: 100vh;
    margin: 0 auto;

    background-color: var(--green-color);
    overflow: hidden;
}

After a little googling I found that the size of an A4 sheet of paper is roughly 21cm so we set that to the width of our poster. We want it to be the height of the viewport and the margin centers our content. We have set the overflow to hidden as we will be doing some positioning later on and this will hide some of the overflowing elements.

main-grid

Looking at the poster we could go for a flexbox layout and use a direction of column, stacking all the elements vertically. That would be a viable solution, but to have a little more control over the size of each column and its placement we can instead use the grid. We are setting an explicit height on the top section and the title section then saying the rest (which is made up of the circles) should take up the rest of the available space, or 1 fractional unit.

.main-grid {
    display: grid;
    grid-template-rows: 50px 200px 1fr;
}

info-section

The top section of the poster, with the two paragraphs of text will also utilize the grid. Flexbox would indeed be a good solution here, we could have used justify-content: space-between and then a padding on the horizontal of each text section to push them to the edges of the pages but with some padding from the actual edge. In keeping with using grid however, we can use a nifty feature of the autocloumn size to set a defined width on the elements on the edges but an auto size in between, pushing the outer elements apart. The left and right section of text use flexbox with a direction of column.

.info-section {
    grid-row: 1;
    display: grid;
    grid-template-columns: 300px auto 300px;
    padding: 1em;

    p {
        font-size: 0.8em;
    }

    .section-left {
        grid-column: 1;
        display: flex;
        flex-direction: column;
        padding: 1em;
    }
    .section-right {
        grid-column: 3;
        display: flex;
        flex-direction: column;
        padding: 1em;
    }
}

title-section

We are on a roll with grid! Let's use another one. Here we will be defining the width of each text section whilst also setting the rows height to that of the given second section in the main-grid class. The subtitle, that is, the text on the right which is split into three rows, was a little more fiddly to get right. Our final result is ok but it's not 100% acurate.

Due to the size of the title text on the left we use a cheeky margin-top to push the three rows down a tad, this gives our eyes the impression that these three rows are centered to the big text on the left. That's not actually true due to the dots on the i raising the height of the title text.

.title-section {
    grid-row: 2;
    display: grid;
    grid-template-columns: 400px auto 300px;
    grid-template-rows: 200px;
    align-items: center;
    padding: 1em;
    height: 100%;

    .title {
        grid-column: 1;
        font-size: 10em;
        font-weight: 500;
        letter-spacing: 3px;

    }
    .subtitle {
        grid-column: 3;
        color: var(--white-color);
        display: flex;
        flex-direction: column;
        padding: 1em;
        font-size: 1.3em;
        font-weight: 100;
        justify-content: space-evenly;
        height: 150px;
        margin-top: 1em;
    }
}

circles-grid

Our final class is the most "complicated". If we take a look at the original poster we can count how many circles we see, it's an 11x11 grid. The repeat() function allows us to set a repeating pattern of sizes in one short statement. For the columns we are saying that there should be 11 columns, each taking up the available space until they reach each end of the perant container. We do the same for the rows except that we explicitly state the height of the rows so that the child elements sizing more closely resemble that of the original poster.

Remember we set the overflow: hidden on the outer-cointainer? Here we can see why. When looking at the original poster we can see the circles on the horizontal edges are cut off, they are semi-circles. Now, rather than creating some special semi-circle shapes we set the width of this section (this grid) to be slightly larger than the parent container, and by hiding the overflow we give the illusion that the circles are semi-circles contained within our bounderies.

We use another little trick with the before pseudo element to give the illusion that the top of the grid is cut off and thus the circles look like semi-circles. The pseudo element here is creating a 20px high block which has the same colour as the poster. It's got an absolute position and lays on top of the circles-grid.

The nested circle class is the base circle that will be used to generate a circle dynamically using JavaScript. The white-circle will be used as an override to colour the white circles on the poster.

.circles-grid {
    grid-row: 3;
    display: grid;
    grid-template-columns: repeat(11, 1fr);
    grid-template-rows: repeat(11, 65px);
    place-items: center;
    background-color: black;
    min-width: 23.5cm;
    position: relative;
    left: -5.25%;

    // add a pseudo element to cut off the top of the grid
    &:before {
        content: '';
        width: 100%;
        height: 20px;
        background-color: var(--green-color);
        position: absolute;
        top: 0;
    }

    .circle {
        border-radius: 50%;
        width: 60px;
        height: 60px;
        background-color: var(--green-color);
    }
    /* when we add this to the circle class it will override the bg-color */
    .white-circle {
        background-color:  var(--white-color);
    }
}

Adding the text to the Html

We can now add the text we see on the poster to our sections on the html page.

                        <!-- the top info text -->
            <section class="info-section">
                <!-- text on the left -->
                <section class="section-left">
                    <p>saturday</p>
                    <p>december 13 1986</p>
                    <p>9 pm over 21</p>
                </section>
                <!-- text on the right -->
                <section class="section-right">
                    <p>at the rat</p>
                    <p>528 commonwealth</p>
                    <p>boston, mass.</p>
                </section>

            </section>
            <!-- the main title section -->
            <section class="title-section">
                <!-- the main title -->
                <h1 class="title">pixies</h1>
                <!-- the subtitle -->
                <section class="subtitle">
                    <p>with</p>
                    <p>throwing muses</p>
                    <p>big dipper</p>
                </section>
            </section>

Bringing it all together

If you havent already, start the live server by clicking the go live that sits on the bottom of vscode. You will see that we have our top two section but no circles are displayed yet. That is because we are going to create then dynamically and have them whizz onto the poster using some gsap magic.

But before we go ahead and do that, let's add out cusomt font. If we check the swissed site we can read that Mike Joyce uses the same font for all the posters, Berthold Akzidenz-Grotesk. The font can be downloaded from here: www.azfonts.net/load_font/berthold-akzidenz-grotesk-be-medium.html. This will give you the font in ttf format. We will want to convert that to woff (see here and here) We can do the conversion online via fontsquirrel.com/tools/webfont-generator.

Now that we have our font in woff format we can drag both the woff and woff2 fonts to our font folder. Then inside the index.scss folder we can load the font using @font-face. We can then add the font family to the outer-containerclass which will cascade down to the elements that use text.

/* load font */
@font-face {
    font-family: 'berthold_akzidenz_grotesk_bRg';
    src: url('../font/berthold-akzidenz-grotesk-be-medium-webfont.woff2') format('woff2'),
         url('../font/berthold-akzidenz-grotesk-be-medium-webfont.woff') format('woff');
    font-weight: normal;
    font-style: normal;
}

.outer-container {
        ...other stuff
    font-family: 'berthold_akzidenz_grotesk_bRg';
}

Next we need to import gsap into our project. We'll use the CDN. At the bottom of the body tag add these two script tags above the script that imports our own js file.

<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.5.1/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.5.1/EasePack.min.js"></script>

index.js

We have created space for our circles on our poster, in fact we have even given them a lovely grid to sit in. But they don't exist yet, let's change that.

First we can grab a reference to our circel-grid then we will be creating an array of circles that matches the grid dimentions we specified earlier (11x11). From each element we will create a div and attach our circleclass.

// get the circle grid from the DOM
let circleGrid = document.querySelector(".circles-grid");

// create 121 (11x11) circle elements and attach the circle class
const circles = Array.from(Array(121)).map((circle) => {
    // create the circle as a div
    circle = document.createElement("div");
    // attach the css class
    circle.className = 'circle';
    return circle;
});

The next step is for us to figure out which circles will be white and which wont so that we get that triangle effect. I took the liberty of counting these out so you can relax! Lets add a new whiteCirclesIndices array to our file. We will use this by looping over our newly created circles array and checking if the indexes match up, if they do we will override the circle class with the white-circle class. We then add all of our circles to the circle-grid.

// the indexes of the circles to be displayed as white
const whiteCirclesIndices = [12,23,24,34,35,36,45,46,47,48,56,57,58,59,60,67,68,69,70,71,72,78,,79,80,81,82,83,84,,89,,90,91,92,93,94,95,96,100,101,102,103,104,105,106,107,108];

// add the circles to our circle grid
circles.forEach((circle, index) => {
    // loop over the indexes that should be white
    for (const whiteIndex of whiteCirclesIndices) {
        // if the circles index matches the white index then add the new css class to it. 
        if (whiteIndex === index) {
            circle.classList.add('white-circle')
        }
    }
    // add the circle to the grid
    circleGrid.append(circle)
})

If you have the live server running you should now see the correct font being used and the circles filling up their grid, with a white triangle formed on the left-center of the grid.

Animate!

Posters are cool to look at, but they don't do much else. Us being web devs, we can makes stuff move for no other reason apart from we want too and it will look cool. So lets bring our poster to life!

At the top of our index.js file get the gsap object formt he window. We will then create a timline. Because we are going to be running a few animations one after the other it makes sense to use a timeline as this will fire off the animations sequentially. We'll start be animating in our info-section , title and subtitle sections.

const {gsap} = window;

let TL = gsap.timeline({delay: 0.5});

...creatingCircles...

// animate the intro text down from the top
TL.from(".info-section", {
    y: window.innerHeight * -1,
    duration: 1.5,
    ease: 'elastic.out(1, 1)'
})

// animate the title in from the left
TL.from(".title", {
    x: window.innerWidth * -1,
    duration: 1.5,
    ease: 'elastic.out(1, 1)'
}, "-=1");

// animate the subtitle in from the right
TL.from(".subtitle", {
    x: window.innerWidth * 1,
    duration: 1.5,
    ease: 'elastic.out(1, 1)'
}, "-=1")

We use the timeline variable TL to target the class names of each section we want to animate. We use the from method as that means that we animate from the given values to their originally set positions. Notice the -=1 ? Our timeline runs each of our animations sequentially, that is, one after the other. What we are doing here is saying to the timeline that we want that animation to overlap the previous one by 1 second. This gives our animations a smoother, more natural feel.

Next up we can animate in the grid itself. This won't be anything fancy, a simple opacity will do. The reaosn for this is that in a second we are going to make our circles fly in from an angle and they will be flying onto a black square. It will look alot nicer if the black square appears around the same time they start flying in.

// gentle opacity animation of the grid background
TL.from(".circles-grid", {
    opacity: 0,
    duration: 2,
}, "-=1") // "-=1" will overlap the end of the last tween by 1 second. It makes them appear smoother

Lastly we will bring in our circles. We'll make use of the stagger animation which can take a grid of elements and animate them from which ever way you like. You can explicitly tell it what the grid dimentions are (which we will do) or you can let it guess, seeing as we know our grids dimentions we'll use them. The from property tells the stagger from where the animation should begin. I like random, you can play about with it. You options are:

center
end
edges
random

// stagger and animate in the circles from the bottom left of the poster
TL.from(".circle", {
    y: window.innerHeight * 1,
    x: window.innerWidth * -1,
    duration: 1.2,
    ease: "bounce.out",
    stagger: {
        grid: [11, 11],
        from: 'random',
        amount: 1.5
    }
}, "-=1")

The finished poster

Fin

That as they say, is that. I think we have created a fairly acurate representation of the poster. We have use css grid in different ways, including dynamically populating it. We have looked at how to add a cusotm font to our css and finally we have added some cool animations. This is a great foundation from which to start creating your own animated layouts, everything you have learnt here can be iterated on and scaled up for use in any project.

Create a 3D product landing page with ThreeJs and React

Richard Haines — Wed, 20 Jan 2021 16:17:33 +0000

We are going to be creating a product landing page which will utilize 3D models and particle effects to take product showcasing to a whole new level. The goal of this tutorial is to introduce you to the concepts of working with a 3D environment in the browser, while using modern tooling, to create your own highly performant 3D sites.

The final project can be viewed at 3d-product-page.netlify.app/

And the final code can be viewed at github.com/molebox/3d-product-page

This tutorial assumes some basic knowledge of the following:

React
JavaScript
CSS
The command line

What tools are we using?

Snowpack

We are going to be using snowpack as our build tool. Its a modern tool that is similar to Webpack, but takes a slightly different approach. Instead of bundling our entire application and recompiling on every code change and save, snowpack only rebuilds single files where the changes have been made. This results in a very fast development process. The term used by the snowpack team is unbundled development where individual files are loaded to the browser during development with ESM syntax.

Chakra-ui

Our application will be written in React and use Chakra-ui for styling. Chakra is an accessibility first component library which comes with superb defaults and enables us to build accessible, modular components at speed. Think of styled components with easy theming and composability.

Threejs and react-three-fiber

We will be utilizing Threejs by way of a wonderful React library called react-three-fiber, which allows us to easily interact with Three using common React techniques. The library is a renderer for Three, using it we can skip a lot of mundane work such as scene creation and concentrate on composing our components in a declarative way with props and states.

The renderer allows us to use all of the Three classes, objects and properties as elements in our markup. All classes constructors arguments can be accessed via an args prop. A simple mesh with a box class can be seen below. Don't worry if you don't understand what this means, we will go over everything shortly.

<mesh visible position={[1, 2, 3]} rotation={[0, 0, 0]}>
  <boxGeometry attach="geometry" args={[1, 1, 1]} />
  <meshStandardMaterial attach="material" color="red"/>
</mesh>

MDX

Our page will be rendered in MDX, a format which allows us to write JSX and include React components in markdown files. It's a wonderful development experience and one I hope you will fall in love with once we reach the end of the tutorial.

Install the fun

I have created a handy snowpack template that creates a project with snowpack, chakra and MDX all installed. It also comes with React Router v6 but we wont be using that so will remove that boilerplate.

Open a new terminal and navigate to your desired project folder and run the following which will create our new project. Change my-new-app to your apps name.

npx create-snowpack-app my-new-app --template snowpack-mdx-chakra

Next we can install our projects dependencies.

npm i @chakra-ui/react @emotion/react @emotion/styled framer-motion react-three-fiber three @react-three/drei react-particles-js

Now that we have our dependencies installed we can begin to tear out some of the stuff we wont need. Our landing page will encompass a single page so we can open the mdx-routes.js file and remove the Nav component and the page-two route from the MDXRoutes component. We'll return to this file later to add some styling but for now we can move on.

Inside the pages folder delete page-two and remove the contents from page-one. Inside the components folder delete the emoji component and add a new folder called 3d. And that's it, we are now ready to begin coding some sick 3D landing page goodness!

The layout

Open the mdx-layout.js file located in the components folder. This will wrap our whole app, in our case our one landing page. Our page will consist of a css grid, we'll use grid areas to get a nice visual representation of how our page will layout. Remove what is currently in there and add the following.

import React from 'react';
import { Flex, Grid } from '@chakra-ui/react';

const desktop = `
'edge   .       .         .'
'edge   text    product   .'
`;

/**
 * The base layout for the MDX pages. You can configure this to set how your pages layout should be.
 */
const MDXLayout = ({ children }) => {
  return (
    <Grid
      templateColumns="10% 1fr 1fr 10%"
      templateRows="10% 1fr 1fr"
      templateAreas={desktop}
      bg="brand.background"
      h="100vh"
    >
      {children}
    </Grid>
  );
};

export default MDXLayout;

Using Chakras Grid component we set the amount of columns to have a responsive padding of 10% of the viewport width on each side of two flexible one fractional units of space. This basically means that the meat of our page will live in the two fractional columns, with each taking up as much space as they need before they hit the 10% padding on each side. Our rows follow the same logic except we save 10% for our header row and the rest takes up as much space as needed. As you can see, we have a background color set on the bg (background) prop. But where does that value come from and what does it mean?

Open the theme.js file located in the src folder. This is our global theme for our app. We are importing the default theme from Chakra, which itself uses the Tailwind default preset. We are then overriding the colors with our own brand colors. The font sizes are also being overridden to allow us to use slightly different sizes to the default. Go ahead and copy the following colors object into the file instead of the current one.

colors: {
    ...theme.colors,
    brand: {
      red: '#ed1c24',
      lightGrey: '#D6D6D6',
      background: '#090d12',
      text: '#FFFfff',
    },
  },

Components in MDX

MDX is just markdown that you can write JSX in. So that means that we can write normal markdown like so:

# This is a header!

But we can also add to that React components We can even compose React components right in the MDX file! Let's open up the index.js file in the src folder and check out how we can add components to our MDX file without using imports.

Let's break down what's going on in here. If we scroll to the bottom we can see an MDXProvider wrapping our app. It accepts a components prop into which we have passed a components object declared above. The components object allows us to map React components to markdown elements as well as passing in custom components for use in our MDX files. As you can see, this template has set this all up for us by mapping some basic markdown elements to some Chakra components. Where there is no object key we have passed in a custom component which can be used in the MDX file without importing it as you would in a normal js or jsx file.

MDX accepts a special key called wrapper which will wrap the entire file with whatever is passed to it. In our case it will take our previously created layout component along with it's grid and use that to wrap our MDX file. Now that we know where the components are coming from when using them in our MDX file, let's go ahead and write some React in markdown!

The header

Opening up the page-one.mdx file located in the pages folder, add the following.

<Flex gridArea="edge" gridRow="1" justify="center" align="center" ml={6} as="header">
  <Image
    w="100px"
    src="https://www.transparentpng.com/thumb/nike-logo/Blc12i-red-nike-logo-clipart-png-photos.png"
    alt="Red Nike Swoosh Logo"
  />
</Flex>

We are using the Flex component provided to us from Chakra via the MDXProvider. This component allows us to quickly apply flex box props to the base element, a div. Even though the component is based upon a div we can give it semantic meaning by utilizing the as props and setting it the header. If we check our layout file again and look at our grid areas we can see that we have edge on the first and second rows. So we have set the grid area to edge and the row to 1.

This places our component in the top left hand corner of the page. We have given it a margin-left (ml) so that it doesn't hit the edge. As you can see from the code block above, we are inserting an image. If you navigate to this url you will see that it's a Nike swish (swoosh, tick? I dunno)

The copy

Let's add some copy to our page. This will be in the first column of our two middle columns. It will hold the title to our page and some copy about the Nike Air Jordan 1's, the product we are showcasing. Directly below the first Flex code block in the page-one.mdx file add the following:

<Flex
gridArea="text"
justify="center"
direction="column"
h="100%"
maxH="500px"
w="90%"
p={6}
>
    <Flex>
      <Text color="brand.lightGrey" fontSize="6xl">
            Air Jordan 1
      </Text>
    </Flex>
    <Box h="80%" position="relative" zIndex="101">
        <Text my={6} fontWeight={300} color="brand.text" fontSize="xl" borderTop="solid 1px" pt={6}>
        The Air Jordan that was first produced for Michael Jordan in 1984 was designed by Peter C. Moore. The red and black colorway of the Nike Air Ship, the prototype for the Jordan I, was later outlawed by then-NBA Commissioner David Stern for having very little white on them (this rule, known as the "51 percent" rule, was repealed in the late 2000s).
        </Text>
        <Text my={6} fontWeight={300} color="brand.text" fontSize="xl" borderBottom="solid 1px" pb={6}>
        After the Nike Air Ship was banned, Michael Jordan and Nike introduced the Jordan I in colorways with more white, such as the "Chicago" and "Black Toe" colorways. They used the Nike Air Ship's ban as a promotional tool in advertisements, hinting that the shoes gave an unfair competitive advantage. The Air Jordan I was originally released from 1985 to 1986, with re-releases (known as "retros") in 1994, 2001–2004, and 2007 to the present. Along with the introduction of the Retro Air Jordan line up's, the brand has elevated to a household notoriety with star-struck collaborations and unique limited releases.
        </Text>
    </Box>
</Flex>

Here we have added another Flex container component, given the grid area of text and some other positional properties. Inside we have added our title and two paragraphs or copy, describing the trainers.

Next we are going to get a bit fancy and create a custom component to display some text on a vertical axis. As we will be re-using this component we will create it with some defaults but allow for customization. Inside the components folder create a new file called custom-text.js and add the following.

import React from 'react';
import styled from '@emotion/styled';

const Custom = styled.p`
  transform: ${(props) => (props.vertical ? 'rotate(270deg)' : 'none')};
  font-size: ${(props) => (props.fontSize ? props.fontSize : '20px')};
  letter-spacing: 10px;
  cursor: default;
  -webkit-text-stroke: 2px ${(props) => (props.color ? props.color : '#5C5C5C')};
  -webkit-text-fill-color: transparent;
`;

const CustomText = ({ text, fontSize, color, vertical }) => {
  return (
    <Custom fontSize={fontSize} color={color} vertical={vertical}>
      {text}
    </Custom>
  );
};

export default CustomText;

We could have used text-orientation here but I found it wasn't flexible enough for this use case so instead decided to use a good old fashioned transform on the text. We use a styled component so that we can add a text effect (-webkit-text-stroke) which isn't available as a prop with a Chakra Text component. This effect allows us to give the text an stroked outline. It takes the color provided as a prop or just uses the set default grey color. Finally our component accepts some size and orientation props, as well as the actual text it is to display. Next we need to add our new component to the components object which is passed into the MDXProvider

const components = {
  wrapper: (props) => <MDXLayout {...props}>{props.children}</MDXLayout>,
  //...lots of stuff
  p: (props) => <Text {...props}>{props.children}</Text>,
  Text,
  Box,
  Flex,
  Heading,
  Grid: (props) => <Grid {...props}>{props.children}</Grid>,
  Link,
  Image,
  SimpleGrid,
  Stack,
    // Here is our new component!
  CustomText,
};

We'll use this new component to display some vertical text alongside out copy. Below the copy add the following.

<Flex gridArea="edge" gridRow="2" justify="center" align="center">
  <Box>
    <CustomText vertical text="Innovation" fontSize="100px" />
  </Box>
</Flex>

If you now run npm run start from the root of the project you should see a red Nike tick in the top left, a title of Air Jordan 1 and some copy below it. To the left of that cop you should see the work Innovation written vertically with an grey outline. It's not much to look at so far, let's spice things up a little with a 3D model!

The third dimension

Before we dive into adding a 3D model to our page let's take a little time to understand how we are going to do that. This isn't some deep dive into Threejs, WebGL and how the react-three-fiber renderer works, rather we will look at what you can use and why you should use it.

For us to render a 3D model on the page we will need to create a Three scene, attach a camera, some lights, use a mesh to create a surface for our model to live on and finally render all that to the page. We could go vanilla js here and type out all that using Three and it's classes and objects, but why bother when we can use react-three-fiber and rather lovely abstraction library call drei (Three in German).

We can import a canvas from react-three-fiber which takes care of adding a scene to our canvas. It also lets us configure the camera and numerous other things via props. It's just a React component at the end of the day, all be it one that does a ton of heavy lifting for us. We'll use our canvas to render our model on. The canvas component renders Three elements, not DOM elements. It provides access to Three classes and objects via it's context so any children rendered within it will have access to Three.

Our canvas can go anywhere on our page but it's important to remember that it will take up the height and width or it's nearest parent container. This is important to remember as if you wanted to display your canvas on the whole screen you would have to do something of a css reset like this:

* {
  box-sizing: border-box;
}
html,
body,
#root {
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 0;
}

In order to render something, like a shape, to our canvas we need to use a mesh. A mesh is like a base skeleton that an object is made from, like a wireframe. to create a basic shape, such as a sphere, we would have to attach a geometry so that the wireframe can form into a shape, and a material so that it no longer looks just like a wireframe. I like to think of it like chicken wire. You can have a flat piece of chicken wire which you then form into a shape (geometry attached). You can then cover that chicken wire in some material such as a cloth (material attached). To decide where to place an object on the canvas we can use the position prop on the mesh, this prop takes an array as [x, y, z] which follows the logical axis with z as depth.

Each Three class takes constructor arguments which enable you to modify it's appearance. To pass these constructor arguments to our Three element we use the args prop which again uses the array syntax. Let's look at an example of this. The box geometry class accepts 3 main arguments, width, height and depth. These can be used like so with react-three-fiber

// Threejs:
const geometry = new THREE.BoxGeometry( 1, 1, 1 );

// react-three-fiber:
<boxGeometry args={[1,1,1]}/>

When creating objects or models it's important to remember to provide the scene with a light source, otherwise the only thing you will be able to see is a black outline of whatever it is you are trying to render. This makes sense if you think about it. You wouldn't be able to see a shape in a dark room, add a light source of any kind and that shape suddenly takes form and has a surface with colors and contours.

An oldie but a goodie, article in smashing magazine that outlines some of the light you can use in Three.

Point. Possibly the most commonly used, the point light works much like a light bulb and affects all objects in the same way as long as they are within its predefined range. These can mimic the light cast by a ceiling light.

Spot. The spot light is similar to the point light but is focused, illuminating only the objects within its cone of light and its range. Because it doesn’t illuminate everything equally as the point light does, objects will cast a shadow and have a “dark” side.

Ambient. This adds a light source that affects all objects in the scene equally. Ambient lights, like sunlight, are used as a general light source. This allows objects in shadow to be viewable, because anything hidden from direct rays would otherwise be completely dark. Because of the general nature of ambient light, the source position does not change how the light affects the scene.

Hemisphere. This light source works much like a pool-table light, in that it is positioned directly above the scene and the light disperses from that point only.

Directional. The directional light is also fairly similar to the point and spot lights, in that it affects everything within its cone. The big difference is that the directional light does not have a range. It can be placed far away from the objects because the light persists infinitely.

Area. Emanating directly from an object in the scene with specific properties, area light is extremely useful for mimicking fixtures like overhanging florescent light and LCD backlight. When forming an area light, you must declare its shape (usually rectangular or circular) and dimension in order to determine the area that the light will cover.

We can view the following example which uses the react-three-fiber Three elements and also outlines examples or doing the same thing but with the drei helper library.

<Canvas>
      <mesh
        visible // object gets render if true
        userData={{ test: "hello" }} // An object that can be used to store custom data about the Object3d
        position={[0, 0, 0]} // The position on the canvas of the object [x,y,x]
        rotation={[0, 0, 0]} // The rotation of the object
        castShadow // Sets whether or not the object cats a shadow
        // There are many more props.....
      >
        {/* A spherical shape*/}
        <sphereGeometry attach="geometry" args={[1, 16, 200]} />
        {/* A standard mesh material*/}
        <meshStandardMaterial
          attach="material" // How the element should attach itself to its parent
          color="#7222D3" // The color of the material
          transparent // Defines whether this material is transparent. This has an effect on rendering as transparent objects need special treatment and are rendered after non-transparent objects. When set to true, the extent to which the material is transparent is controlled by setting it's .opacity property.
          roughness={0.1} // The roughness of the material - Defaults to 1
          metalness={0.1} // The metalness of the material - Defaults to 0
        />
      </mesh>
      {/*An ambient light that creates a soft light against the object */}
      <ambientLight intensity={0.5} />
      {/*An directional light which aims form the given position */}
      <directionalLight position={[10, 10, 5]} intensity={1} />
      {/*An point light, basically the same as directional. This one points from under */}
      <pointLight position={[0, -10, 5]} intensity={1} />

      {/* We can use the drei Sphere which has a simple API. This sphere has a wobble material attached to it */}
      <Sphere visible position={[-3, 0, 0]} args={[1, 16, 200]}>
        <MeshWobbleMaterial
          attach="material"
          color="#EB1E99"
          factor={1} // Strength, 0 disables the effect (default=1)
          speed={2} // Speed (default=1)
          roughness={0}
        />
      </Sphere>

      {/* This sphere has a distort material attached to it */}
      <Sphere visible position={[3, 0, 0]} args={[1, 16, 200]}>
        <MeshDistortMaterial
          color="#00A38D"
          attach="material"
          distort={0.5} // Strength, 0 disables the effect (default=1)
          speed={2} // Speed (default=1)
          roughness={0}
        />
      </Sphere>
    </Canvas>

The model

Now that we have an understanding of what to use let's create a component for a our product model. Inside the 3d folder create a new file called model.js and add the following.

import React from 'react';
import { useGLTF } from '@react-three/drei';
import { useFrame } from 'react-three-fiber';
import ModelLights from './model-lights';

const Model = ({ scenePath, position, rotation }) => {
  const gltf = useGLTF(scenePath, true);
  const mesh = React.useRef();
  useFrame(
    () => (
      (mesh.current.rotation.x += rotation[0]),
      (mesh.current.rotation.y += rotation[1])
    ),
  );
  return (
    <mesh ref={mesh} position={position}>
      <ModelLights/>
      <primitive object={gltf.scene} dispose={null} />
    </mesh>
  );
};

export default Model;

Our component is fairly generic due to the props it takes. The scene path refers to the path to the gltf file that houses the model. The position props which is passed down to the mesh positions the model on the canvas, and the rotation sets the rotation of the model But what is gltf? In a nutshell, it's a specification for loading 3D content. It accepts both JSON (.gltf) or binary (.glb) formats. Instead of storing a single texture or assets like .jgp or .png, gltf packages up all that is needed to show the 3D content. That could include everything from the mesh, geometry, materials and textures. For more information checkout the Three docs.

To load our model files we use a helper hook from drei (useGLTF) which uses useLoader and GTLFLoader under the hood. We use the useFrame hook to run a rotation effect on the model using a ref which we connect to the mesh. The mesh we rotate on the X axis and position according to the provided props.

We use a primitive placeholder and attach the model scene and finally pass in a separate lights component which we will soon create.

For our model we will be downloading a free 3D model from Sketchfab. Create a free account and head to this link to download the Nike Air Jordan 1's model. You will want to download the Autoconverted format (glTF), which is the middle option. To access our model files in our application open the public folder at our projects root and add a new folder called shoes, inside this folder paste over the textures folder, scene.bin and scene.gltf files. Now that we have created our product model component and downloaded the model files we need to create the canvas that the model shall live in on our page. Inside the 3d folder create a new file called canvas-container.js and add the following.

import React, { Suspense } from 'react';
import { Canvas } from 'react-three-fiber';
import { Box } from '@chakra-ui/core';

/**
 * A container with a set width to hold the canvas.
 */
const CanvasContainer = ({
  width,
  height,
  position,
  fov,
  children,
  ...rest
}) => {
  return (
    <Box {...rest} h={height} w={width} zIndex="999">
      <Canvas
        colorManagement
        camera={{
          position,
          fov,
        }}
      >
        <Suspense fallback={null}>{children}</Suspense>
      </Canvas>
    </Box>
  );
};

export default CanvasContainer;

Our new component has a container div (Box) which takes props for it's width, height and anything else we might fancy passing in. It's z-index is set to a high value as we will be placing some text beneath if. The canvas has a camera set with a field of view (where the higher the number the further away the view). We wrap the children in a Suspense so that the application doesn't crash while it's loading.

Now create a new file in the same folder called product.js and add the following code.

import React from 'react';
import Model from './model';
import { OrbitControls } from '@react-three/drei';
import CanvasContainer from './canvas-container';

/**
 * A trainers model
 */
const Product = () => {
  return (
    <CanvasContainer height={800} width={800} position={[20, 30, 20]} fov={75}>
      <Model
        scenePath="shoes/scene.gltf"
        position={[0, 10, 0]}
        rotation={[0, 0.005, 0]}
      />
      <OrbitControls />
    </CanvasContainer>
  );
};

export default Product;

We want to let our user interact with out model. Importing the orbital controls from drei allows the user to zoom in/out and spin around the model all with their mouse letting them view it from any angle, a cool touch.

But we won't be able to see anything if we don't add any lights to our canvas. Inside the 3d folder create a new file called model-lights and add the following.

import React from 'react';

const ModelLights = () => (
  <>
    <directionalLight position={[10, 10, 5]} intensity={2} />
    <directionalLight position={[-10, -10, -5]} intensity={1} />
  </>
);

export default ModelLights;

Now it's time to add these bad boys to the MDX file. Add the Product component to the components object the same way we did with the CustomText component.

Now add the following below the Flex component that sets the innovation text.

<Flex
  gridArea="product"
  justify="center"
  direction="column"
  h="100%"
  position="relative"
>
  <Product />
  <Box
    position="absolute"
    right="-15%"
    bottom="25%"
  >
    <CustomText vertical color="#ed1c24" text="Jordan" fontSize="200px" />
  </Box>
  <Box position="absolute" bottom="0" right="35%">
  <CustomText color="#5C5C5C" text="Air" fontSize="200px" />
</Box>

<Box position="absolute" top="-50%" right="20%" zIndex="100">
  <CustomText color="#ed1c24" text="1" fontSize="800px" />
</Box>

</Flex>

Setting the grid area to product places our model in the correct row and column of our grid. We give the Flex component a position of relative as we want to absolutely position the text that is underneath the model. This gives our page a sense of depth that is accentuated by the 3D model. If we run our development server again we should we the shoes spinning around to the right of the copy!

Add some glitter

Our page is looking pretty dope but there are a few more finishing touches that would make it sparkle just that little brighter. Head over to Sktechfab again and download this basketball model. Inside the 3d folder create a new file called basketball.js and add the following.

import React, { Suspense } from 'react';
import Model from './model';
import CanvasContainer from './canvas-container';

/**
 * A basketball model
 */
const Basketball = () => {
  return (
    <CanvasContainer
      ml={5}
      height={100}
      width={100}
      position={[0, 20, 20]}
      fov={50}
    >
      <Model
        scenePath="basketball/scene.gltf"
        position={[0, 17, 17]}
        rotation={[0.025, 0.025, 0]}
      />
    </CanvasContainer>
  );
};

export default Basketball;

Utilizing out generic canvas and model components we are able to create a new component that will render a basketball to the page. We are going to position this basketball to the left of the Air Jordan title text. Noice. Add the new Basketball component to the component s object like we have done before and open the MDX file and add the new component under the title text.

<Flex>
  <Text color="brand.lightGrey" fontSize="6xl">
    Air Jordan 1
  </Text>
// Im the new component!
<Basketball/>
</Flex>

Sweet! It's almost complete. Subtle animations that aren't obvious to the user straight away are a nice addition to any website. Let's add a glitch effect to our title text which only runs when the site visitor hovers their mouse over the text.

Inside the components folder create a new file called glitch-text.js and add the following.

import React from 'react';
import styled from '@emotion/styled';

const Container = styled.div`
  position: relative;

  &:hover {
    &:before {
      content: attr(data-text);
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;

      left: 2px;
      text-shadow: -1px 0 #d6d6d6;
      background: #090d12;

      overflow: hidden;
      animation: noise-anim-2 5s infinite linear alternate-reverse;
    }

    &:after {
      content: attr(data-text);
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;

      left: -2px;
      text-shadow: -1px 0 #d6d6d6;
      background: #090d12;
      overflow: hidden;
      animation: noise-anim 1s infinite linear alternate-reverse;
    }

    @keyframes noise-anim {
      0% {
        clip-path: inset(100% 0 1% 0);
      }
      5% {
        clip-path: inset(45% 0 41% 0);
      }
      10% {
        clip-path: inset(8% 0 18% 0);
      }
      15% {
        clip-path: inset(94% 0 7% 0);
      }
      20% {
        clip-path: inset(23% 0 69% 0);
      }
      25% {
        clip-path: inset(21% 0 28% 0);
      }
      30% {
        clip-path: inset(92% 0 3% 0);
      }
      35% {
        clip-path: inset(2% 0 35% 0);
      }
      40% {
        clip-path: inset(80% 0 1% 0);
      }
      45% {
        clip-path: inset(75% 0 9% 0);
      }
      50% {
        clip-path: inset(37% 0 3% 0);
      }
      55% {
        clip-path: inset(59% 0 3% 0);
      }
      60% {
        clip-path: inset(26% 0 67% 0);
      }
      65% {
        clip-path: inset(75% 0 19% 0);
      }
      70% {
        clip-path: inset(84% 0 2% 0);
      }
      75% {
        clip-path: inset(92% 0 6% 0);
      }
      80% {
        clip-path: inset(10% 0 58% 0);
      }
      85% {
        clip-path: inset(58% 0 23% 0);
      }
      90% {
        clip-path: inset(20% 0 59% 0);
      }
      95% {
        clip-path: inset(50% 0 32% 0);
      }
      100% {
        clip-path: inset(69% 0 9% 0);
      }
    }
  }
`;

export default ({ children }) => {
  return <Container data-text={children}>{children}</Container>;
};

Our new component uses a styled div component to set its internal css. We state that the following effect shall only run when the element is hovered and then use the pseudo elements to insert some glitchy goodness. The pseudo content is the text passed in as children, we animate some clip paths via some keyframes and give the effect that the text is moving. Add this new component to the components object as GlitchText and then wrap the title text in the new component in the MDX markup.

<Text color="brand.lightGrey" fontSize="6xl">
  <GlitchText>Air Jordan 1</GlitchText>
</Text>

Finishing touches

We've come so far and we have covered some steep terrain. We have taken a broad overview of working with 3D components and models in React, looked at designing layouts using css grid. Utilized a component library to make our life easier and explored how to create cool, interactive markdown pages with MDX. Our product page is basically complete, anyone who came across this on the interwebs would certainly be more drawn in than your run of the mill static product pages. But there is one last thing I would like you to add, something subtle to make the page pop. Let's add some particles!

We have already installed the package so create a new file inside the component folder called background and add the following.

import React from 'react';
import Particles from 'react-particles-js';

const Background = () => (
  <div
    style={{
      position: 'absolute',
      width: '100%',
      height: '100%',
    }}
  >
    <Particles
      params={{
        particles: {
          number: {
            value: 25,
          },
          size: {
            value: 3,
          },
        },
        interactivity: {
          events: {
            onhover: {
              enable: true,
              mode: 'repulse',
            },
          },
        },
      }}
    />
  </div>
);

This will serve as our background to our site. We have absolutely positioned the parent container of the particles so that they take up the whole of the page. Next open the routes file and add a Box component and the new Background component.

import React from 'react';
import { Box, CSSReset } from '@chakra-ui/core';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import PageOne from '../pages/page-one.mdx';
import Background from './background';

/**
 * The routes for the app. When adding new pages add a new route and a corresponding nav link in the Nav component above. Import the new page and add it to the route.
 */
export const MDXRoutes = () => (
  <Router>
    <CSSReset />
    <Box
      position="relative"
      top={0}
      left={0}
      width="100%"
      height="100%"
      zIndex="99999"
    >
      <Background />
      <Routes>
        <Route path="/" element={<PageOne />} />
      </Routes>
    </Box>
  </Router>
);

Start up the development server marvel at your handy work! Great job. If everything went according to plan then your site should look just like the demo site 3d-product-page.netlify.app/

Recap

Learnt about react-three-fiber, drei and Threejs
Learnt how to add a canvas to a page and render a shape
Learnt how to render a 3D model to a page
Used some super modern (this will age well...) tooling

We accomplished quite a lot during this tutorial and hopefully there are some take homes that can be used on other projects you create. If you have any questions shoot me a message on Twitter @studio_hungry, I'd be more than happy to have a chinwag about your thoughts and would love to see what you create with your new found 3D knowledge!

Date object snippet

Richard Haines — Mon, 04 Jan 2021 21:19:37 +0000

Getting the locale date

The toLocaleDateString method on the date object lets you pass in the locale of choice and returns a string formatted date with forward slash separators.

let today = new Date().toLocaleDateString('en-gb');

// today => 24/09/2020

Replacing the slash

To replace the forward slash with a dash is as easy as manipulating the string with a replace regex.

let today = new Date().toLocaleDateString('en-gb').replace(/\//g, '-');

// today => 24-09-2020

Written representation

To get the written representation of the date in the chosen locale toLocaleDateString accepts a second options param where you can specify

weekday
year
month
day

const options = {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
};
let today = new Date().toLocaleDateString('en-gb', options);

// today => Thursday, 24 September 2020

Build a tech conf site with Gatsby + Crystalize (Headless GraphQL CMS)

Richard Haines — Mon, 04 Jan 2021 21:18:33 +0000

This tutorial was originally posted on my blog richardhaines.dev

In this tutorial we will learn how to utilize the Crystallize graphql API as a headless CMS for our pretend tech conference website, The Conf Vault.

All the source code for this article can be found here: github.com/molebox/gatsby-crystallize-conf-example. Feel free to fork and play around with it, it can often times help to have the source code open when following a tutorial.

I've been really impressed with what Crystallize has to offer, at first it was quite the mind shift thinking about modelling my data but I really like the process of using Figma to brainstorm the models then being able to directly translate them into actual models in the Crystallize UI.

Crystallize provide the tools with which to visually present content and I found the whole process much more aligned with how I tend to think about projects before starting them. Due to the nature of the composable shapes, we as creators can put together feature rich stories with the aim of driving home our brands story, be that our personal brand or business.

Although mainly marketed as an ecommerce PIM, Crystallize is certainly capable of much more, let's take a look...

We will learn:

Why Crystallize?
Content modelling (with Figma 🤯)
Querying and pulling data into a Gatsby site with Apollo
Deploy to Netlify and set up webhooks!
BONUS: Make it pretty! Add some gsap animations, some colors, throw some box shadows on it... 🤗

This article assumes prior knowledge of React and the Jamstack ecosystem.

Why Crystallize?

As a Jamstack developer you are most likely familier with the concept of the headless Content Management System (CMS), a place for you to enter and store data from which a frontend will request and use it. Differentiating between them mostly comes down to how you want to interact with your stored data, via a GUI or CLI, and how to access that data, via REST or Graphql (gql) endpoints.

Marketing itself as a super fast headless CMS for Product Information Management (PIM, we're racking up those abbreviations!), it aims to enable the user to combine rich story telling, structured content and ecommerce as a single solution. But it doesn't only have to used for ecommerce solutions. Crystallize is flexible enough so that we can utilize its structured content models and create anything we like, then using it's graphql API we can access our stored data from any device, be that computer or mobile.

The UI is also super easy to hand off to a client so that they can enter in data themselves, which is a massive plus when considering which CMS to go with while working with clients.

Content Modelling

When we whiteboard or brainstorm ideas they are very rarely linear, they don't tend to fit in square boxes, at least that is, until we manipulate those ideas to fit a given structure, one provided to us by our choice of CMS for example. Of course, a totally generic solution to modelling our content would also be very time consuming for a user to put together. Give them a set of premade tools with just the right amount of generics however and they can create what they want, in whatever shapes they please.

The content model serves as documentation and overview and connects information architects, designers, developers and business stakeholders.

The fine folks at Crystallize have created a design system using Figma and given everyone access to it via a Figma file you can download. I put together a model for our tech conf site which you can download here.

title=""
url="file/gywqAn9uh3J2vjwcfIOdVr/The-Conf-Vault-Content-Model?node-id=0%3A1"
/>

Looking at the content model, we have 3 shapes, Event, Schedule and Speaker. These are in the format of Documents. Each one is comprised of components which make up the structure of that model. The Event shape has a relationship with both the schedule and speaker shapes. This is because an event has both a schedule and speakers. The schedule shape also has a relationship with the speakers shape. These relationships will allow us to query on a single node but access it's corrasponding relationship nodes. For example, if we query for an event, we will in turn be able to access the speakers at that event.

Note that the modelling you do in Figma can't be exported and used in the Crystallize UI, you will have to manually re-create the models.

Show me the crystals... 💎

Head over to crystallize.com and create a new account, once in create a new tenent and then you will be presented with a page similar to the following:

On the left hand side you can open the menu to reveal your options. With your Figma file open too, start creating the shapes and their components. Begin with the folders. 3 folders should do the trick, Speakers, Conferences and Schedules. Now create the 3 document shapes, Event, Schedule and Speaker. Each of our document shapes will be made up of components, following our content model in Figma, add the components to the newly created shapes.

Once done open the catalogue tab (the one at the top) and inside the Conference folder create a new document of type Event.

An Event

Don't worry about adding anything to the schedule relationship just yet, we'll need to create a schedule first for that to make any sense! The same applies to the speakers relationships.

Once you have created all your events do the same for the speakers and schedules. Now the schedules are done you can add the speaker relations to those, then coming back to the events, you can add both the schedule and speaker relations, and the circle of life is complete!

A Speaker

A Schedule

Fetching data using Apollo Client

Being a Jamstack dev there are quite a few solutions to the age old question of "Which frontend should I use for my headless CMS...?" We'll be going with Gatsby today. I prefer to spin up Gatsby sites from an empty folder, if you are well versed then feel free to use a starter or template. We'll be needing some additional packages to those that form a basic Gatsby site, from the command line (I will be using yarn but npm is fine too) add the following packages:

yarn add @apollo/client isomorphic-fetch

There are a couple of ways we could connect our Cystallize API with our Gatsby site. Crystallize has a gatsby boilerplate which uses the gatsby-source-graphql plugin, I would have expected there to be a source plugin for sourcing data from Crystallize which would have meant abstracting away from the gatsby-source-graphql and transforming the source nodes. Instead, we'll be super on trend and use Apollo to interact with and fetch our data.

wrap-root.js

In Gatsby there are two files that can be created and used in order to access certain points of the build process. We'll be creating a third file which will be imported into both. This is purely a personal choice that reduces code duplication, though it has become somewhat of a standard in the Gatsby community.

const React = require("react");
// We need this as fetch only runs in the browser
const fetch = require("isomorphic-fetch");
const {
  ApolloProvider,
  ApolloClient,
  createHttpLink,
  InMemoryCache,
} = require("@apollo/client");

// create the http link to fetch the gql results
const httpLink = createHttpLink({
  uri: "https://api.crystallize.com/rich-haines/catalogue",
  fetch,
});

const client = new ApolloClient({
  cache: new InMemoryCache(),
  link: httpLink,
  fetch,
});

export const wrapRootElement = ({ element }) => (
  <ApolloProvider client={client}>{element}</ApolloProvider>
);

We create a http link to our gql endpoint and pass it to the Apollo client, before passing the client to the provider and wrapping our app.

This file will be imported into and exported from both the gatsby-ssr.js and gatsby-browser.js files like so:

import { wrapRootElement as wrap } from "./wrap-root";

export const wrapRootElement = wrap;

Let's now add some scripts to our package.json so that we can run our site.

{
  "name": "gatsby-conf-example",
  "version": "1.0.0",
  "main": "index.js",
  "author": "Rich Haines",
  "license": "MIT",
  "scripts": {
    "dev": "gatsby develop",
    "build": "gatsby build",
    "clean": "gatsby clean",
    "z": "gatsby clean && gatsby develop",
    "pretty": "prettier --write \"src/**/*js\""
  },
  "dependencies": {
    ...deps
  },
  "devDependencies": {
    ...devDeps
  }
}

Often times when developing Gatsby sites you will need to remove the cache, setting up a simple script to both clear the cache and run our site in gatsby develop mode will save time and headaches later. hence yarn z, the name is arbitrary.

Show me the data!

Now that we have Apollo setup we can head back over to the Crystallize UI and navigate to the Catalogue Explorer tab which can be found in the left tab menu. Click Fetch tree at root and run the query. You should see your 3 folders returned. If we inspect the query on the left of the explorer we can see that it's in fact 1 query with many fragments. These fragments split up the requests into bite size chunks that can then be spread into other fragments or the query.

A neat feature which I really like with Crystallize is the ability to test out queries directly from the shape, with provided base query and fragments to get you going. If you head to your catalogue and open up an event, then click the gql symbol which sits along the top bar an explorer will open up, it should look something like this:

This is nice and allows you to play about with different fragments and see what you would get back from your query should you use it in production. Not content with offering 2 different ways to test our queries, Crystallize provides a 3rd. A url with your tenent id which looks like the following: https://api.crystallize.com/your-tenent-id-here/catalogue.

This is a clean slate with tabs to save each query. From whatever gql explorer you choose, open the Docs tab located on the right. From here you can see what you can query and how each interface is nested or relates to another. Click catalogue and you can see that it returns a Item, when we click the Item we can see all of the properties we can query for.

The interesting part of this is the children property, which itself returns an Item. This nesting goes as far as your data is nested but is powerful and enables us to query nested children without having to specify specific properties.

For our index/home page we will be querying for the root paths to our 3 folders, these will be passed on to components which will use that path to themselves query for specific data.

GetRootPaths

query GetRootPaths {
  catalogue(language: "en", path: "/") {
    children {
      path
      shape {
        name
      }
      children {
        path
        shape {
          name
        }
      }
    }
  }
}

We set the path param to that of the root directory, that is, the tenent. From here we ask for the first child and that's first child. So that is 2 levels deep. We request the path and the name of the shape. We know that our 3 shapes are called Conferences, Speakers and Schedules. Those should be our top level data types. Then we would expect to see the paths and shapes of the documents within the 3 folders. What is returned is the following:

{
  "data": {
    "catalogue": {
      "children": [
        {
          "path": "/conferences",
          "shape": {
            "name": "Conferences"
          },
          "children": [
            {
              "path": "/conferences/oh-my-dayz",
              "shape": {
                "name": "Event"
              }
            },
            {
              "path": "/conferences/crystal-conf-yeah",
              "shape": {
                "name": "Event"
              }
            }
          ]
        },
        {
          "path": "/speakers",
          "shape": {
            "name": "Speakers"
          },
          "children": [
            {
              "path": "/speakers/speaker",
              "shape": {
                "name": "Speaker"
              }
            },
            {
              "path": "/speakers/speaker-1",
              "shape": {
                "name": "Speaker"
              }
            },
            {
              "path": "/speakers/speaker-2",
              "shape": {
                "name": "Speaker"
              }
            }
          ]
        },
        {
          "path": "/schedules",
          "shape": {
            "name": "Schedules"
          },
          "children": [
            {
              "path": "/schedules/oh-my-dayz-schedule",
              "shape": {
                "name": "Schedule"
              }
            },
            {
              "path": "/schedules/crystal-conf-schedule",
              "shape": {
                "name": "Schedule"
              }
            }
          ]
        }
      ]
    }
  }
}

Sure enough we see the expected data. Let's move back to the frontend and add this query to our code.

Open the index.js file located in the pages folder of your Gatsby project.

index.js

import React from "react";
import { useQuery, gql } from "@apollo/client";

export default function Index() {
  const { loading, error, data } = useQuery(GET_ROOT_PATHS);

  if (loading) {
    return <h1>loading....</h1>;
  }
  if (error) {
    return <h1>error....</h1>;
  }

  const conferencePaths = data.catalogue.children[0].children.map(
    (node) => node.path
  );

  return (
    <div>
      {conferencePaths.map((path, index) => (
        <p key={index}>{path}</p>
      ))}
    </div>
  );
}

const GET_ROOT_PATHS = gql`
  query GetRootPaths {
    catalogue(language: "en", path: "/") {
      children {
        path
        shape {
          name
        }
        children {
          path
          shape {
            name
          }
        }
      }
    }
  }
`;

Apollo provides us with a lovely way to query and handle our data. We pass our query into the useQuery hook, in return we get 2 states (loading, error) and our data. We do a simple check to makes sure our data isn't loading or has an error then we filter out the conference paths and simply display them on the screen. We'll be coming back to this page soon, but let's first use a query that accepts some parameters.

The Event

We'll pass each conference path down to an event component which in turn will use that path as a query param to request data about that event. Let's see how that looks in practice. In your components folder, inside the src folder (assuming you set your project up this way) create a new file and name it event.js

event.js

import React from "react";
import { useQuery, gql } from "@apollo/client";

const Event = ({ path }) => {
  const { loading, error, data } = useQuery(GET_CONFERENCE, {
    variables: {
      path: path,
    },
  });

  if (loading) {
    return <h1>loading....</h1>;
  }
  if (error) {
    return <h1>error....</h1>;
  }

  let title = data.catalogue.components[0].content.text;
  let logo = data.catalogue.components[1].content.images[0].variants[0].url;
  let codeOfConduct = data.catalogue.components[2].content.json;
  let speakersPath = data.catalogue.components[4].content.items.map(
    (node) => node.path
  );
  let schedulePath = data.catalogue.components[3].content.items[0].path;

  return (
    <div>
      <h1>{title}</h1>
      <img src={logo} />
      {speakersPath.map((path, index) => (
        <Speaker key={index} path={path} />
      ))}
      <Schedule path={schedulePath} />
      <CoD cod={codeOfConduct} />
    </div>
  );
};

export default Event;

const GET_CONFERENCE = gql`
  query GetConference($path: String!) {
    catalogue(language: "en", path: $path) {
      name
      path
      components {
        content {
          ...richText
          ...imageContent
          ...singleLineText
          ...paragraphsCollection
          ...propertiesTable
          ...relations
        }
      }
    }
  }

  fragment singleLineText on SingleLineContent {
    text
  }

  fragment richText on RichTextContent {
    json
    html
    plainText
  }

  fragment image on Image {
    url
    altText
    key
    variants {
      url
      width
      key
    }
  }

  fragment imageContent on ImageContent {
    images {
      ...image
    }
  }

  fragment paragraphsCollection on ParagraphCollectionContent {
    paragraphs {
      title {
        ...singleLineText
      }
      body {
        ...richText
      }
      images {
        ...image
      }
    }
  }

  fragment propertiesTable on PropertiesTableContent {
    sections {
      ... on PropertiesTableSection {
        title
        properties {
          key
          value
        }
      }
    }
  }

  fragment relations on ItemRelationsContent {
    items {
      name
      path
      components {
        content {
          ...richText
          ...imageContent
          ...singleLineText
          ...paragraphsCollection
        }
      }
    }
  }
`;

The query was put together in the gql explorer, the order of the fragments is important as some of them rely on one another and they can't be defined before they are used. The basic logic behind the query is that we pass in a path to a conference from which we want to recieve back the components that make up the data for that shape. The components are split into fragments so that our query doesn't become bloated. Notice the relations fragment. It returns the same data as our query plus it's own path and name. Nearly recursive, of course, to understand recursion one must first understand recursion....

Our Speaker and Schedule components follow much the same way of thinking. The CoD and indeed some other components, uses a complimentory library supplied by Crystallize to help with displaying it's rich text data, which is returned as either html , json or plain text. Let's install it and learn how to use it.

yarn add @crystallize/content-transformer

Now in our components folder create a new file named content-transform.js

content-transform.js

import React from "react";
import CrystallizeContent from "@crystallize/content-transformer/react";

const ContentTransform = (props) => {
  const overrides = {
    paragraph({ metadata, renderNode, ...rest }) {
      return <p style={{ fontSize: props.fontSize }}>{renderNode(rest)}</p>;
    },
  };

  return <CrystallizeContent {...props} overrides={overrides} />;
};

export default ContentTransform;

This package basically allows us to pass in overrides for how it displays certain elements. In the above example, taken from our app, the paragraph tag is overriden with the font size prop passed in. In practice this is used like so:

CoD

import React from "react";
import ContentTransform from "./content-transform";

const CoD = ({ cod }) => {
  return (
    <div>
      <ContentTransform {...cod} />
    </div>
  );
};

export default CoD;

And thats it. If we were to pass in the font size prop we could do so like this:

<ContentTransform fontSize="100px" {...cod} />

It's an elegant way to help display rich text data.

As mentioned, our Speaker and Schedule components are much the same. Let's take them both at the same time.

speaker.js

import React from "react";
import { useQuery, gql } from "@apollo/client";
import ContentTransform from "./content-transform";

const Speaker = ({ path }) => {
  const { loading, error, data } = useQuery(GET_SPEAKER, {
    variables: {
      path: path,
    },
  });

  if (loading) {
    return <h1>loading...</h1>;
  }
  if (error) {
    return <h1>error...</h1>;
  }

  let image = data.catalogue.components[1].content.images[0].variants[0].url;
  let name = data.catalogue.components[0].content.json;
  let company = data.catalogue.components[2].content.text;
  let bio = data.catalogue.components[3].content.json;
  let twitter = data.catalogue.components[4].content.text;

  return (
    <div>
      <img src={image} />
      <ContentTransform fontSize="xl" {...name} />
      <p>{company}</p>
      <ContentTransform {...bio} />
      <p>{twitter}</p>
    </div>
  );
};

export default Speaker;

const GET_SPEAKER = gql`
  query GetSpeaker($path: String!) {
    catalogue(language: "en", path: $path) {
      ...item
      name
      components {
        content {
          ...richText
          ...singleLineText
          ...imageContent
        }
      }
    }
  }

  fragment item on Item {
    name
    type
    path
    children {
      name
    }
  }

  fragment singleLineText on SingleLineContent {
    text
  }

  fragment richText on RichTextContent {
    json
    html
    plainText
  }

  fragment image on Image {
    url
    altText
    key
    variants {
      url
      width
      key
    }
  }

  fragment imageContent on ImageContent {
    images {
      ...image
    }
  }
`;

schedule.js

import React from "react";
import { useQuery, gql } from "@apollo/client";

const Schedule = ({ path }) => {
  const { loading, error, data } = useQuery(GET_SCHEDULE, {
    variables: {
      path: path,
    },
  });

  if (loading) {
    return <h1>loading...</h1>;
  }
  if (error) {
    return <h1>error...</h1>;
  }

  let title = data.catalogue.components[0].content.sections[0].title;
  let schedule = data.catalogue.components[0].content.sections[0].properties;

  return (
    <div>
      <h1>{title}</h1>
      <table cellPadding={6}>
        <thead>
          <tr>
            <th>
              <p>Speaker</p>
            </th>
            <th>
              <p>Subject...</p>
            </th>
          </tr>
        </thead>

        <tbody>
          {schedule.map((node, index) => (
            <tr key={index}>
              <td>
                <p>{node.key}</p>
              </td>
              <td>
                <p>{node.value}</p>
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
};

export default Schedule;

const GET_SCHEDULE = gql`
  query GetSchedule($path: String!) {
    catalogue(language: "en", path: $path) {
      ...item
      components {
        content {
          ...propertiesTable
        }
      }
    }
  }

  fragment item on Item {
    name
    type
    path
    children {
      name
    }
  }

  fragment propertiesTable on PropertiesTableContent {
    sections {
      ... on PropertiesTableSection {
        title
        properties {
          key
          value
        }
      }
    }
  }
`;

Our schedule component makes use of the properties table in the Crystallize backend. This is translated to key value pairs which work perfectly when used in an actual HTML table.

Deploy when content updates using webhooks

Our site isn't much to look at, in fact it's downright ugly! But we'll worry about that later, let's first get this baby deployed and setup a web hook so that our static site rebuilds every time we publish changes from our Crystallize backend.

This section assumes you have a Netlify account setup, if not create an account if you wish to follow along with this section.

Create an netlify.toml file at the projects root.

[build]
    command = "yarn build"
    functions = "functions"
    publish = "public"

Next, create a new site from the repository you created earlier, I hope you have been commiting your code! Netlify will use the settings from the .toml file we just created. In the netlify dashboard head to the Deploys tab and then the Deploy Settings, scroll down until you find the build hooks section. Add a new build hook, naming it whatever you like, perhaps NETLIFY_BUILD_ON_PUBLISH makes the most sense as that's what it's going to do. You will be presented with a url, copy it to the clipboard and head on over to the Crystallize UI. From the tabs on the left click the little Captain Hook icon then add a new web hook

Here we have selected publish as the event we want to trigger our build hook. Paste the url you copied from the netlify dahsboard into the URL section and change it from GET to POST, then hit save. Now make a small change to your data, add a shape, remove a full stop, whatever. Then open the netlify dahsboard, go to the deploy section and watch as your site rebuilds!

BONUS!

Our site quite frankly, looks terrible. Let's straighten that out. I'm going to show the code for each component plus a few extras, they each use Chakra-UI which allows inline styling via props.

Let's install some additional packages

yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion gsap gatsby-plugin-google-fonts react-rough-notation
yarn add prettier -D

Unfortunately Chakra requires us to install framer motion (as of v1) even though we will be adding some animations using gsap. I can forgive this as working with Chakra will enable us to utilize performant and accessibility first components and speed up our development time when creating our UI.

Inside the src folder create a new file called theme.js this is where we will define our apps colors, fonts and font sizes.

theme.js

import { extendTheme } from "@chakra-ui/react";

export const theme = extendTheme({
  styles: {
    global: {
      body: {
        visibility: "hidden",
      },
    },
  },
  fonts: {
    heading: "Open Sans",
    body: "Jost",
  },
  fontSizes: {
    xs: "12px",
    sm: "14px",
    md: "16px",
    lg: "18px",
    xl: "20px",
    "2xl": "24px",
    "3xl": "28px",
    "4xl": "36px",
    "5xl": "74px",
    "6xl": "100px",
    "7xl": "130px",
  },
  colors: {
    brand: {
      bg: "#008ca5",
      offBlack: "#000213",
      offWhite: "#f6f8fa",
      accent: "#e93f79",
    },
  },
  config: {
    useSystemColorMode: false,
    initialColorMode: "light",
  },
});

Notice we have set the bodies visibility to hidden? We will be using some gsap animations soon and this will stop our animations from flashing on page mount.

Now we will need to add the ChakraProvider to the wrap-root.js file, import the theme and pass it into the ChakraProvider like so:

export const wrapRootElement = ({ element }) => (
  <ChakraProvider resetCSS theme={theme}> // <===== HERE
    <ApolloProvider client={client}>{element}</ApolloProvider>
  </ChakraProvider>
);

Next we want to add a way to access our fonts from google. We have already installed the package so create a gatsby-config.js file and add the following:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-google-fonts`,
      options: {
        fonts: [
          `Jost`,
          `Open Sans`,
          `source sans pro\:300,400,400i,700`, // you can also specify font weights and styles
        ],
        display: "swap",
      },
    },
  ],
};

It's important to add the display: 'swap' as this will swap out our font for the system font while the page loads, helping with performance.

In the components folder create two new files, layout.js and section.js . Then create a new folder called state and add loading.js and error.js files to it.

layout.js

import React from "react";
import { Flex, Box } from "@chakra-ui/react";

const Layout = ({ children }) => {
  return (
    <Box bgColor="brand.bg" h="100%" minH="100vh" w="100%" overflow="hidden">
      <Flex direction="column" m="0 auto" bgColor="brand.bg" p={3}>
        {children}
      </Flex>
    </Box>
  );
};

export default Layout;

section.js

import { Flex } from "@chakra-ui/react";
import React from "react";

const Section = ({ children, fullPage }) => {
  return (
    <Flex
      as="section"
      h={`${fullPage ? "100vh" : "100%"}`}
      direction="column"
      maxW="1440px"
      m="0 auto"
    >
      {children}
    </Flex>
  );
};

export default Section;

state/loading.js

import React from "react";
import Section from "./../section";
import { Flex, Spinner } from "@chakra-ui/react";

const Loading = () => {
  return (
    <Section>
      <Flex justify="center" align="center">
        <Spinner size="xl" />
      </Flex>
    </Section>
  );
};

export default Loading;

state/error.js

import React from "react";
import Section from "../section";
import { Flex, Text } from "@chakra-ui/react";

const Error = () => {
  return (
    <Section>
      <Flex justify="center" align="center">
        <Text>You broke it! Try turning it on and off again...</Text>
      </Flex>
    </Section>
  );
};

export default Error;

At the moment we have a bunch of files just hanging loose in the components folder, let's organize them into something more manageble. Create a event folder and a hero folder. Move the event.js , schedule.js, cod.js, content-transform.js and speaker.js files to the event folder. Still inside the event folder create container.js , heading.js and buy-ticket-button.js

container.js

import React from "react";
import { Box } from "@chakra-ui/react";

const Container = ({ children, ...rest }) => (
  <Box my={6} {...rest}>
    {children}
  </Box>
);

export default Container;

heading.js

import React from "react";
import { Text } from "@chakra-ui/react";

const Heading = ({ children }) => (
  <Text fontSize="2xl" m={0} textAlign="center" fontFamily="heading">
    {children}
  </Text>
);

export default Heading;

buy-ticket-button.js

import React from "react";
import { Button } from "@chakra-ui/react";

const BuyTicketButton = () => {
  return (
    <Button
      bg="brand.accent"
      h="70px"
      w="250px"
      px={2}
      transition="all .25s ease-in-out"
      boxShadow="-5px 5px #000"
      borderRadius={0}
      variant="outline"
      textTransform="uppercase"
      fontSize="lg"
      _active={{
        boxShadow: "-2px 2px #000",
        transform: "translate(-2px, 2px)",
      }}
      _hover={{
        boxShadow: "-2px 2px #000",
        transform: "translate(-2px, 2px)",
      }}
    >
      Buy a Ticket!
    </Button>
  );
};

export default BuyTicketButton;

Cool. Now let's update our previously created components.

event.js

import React from "react";
import { useQuery, gql } from "@apollo/client";
import Section from "../section";
import { Flex, Text, Grid, Image, Box } from "@chakra-ui/react";
import Error from "../state/error";
import Loading from "../state/loading";
import Speaker from "./speaker";
import Schedule from "./schedule";
import CoD from "./cod";
import BuyTicketButton from "./buy-ticket-button";
import Container from "./container";
import Heading from './heading';

const Event = ({ path }) => {
  const { loading, error, data } = useQuery(GET_CONFERENCE, {
    variables: {
      path: path,
    },
  });

  if (loading) {
    return <Loading />;
  }
  if (error) {
    return <Error />;
  }

  let title = data.catalogue.components[0].content.text;
  let logo = data.catalogue.components[1].content.images[0].variants[0].url;
  let codeOfConduct = data.catalogue.components[2].content.json;
  let speakersPath = data.catalogue.components[4].content.items.map(
    (node) => node.path
  );
  let schedulePath = data.catalogue.components[3].content.items[0].path;

  return (
    <Section>
      <Grid
        templateColumns="10% 1fr 10%"
        autoRows="auto"
        w={["95%", "1440px"]}
        m="2em auto"
        bgColor="brand.offWhite"
        gap={5}
        boxShadow="-3px 3px #000"
      >
        <Flex
          gridColumn={2}
          gridRow={1}
          justify="space-evenly"
          align="center"
        >
          <Box
            bgColor="brand.offBlack"
            p={6}
            lineHeight={1}
            transform="rotate(-5deg)"
            boxShadow="-3px 3px #e93f79"
          >
            <Text
              fontFamily="heading"
              fontSize={["xl", "5xl"]}
              color="brand.offWhite"
              fontWeight={700}
            >
              {title}
            </Text>
          </Box>
          <Image src={logo} boxSize={100} boxShadow="-3px 3px #e93f79" />
        </Flex>
        <Container gridRow={2} gridColumn={2} border="solid 1px" p={2} boxShadow="-3px 3px #000">
          <Heading>The Speakers</Heading>
          <Flex
            gridRow={2}
            gridColumn={2}
            p={2}
            justify="center"
            align="center"
            wrap="wrap"
            m="1em auto"
            maxW="1000px"
          >
            {speakersPath.map((path, index) => (
              <Speaker key={index} path={path} />
            ))}
          </Flex>
        </Container>
        <Container gridRow={3} gridColumn={2}>
          <Schedule path={schedulePath} />
        </Container>
        <Container gridRow={4} gridColumn={2}>
          <CoD cod={codeOfConduct} />
        </Container>
        <Container mx="auto" mb={6} gridRow={5} gridColumn={2}>
          <BuyTicketButton />
        </Container>
      </Grid>
    </Section>
  );
};

...query

schedule.js

import React from "react";
import { Box, Flex, Text } from "@chakra-ui/react";
import Loading from "../state/loading";
import Error from "../state/error";
import { useQuery, gql } from "@apollo/client";
import Heading from "./heading";
import Container from "./container";

const Schedule = ({ path }) => {
  const { loading, error, data } = useQuery(GET_SCHEDULE, {
    variables: {
      path: path,
    },
  });

  if (loading) {
    return <Loading />;
  }
  if (error) {
    return <Error />;
  }

  let title = data.catalogue.components[0].content.sections[0].title;
  let schedule = data.catalogue.components[0].content.sections[0].properties;

  return (
    <Flex
      justify="center"
      p={2}
      mx="auto"
      w={["300px", "1000px"]}
      direction="column"
    >
      <Container>
        <Heading>{title}</Heading>
      </Container>
      <Box as="table" cellPadding={6} mb={6}>
        <Box as="thead">
          <Box as="tr">
            <Box as="th" align="left" colSpan="-1">
              <Text
                fontSize={["md", "xl"]}
                fontWeight={600}
                fontFamily="heading"
              >
                Speaker
              </Text>
            </Box>
            <Box as="th" align="left">
              <Text
                fontSize={["md", "xl"]}
                fontWeight={600}
                fontFamily="heading"
              >
                Subject...
              </Text>
            </Box>
          </Box>
        </Box>

        <Box as="tbody">
          {schedule.map((node, index) => (
            <Box key={index} as="tr">
              <Box as="td" borderBottom="solid 1px" borderLeft="solid 1px">
                <Text fontSize={["md", "xl"]} fontFamily="body">
                  {node.key}
                </Text>
              </Box>
              <Box as="td" borderBottom="solid 1px" borderLeft="solid 1px">
                <Text fontSize={["md", "xl"]} fontFamily="body">
                  {node.value}
                </Text>
              </Box>
            </Box>
          ))}
        </Box>
      </Box>
    </Flex>
  );
};

Most Chakra component are based on the Box component, which itself is polymorphic and can be changed to represent any semantic html element. So in this case we have used it to re-create the html table. The upside of this is that we are able to use the Chakra props while keeping our code semantically correct.

content-transform.js

import React from "react";
import CrystallizeContent from "@crystallize/content-transformer/react";
import { Text } from "@chakra-ui/react";

const ContentTransform = (props) => {
  const overrides = {
    paragraph({ metadata, renderNode, ...rest }) {
      return (
        <Text fontSize={props.fontSize} my={2}>
          {renderNode(rest)}
        </Text>
      );
    },
  };

  return <CrystallizeContent {...props} overrides={overrides} />;
};

export default ContentTransform;

speaker.js

import { Flex, Image, Text, Box } from "@chakra-ui/react";
import React from "react";
import { useQuery, gql } from "@apollo/client";
import Loading from "../state/loading";
import Error from "../state/error";
import ContentTransform from "./content-transform";
import { RoughNotation } from "react-rough-notation";

const Speaker = ({ path }) => {
  const { loading, error, data } = useQuery(GET_SPEAKER, {
    variables: {
      path: path,
    },
  });

  if (loading) {
    return <Loading />;
  }
  if (error) {
    return <Error />;
  }

  let image = data.catalogue.components[1].content.images[0].variants[0].url;
  let name = data.catalogue.components[0].content.json;
  let company = data.catalogue.components[2].content.text;
  let bio = data.catalogue.components[3].content.json;
  let twitter = data.catalogue.components[4].content.text;

  return (
    <Flex direction="column" p={2} align="center" minH="300px">
      <Image mb={3} src={image} borderRadius="full" boxSize={100} />
      <RoughNotation
        type="highlight"
        strokeWidth={2}
        padding={0}
        show={true}
        color="#e93f79"
      >
        <ContentTransform fontSize="xl" {...name} />
      </RoughNotation>
      <Text fontSize="md" fontWeight={600} my={3}>
        {company}
      </Text>
      <Box maxW="300px" align="center">
        <ContentTransform {...bio} />
      </Box>
      <Text fontWeight={600} fontSize="md" my={3}>
        {twitter}
      </Text>
    </Flex>
  );
};

cod.js

import { Flex } from "@chakra-ui/react";
import React from "react";
import ContentTransform from "./content-transform";
import Heading from "./heading";
import Container from "./container";

const CoD = ({ cod }) => {
  return (
    <Flex
      mb={3}
      direction="column"
      align="center"
      justify="center"
      p={2}
      m="2em auto"
      boxShadow="-3px 3px #000"
      border="solid 1px"
      w={["300px", "1000px"]}
    >
      <Container>
        <Heading>Code of Conduct</Heading>
      </Container>
      <ContentTransform {...cod} />
    </Flex>
  );
};

export default CoD;

If you now run yarn z your website will look a damn site nicer, but it's lacking some movement. Let's spice things up with some snazzy animations. In the hero folder create 2 new files hero.js and square.js

square.js

import { Box } from "@chakra-ui/react";
import React from "react";

const Square = ({ color, shadowColor, className }) => {
  return (
    <Box
      className={className}
      bgColor={color}
      w="30px"
      h="30px"
      boxShadow={`-3px 3px ${shadowColor}`}
      borderRadius={0}
    />
  );
};

export default Square;

hero.js

import React from "react";
import gsap from "gsap";
import { Flex, Grid, Text } from "@chakra-ui/react";
import Square from "./square";
import Section from "../section";

const Hero = () => {
  // create (9x4) Square elements and attach the Square class
  const topSquaresLeft = Array.from(Array(36)).map((_, index) => {
    return (
      <Square
        key={`${index}-topLeft`}
        className="topLeft"
        color="#000213"
        shadowColor="#fff"
      />
    );
  });
  // create (5x4) Square elements and attach the Square class
  const topSquaresRight = Array.from(Array(20)).map((_, index) => {
    return (
      <Square
        key={`${index}-topRight`}
        className="topRight"
        color="#e93f79"
        shadowColor="#000"
      />
    );
  });
  const bottomSquaresLeft = Array.from(Array(36)).map((_, index) => {
    return (
      <Square
        key={`${index}-bottomLeft`}
        className="bottomLeft"
        color="#000213"
        shadowColor="#fff"
      />
    );
  });
  // create (5x4) Square elements and attach the Square class
  const bottomSquaresRight = Array.from(Array(20)).map((_, index) => {
    return (
      <Square
        key={`${index}-bottomLeft`}
        className="bottomRight"
        color="#e93f79"
        shadowColor="#000"
      />
    );
  });

  React.useEffect(() => {
    gsap.to("body", { visibility: "visible" });

    let TL = gsap.timeline();
    TL.from(".topLeft", {
      y: window.innerHeight * 1,
      x: window.innerWidth * -1,
      duration: 0.5,
      ease: "back.out(1.3)",
      stagger: {
        grid: [9, 4],
        from: "random",
        amount: 1.5,
      },
    });
    TL.from(
      ".topRight",
      {
        y: window.innerHeight * -1,
        x: window.innerWidth * 1,
        duration: 0.6,
        ease: "back.out(1.4)",
        stagger: {
          grid: [5, 4],
          from: "random",
          amount: 1.5,
        },
      },
      "-=1.2"
    );
    TL.from(
      ".title",
      {
        opacity: 0,
        duration: 1,
      },
      "-=1.2"
    );
    TL.from(
      ".bottomLeft",
      {
        y: window.innerHeight * -1,
        x: window.innerWidth * 1,
        duration: 0.7,
        ease: "back.out(1.5)",
        stagger: {
          grid: [9, 4],
          from: "random",
          amount: 1.5,
        },
      },
      "-=1.2"
    );
    TL.from(
      ".bottomRight",
      {
        y: window.innerHeight * 1,
        x: window.innerWidth * -1,
        duration: 0.8,
        ease: "back.out(1.6)",
        stagger: {
          grid: [5, 4],
          from: "random",
          amount: 1.5,
        },
      },
      "-=1.2"
    );
  }, []);

  return (
    <Section fullPage>
      <Flex m="0 auto">
        <Grid
          w="100%"
          templateColumns="repeat(9, 80px)"
          templateRows="repeat(4, 80px)"
          placeItems="center"
          display={["none", "grid"]}
        >
          {topSquaresLeft.map((Square) => Square)}
        </Grid>
        <Grid
          w="100%"
          templateColumns="repeat(5, 80px)"
          templateRows="repeat(4, 80px)"
          placeItems="center"
          display={["none", "grid"]}
        >
          {topSquaresRight.map((Square) => Square)}
        </Grid>
      </Flex>
      <Flex p={5} align="center" justify="center" w="100%">
        <Text
          textTransform="uppercase"
          fontFamily="heading"
          fontSize="6xl"
          fontWeight={700}
          color="brand.offWhite"
          className="title"
          letterSpacing={[2, 5]}
          textShadow={[
            null,
            "-3px -3px 0px #fff, 3px -3px 0px #fff, -3px 3px 0px #fff, 3px 3px 0px #fff, 4px 4px 0px #000, 5px 5px 0px #000, 6px 6px 0px #000, 7px 7px 0px #000, 8px 8px 0px #000, 9px 9px 0px #000",
          ]}
        >
          The conf vault
        </Text>
      </Flex>
      <Flex m="0 auto">
        <Grid
          w="100%"
          templateColumns="repeat(9, 80px)"
          templateRows="repeat(4, 80px)"
          placeItems="center"
          display={["none", "grid"]}
        >
          {bottomSquaresLeft.map((Square) => Square)}
        </Grid>
        <Grid
          w="100%"
          templateColumns="repeat(5, 80px)"
          templateRows="repeat(4, 80px)"
          placeItems="center"
          display={["none", "grid"]}
        >
          {bottomSquaresRight.map((Square) => Square)}
        </Grid>
      </Flex>
    </Section>
  );
};

export default Hero;

That's quite alot of information to take in, let's step through it.

We create an array of 36 elements (a grid of 9x4) and map over the indexes returning the square component. It's named topSquaresLeft, we then do the same for each corner or the page.
In the useEffect hook we set the body visibility to visible. We then create a gsap timeline. (The inner workings of gsap will not be covered here, their docs are very good and would be a great place to start. I've also written some notes on gettings started with gsap, which you can find at richardhaines.dev/notes-on-gsap) With the timeline we initiate a staggered animation of all the boxes from each corner of the page, during this we animate the opacity of the title so that it gradually reveals itself during the boxes animations.
We setup 4 grids and map over each of our arrays of squares.

Finally update the index.js file, adding the layout, hero and state components.

import React from "react";

import { useQuery, gql } from "@apollo/client";
import Hero from "../components/hero/hero";
import Layout from "./../components/layout";
import Event from "../components/event/event";
import Loading from "../components/state/loading";
import Error from "../components/state/error";

export default function Index() {
  const { loading, error, data } = useQuery(GET_ROOT_PATHS);

  if (loading) {
    return <Loading />;
  }
  if (error) {
    return <Error />;
  }

  const conferencePaths = data.catalogue.children[0].children.map(
    (node) => node.path
  );

  return (
    <Layout>
      <Hero />
      {conferencePaths.map((path, index) => (
        <Event key={index} path={path} />
      ))}
    </Layout>
  );
}

Thanks for taking the time to read along, if you have any questions feel free to shoot me a message on Twitter @studio_hungry

Chakra-ui external link with SVG icon

Richard Haines — Tue, 01 Dec 2020 10:38:25 +0000

This articel was originally posted on my digital garden richardhaines.dev/chakra-external-link-with-svg-icon

I love using Chakra-ui, it's enabled me to develop faster and get my ideas down on the page so I can concentrate on other aspects of development. External links are not an issue to create, and Chakra isn't breaking any moulds with their implementation but the composability of their components allows for easy creation of a nice external link that uses an icon as its display piece. A library I like to use for icons is SimpleIcons, these are not your car, bird, desk or shop icons, rather a set of brand icons perfect for showing off what stack you currently indulge in or even as links to services you use. That will be our use case today, let's dive right in.

I'm going to assume you have Chakra-ui installed in your project.

The SVG

Head to simple icons and grab yourself the GitHub icon (or whatever icon takes your fancy) and download it. These svgs are small, their paths are for the most part not complicated and so we can just keep our file handy until later. In your project create a new file and name it the name of your icon, I will name mine GitHub. We will be taking advantage of polymorphism and the as prop which can be used on all Chakra primitives and enable us to set our generic Box component to act as an svg element semantically. (It's my understanding that all components derive from the Box component in Chakra). Import Box and set it as svg, then as children add the svg path that you downloaded earlier together with a title element.

import React from "react";
import { Box } from "@chakra-ui/core";

function Github() {
  return (
    <Box
      as="svg"
      role="img"
      width="20px"
      height="20px"
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 24 24"
      fill="#1f2127"
      _hover={{
        fill: "brand.accent",
      }}
    >
      <title>My GitHub Link</title>
      <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"></path>
    </Box>
  );
}

export default Github;

One of the reasons I really like this approach to creating icons in my projects is that I can utilize the Chakra theme setup i have to alter the icon with user interaction. In the above code you can see that I have added an on hover event which will change the fill of the svg when the mouse hovers over it. You can of course include style tags in your svgs and there are other way to do the same but this is pure simplicity and reads very well in my opinion.

The External Link

Now that we have our icon created we can create our external link. This wil really just be a wrapper around the native Chakra Link.

import React from "react";
import { Link } from "@chakra-ui/core";

const ExternalLink = ({ icon, href, ...rest }) => (
  <Link
    fontSize="xl"
    fontWeight={500}
    fontFamily="heading"
    color="brand.black"
    my={5}
    href={href}
    isExternal
    {...rest}
  >
    {icon}
  </Link>
);

export default ExternalLink;

We pass in our icon as a child to the component meaning the icon will render instead of any text. When the user hovers over the icon they will be able to read the title element text we set in the icon component. By setting the isExternal prop on the component we are telling Chakra to add some defaults such as referrerpolicy and rel. We also spread anything else we might want to pass in depending where we are rendering our component. As the Link component derives from the Box it inherits all of it's props so basically anything (style wise) can be passed onto it. Finally we pass in the href so that our link knows where to direct our users.

Using our new component is as simple as:

<ExternalLink
  icon={<Github />}
  href="https://github.com/molebox"
  gridColumn={3} // additional prop passed in
/>

Why i created a new digital garden

Richard Haines — Fri, 04 Sep 2020 12:06:59 +0000

This article was originally posted on my digital garden at garden.richardhaines.dev

So here we are, the likely hood is that you are reading this on said new digital garden. You've viewed the wacky home page, seen the silly cartoons references and navigated your way to this post. Or you just clicked on the link I posted on social media, either way you are here. So welcome!

I had taken a long time slowly adding features to my main site richardhaines.dev, I had wanted it to be a home base for everything that I created and wanted to share with the world. I'm still happy with it, it serves it's purpose rather well. I got to practice some GSAP animations, had my blog stationed there and also made a cool copy/paste page where I laid out a lot of the things I find myself copying over and over again.

The decision to move my digital garden over to a new subdomain came about through a want to create something silly, something in my own image. A place where I could not only house my writings but also experiment with designs, layout and animations without worrying about upsetting the flow of my main site. The thing is, when you take so long to build something you eventually become attached to it, be that a good or bad thing, and every change you make to that thing becomes smaller and smaller as time goes by. Upset that you might destroy the thing you worked so hard on to get to it's current stage.

I'd been interested in trying out NEXTJS for a while, I had dabbled rather briefly for a post I made that introduced Theme-ui into the mix but hadn't really made something. Dom Clark who I know through the Party Corgi discord had created a new project that combines NEXTJS and MDX which at it's core is a set of templates that aim to get the user up and running with an NEXTJS and MDX site as quickly as possible. I decided that this was a good opportunity to do a test run and see how easy it would be to get a site up and running using my current MDX files (which make up my digital garden).

Turns out it's super easy. The whole repo is geared up to get you writing and publishing content from the off. I literally just had to import my MDX files into a certain folder and BOOM it worked.

Seeing as it was so easy to get up and running I began experimenting with some ideas I had had previously but been too afraid to implement. And the result is this glorious explosion of colour and fun. This site is a playground for me to do whatever I want, safe in the knowledge that I've made it that way, for that reason. It will forever be WIP and that's the point. You never finish tending to your garden, you nurture it and watch it blossom into whatever form it takes.

Some links:

use-cloudinary hooks lib - Controlling your folders

Richard Haines — Fri, 21 Aug 2020 19:36:38 +0000

This article was originally published on my blog at garden.richardhaines.dev

Following on from my article about the use-cloudinary - useSearch hook, this time we'll be streamlining our code and diving into some of whats possible with when manipulating our cloudinary folders.

If we recount what we did last time:

A user could load their 3 previously saved images on the click of a button
The search expression told cloudinary that our type of media was image and that we wanted an exact match on the folders
Our serverless function set the mex results returned, in our case 3

This is a great, simple solution, but there is one problem. If we are stating that our user can only load their last 3 images but at the same time allowing them to save as many images as they like then we put ourselves and our cloudinary accounts credits at risk of being abused. This of course would be no fault of the users, we are the ones setting up the rules by which they should follow. No, alas it is our fault (well mine.... cough cough). Lets refactor a wee bit and see what we can do to make this process better.

Our search function will remain unchanged, our function will still search for an exact folder based on our users name. Our upload function however could do with some work.

The previous upload serverless function

const cloudinary = require("cloudinary").v2;
const dotenv = require("dotenv");
dotenv.config();

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET
});

exports.handler = async event => {
  const { file } = JSON.parse(event.body);
  const res = await cloudinary.uploader.upload(file, { ...JSON.parse(event.body) });
  return {
    statusCode: 200,
    body: JSON.stringify(res)
  };
};

The function takes and parses the passed in event, from which our file to upload is destructured and added to the cloudinary uploader function along with the rest of the image transformations. Cool.

The super duper upload serverless function

Brace yourselves.....here it comes....

const cloudinary = require("cloudinary").v2;
const dotenv = require("dotenv");
dotenv.config();

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET
});

// Upload an image with a max of 3 images in a folder
exports.handler = async event => {
  const { file } = JSON.parse(event.body);
  const body = JSON.parse(event.body);
  // extract the folder from the public_id
  const folder = body.public_id.split("/")[0];

  // get the images of the folder and sort them by the uploaded date
  const searchRes = await cloudinary.search
    .expression(folder)
    .sort_by("uploaded_at")
    .execute()
    .then(searchResult => searchResult);

  // if the folder contains 3 images then delete the oldest one
  if (searchRes.resources.length === 3) {
    await cloudinary.uploader.destroy(searchRes.resources[searchRes.resources.length - 1].public_id);
  }

  // upload our new image to the folder
  const res = await cloudinary.uploader.upload(file, { ...JSON.parse(event.body) });
  return {
    statusCode: 200,
    body: JSON.stringify(res)
  };
};

We'll go through this step by step to understand whats going on.

As with all our serverless functions it takes an event. We parse and destructure the file that we want to upload and parse the body. We could do this in one but I like to split it out so its easy to read.
We extract the folder name from the files public_id, grabbing anything before the forward slash.
We run our cloudinary search function and pass our folder as the expression to search for.
We sort the results by their uploaded_at date. This will give us the latest uploads first.
Notice that we have not included a max_results in this search. This means that we will get back all of the images in the folder.
We then check if the returned arrays length is equal to 3, as we only want to have 3 images max in our folder. If their are 3 images we want to remove the oldest one as we will soon be uploading a new image to the folder.
Cloudinary has a handy destroy function which along with an optional callback accepts the public_id of the image you wish to remove.
We pass in the last index of the search results array, as that will be our oldest entry.
Finally we upload our new image to the same folder and return that wonderful 200 and the results!

Now we have ensured that our cloudinary credits are safe from those pesky image uploaders. Our folder is set to only accept 3 images. Of course we could choose any number we like. In an up coming tutorial series I'll walk you through creating an authenticated photo album library which will extensively use this hooks library and cloudinary.