DEV Community: Andrew Shearer

git commit -m is a lie! How to commit like a pro

Andrew Shearer — Mon, 10 Jun 2024 22:21:30 +0000

When you first started learning git, you probably learned that the way to commit something is by using git commit -m "your message". This is fine as a beginner, but once you start working in a professional environment, you'll quickly realize that using -m is insufficient. In this article, I'll cover some different ways to commit your changes, as well as some handy git tricks.

The -m flag is the most basic way to commit your changes. It's fine for small changes, but it's not very useful for larger commits. When you use -m, you're limited to a single line of text, which can make it difficult to explain what you're doing. For example, if you're fixing a bug, you might want to explain what the bug was and how you fixed it. With -m, you're limited to something like this:

git commit -m "Fixed bug"

This is not ideal as it doesn't give much information. If you want to provide more information, you can use the -m flag multiple times:

git commit -m "Fixed bug" -m "The bug was caused by a missing semicolon"

If you haven't seen this pattern before, you can think of it like this:

git commit -m "Title" -m "Description"

Instead, what would be even better, is to to write a multi-line commit message. Doing this allows you to not only provide a title and description, but the ability to write a much more detailed description of why you made the changes that you did, and provide any other relevant information.

The simplest way of doing this is to configure your editor to be the default editor for git. Listed below, I've included a few examples of how to do this for some popular editors:

# For VS Code
git config --global core.editor "code --wait"

# For Sublime Text
git config --global core.editor "subl -n -w"

# For Vim
git config --global core.editor "vim"

# For Emacs
git config --global core.editor "emacs"

Configuring your editor in this way not only provides you with the benefit of being able to write a more detailed commit message, but it also allows you to easily update your global git configuration file.

Now let's say it's time to commit something. Since you've configured your editor to be the default editor for git, now run the commit command without the -m flag:

git commit

This will open up your editor, which for VS Code would look something like this:

Something else to note is when you're working on a team, it's likely you'll be following a commit message convention. This is especially true when you're working on a project with multiple people with an issue / project management tool such as Jira. It's convention to start your commit message with the Jira ticket number, followed by a colon, and then the title of your commit. It would look something like this:

This is looking a lot better! Once you're done writing, save and close the file, and your changes will be committed.

But, why? Why would you want to commit changes like this? There are a few reasons:

Clarity: Writing a multi-line commit message allows you to provide a clear and concise explanation of what you're doing. This is useful when you're working on a team, as it allows your teammates to quickly understand why you made the changes that you did. This is especially true when conducting code reviews on pull requests.
History: When you write a detailed commit message, you're creating a history of your changes. This can be useful if you ever need to go back and see why you made a particular change.
Documentation: A good commit message can serve as documentation for your code. If you ever need to go back and see why you made a particular change, you can look at the commit message to get a better understanding of what you were thinking at the time.

Another commit flag you may have used is -a. This flag is only semi-useful. The reason why I say that is that it will only commit previously tracked files. If you've created a new file as part of your current commit, you'll need to stage it first before using the -a flag. So, you'll need to use the add command for that.

With that in mind, I created a simple git alias for myself that will add all files to the staging area and then run the commit command without any flags. What is a git alias you may ask? A git alias is a way to create a shortcut for a git command, or a series of git commands.

To create a git alias, you'll need to add them to your global git configuration file. Since you've already configured your editor to be the default editor for git, you can run the following command to open up your global git configuration file:

git config --global -e

Now, add the following alias to the file:

[alias]
  ac = !git add . && git commit

Now, when you want to commit changes, you can run the following command:

git ac

I use this alias all the time, and it's a nice little time saver. Here are some other git aliases that I've created for myself that you might find useful:

[alias]
  cg = !git config --global -e
  cpom = !git checkout main && git pull origin main
  mm = !git merge main
  ru = !git remote update
  dasm = !git branch | grep -v "main" | xargs git branch -D

As a quick side note, if you're not sure what the last command is doing, it's deleting all local branches except for the main branch. This is useful if you're working on a project with a lot of branches and you're lazy like me and forget to delete them once they're merged into main.

I also created this extremely simple repo on GitHub that you can see the difference in the commits:

https://github.com/andrews1022/commit-example/commits/main/

I hope you found this article helpful! Let me know if you have any questions, or leave a comment if you have any other git tips and tricks you'd like to share.

Build an Express App Using Bun and Deploy It To Render With Docker

Andrew Shearer — Wed, 25 Oct 2023 15:30:49 +0000

In this post, we will scaffold a simple Express project using Bun, and then deploy it to Render using Docker. You’ll also get to see how much easier it is to get up and running locally with Bun than it is with Node.

Let’s get started!

Initial Setup

To get started, run this command to setup a Bun project in the folder of your choice:

bun init -y

Next, let’s make this a repo. Setup one on GitHub, then run the following commands:

git init
git branch -M main
git add .
git commit
git remote add origin https://github.com/YOUR_GITHUB_USERNAME/YOUR_REPO_NAME.git
git push -u origin main

Now add express and its @types package:

bun add express @types/express

Update index.ts with this:

import express from "express";

const app = express();
const port = 8080;

app.get("/", (req, res) => {
  // send a simple json response
  res.json({ message: "Hello World!" });
});

app.listen(port, () => {
  console.log(`Listening on port ${port}...`);
});

To test the local Express server, run this command:

bun index.ts

Then if you visit http://localhost:8080/ in the browser, or send a GET request to that URL with something like Postman / Insomnia, you should see the JSON response:

{
    "message": "Hello World!"
}

However, it would be nice to hot reload the server when we make changes, say to the response sent in app.get().

Thankfully, Bun has built in hot reload support. We can run this command instead:

bun --hot run index.ts

So now if we change the res.json() to this:

app.get("/", (req, res) => {
  // send a simple json response
  res.json({ message: "Hello from Bun & Express!" });
});

And if you then refresh the browser page or resent your GET request, you should see the updated JSON response:

{
    "message": "Hello from Bun & Express!"
}

Let’s add this as a script to our package.json:

"scripts": {
  "dev": "bun --hot run index.ts"
}

Now we can just run bun run dev instead. Noice!

Comparison to Node

Now, let’s take a look at a simplified breakdown of what it would take to reproduce the same result using Node:

Create a package.json: npm init -y
Create a tsconfig.json: npx tsc --init
Create index.ts: touch index.ts
Install packages: npm i express @types/express concurrently nodemon
Add the same boilerplate Express code to index.ts
Watching file changes: "dev": "concurrently \"npx tsc --watch\" \"nodemon -q dist/index.js\"”

As you can see, here there are a few extra steps, and certain things that Bun does for us automatically, such as creating the tsconfig.json and index.ts, we have to do ourselves. We also have to install a few extra dependencies (concurrently and nodemon) to get the server up and running as well.

Please don’t take this as me bashing Node, that’s not my intention at all. All I’m trying to show is how much simpler things are with Bun, and I was honestly just so shocked at how fewer steps there were, and it’s provided a better developer experience in my opinion. I definitely think Bun is worth installing and trying out!

Deploying to Render using Docker

Setup Docker

At the root level of the project, run the following command to create the necessary Docker related files:

touch Dockerfile .dockerignore

Add the following code to Dockerfile:

# Dockerfile

# use the official Bun image
# see all versions at https://hub.docker.com/r/oven/bun/tags
FROM oven/bun:1 as base
WORKDIR /usr/src/app

# install dependencies into temp folder
# this will cache them and speed up future builds
FROM base AS install
RUN mkdir -p /temp/dev
COPY package.json bun.lockb /temp/dev/
RUN cd /temp/dev && bun install --frozen-lockfile

# install with --production (exclude devDependencies)
RUN mkdir -p /temp/prod
COPY package.json bun.lockb /temp/prod/
RUN cd /temp/prod && bun install --frozen-lockfile --production

# copy node_modules from temp folder
# then copy all (non-ignored) project files into the image
FROM install AS prerelease
COPY --from=install /temp/dev/node_modules node_modules
COPY . .

# [optional] tests & build
# ENV NODE_ENV=production
# RUN bun test
# RUN bun run build

# copy production dependencies and source code into final image
FROM base AS release
COPY --from=install /temp/prod/node_modules node_modules
COPY --from=prerelease /usr/src/app/index.ts .
COPY --from=prerelease /usr/src/app/package.json .

# run the app
USER bun
EXPOSE 3000/tcp
CMD ["bun", "run", "dev"]

Add the following code to .dockerignore:

# .dockerignore

node_modules
Dockerfile*
docker-compose*
.dockerignore
.git
.gitignore
README.md
LICENSE
.vscode
Makefile
helm-charts
.env
.editorconfig
.idea
coverage*

You can test the Dockerfile locally if you have Docker installed by running the following command:

docker build --pull -t bun-express .
docker run -d -p 8080:8080 bun-express

If you should encounter the following error message during the build process:

error: lockfile had changes, but lockfile is frozen

This happens because it is likely that the bun.lockb file is not up to date. Simply run bun install to download and reinstall all the packages, and the issue should be resolved.

Make sure to push up any changes to your repo on GitHub at this point.

Deploy to Render

Next, we can deploy the app to Render. There are of course tons of options to deploy an application in a Docker Container, I just found Render to be very beginner friendly and easy to use.

Create a free account, and once you’re logged in, on the dashboard page, click New Web Service.

Make sure Build and deploy from a Git repository is selected, and click Next.

Click the big purple Connect Repository button.

Select where you want to install Render, and then select if you want to install it for all your repos, or just a select few. I chose to install it just for this repo.

Click Install.

You should be back on the Render dashboard, and see the repo listed. Click the Connect button next to it.

Give it a name, I called mine bun-express-render.

Select the Region best suited to you.

Ensure the Branch is set to main.

The Runtime should automatically be set to Docker.

You can start with the Free tier.

Click Create Web Service.

The build will take a few minutes.

Once the build is finished, if you visit the URL, you should see the message!

And that’s it! You’ve now created an Express app using TypeScript with Bun, and deployed it to Render using Docker!

Finally, here is a link to my repo with the full source code you can use as a reference in case you get stuck.

Cheers, and happy coding!

Deploy a Full Stack Next.js App to a DigitalOcean VPS With Docker

Andrew Shearer — Fri, 06 Oct 2023 19:46:25 +0000

Project Info

In this tutorial, we will be creating a simple full stack note taking app using:

Next.js + Tailwind
Drizzle ORM
PostgreSQL
DBeaver
DigitalOcean
Docker

While the app itself is very simple, the main focus here is to learn how to:

Setup a PostgreSQL database locally
Deploy the app to a DigitalOcean VPS using Docker containers

The functionality of the app is:

Have a page to view all notes
On the same page, have form to create a note using server actions

So, not full CRUD, and no auth.

It’s a great pipeline to know how to navigate, but there will be some cost involved. I’ll try to keep costs as low as I can.

Let’s get started!

Setting Up PostgreSQL & DBeaver

Download page PostgreSQL here

Download page for DBeaver here

I am going to provide the steps I took to get PostgreSQL with DBeaver up and running locally, you might need to Google for your specific OS (I am on Ubuntu).

First, we need to install PostgreSQL:

sudo apt update
sudo apt install postgresql postgresql-contrib

You can check the installation was successful by running:

psql --version
# psql (PostgreSQL) 16.0 (Ubuntu 16.0-1.pgdg22.04+1)

During the installation, PostgreSQL will create a default user called postgres. You can set a password for this user by running this command:

sudo -u postgres psql postgres

You’ll enter the postgres console. Once there, enter:

\password postgres

Since this is just a local database to play around with, I'm not too concerned about security at this point. So for the local db, the username, password, and database name will all be postgres.

Enter a password, then enter this to quit the psql console:

\q
# or 
exit

I will be using DBeaver as my database admin GUI of choice. It’s free, and available on all 3 major OS’s(Windows, Mac, & Linux). If you already have a tool you prefer to use, then of course stick with that.

Open DBeaver, and in the top menu bar, select Database, then New Database Connection

Settings:

Connect by Host
URL, Host, and Port can all be left alone
Database, username, and password should all be postgres

Click Test Connection

If you see a response like this:

You’re good to go!

FYI: If you did not set a password for the default postgres user, the connection test would always fail.

Click Ok, then click Finish

Setup Next.js App

Then in a folder of your choice, download and setup the latest Next.js TypeScript starter:

npx create-next-app@latest --ts .

If you are getting warnings in your CSS file complaining about unknown CSS rules, follow these steps here.

Still in globals.css, update the code with this reset from Josh Comeau.

/* src/app/globals.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

*, *::before, *::after {
  box-sizing: border-box;
}

* {
  margin: 0;
    padding: 0;
}

body {
  line-height: 1.5;
  -webkit-font-smoothing: antialiased;
}

img, picture, video, canvas, svg {
  display: block;
  max-width: 100%;
}

input, button, textarea, select {
  font: inherit;
}

p, h1, h2, h3, h4, h5, h6 {
  overflow-wrap: break-word;
}

#root, #__next {
  isolation: isolate;
}

Update tsconfig.json to this:

{
  "compilerOptions": {
    "target": "esnext",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Update src/app/page.tsx to this:

// src/app/page.tsx

const HomePage = () => {
  return (
    <div>
      <h1>HomePage</h1>
    </div>
  );
};

export default HomePage;

Update src/app/layout.tsx to this:

import { Inter } from "next/font/google";

import type { Metadata } from "next";
import type { ReactNode } from "react";

import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  description: "Generated by create next app",
  title: "VPS Demo"
};

type RootLayoutProps = {
  children: ReactNode;
};

const RootLayout = ({ children }: RootLayoutProps) => {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
};

export default RootLayout;

Setup GitHub Repo

I’m a fan of setting up a GitHub repo early and committing + pushing often in smaller chunks.

I’m going to assume that you know how to do that, so please do so before continuing.

Setup Drizzle

Link to Drizzle ORM docs here

Install the necessary packages:

npm i drizzle-orm postgres dotenv
npm i -D drizzle-kit

At the root level of the project, create a file called drizzle.config.ts

Add this code to it:

// drizzle.config.ts

import dotenv from "dotenv";
import type { Config } from "drizzle-kit";

// this is needed for pushing
dotenv.config({ path: ".env.local" });

const config: Config = {
  schema: "./src/drizzle/schema.ts",
  out: "./src/drizzle",
  driver: "pg",
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!
  }
};

export default config;

We don’t have this drizzle folder and schema.ts yet, so create them at the specified location.

The schema.ts file can be blank for now.

We also don’t have an environment variable called DATABASE_URL yet either, so also at the root level, create a .env.local file.

Then in this file, add this:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"

Next, in the drizzle folder, create a file called config.ts

Add this code to it:

// src/drizzle/config.ts

import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";

import * as schema from "@/drizzle/schema";

const connectionString = process.env.DATABASE_URL || "";
const client = postgres(connectionString);
const db = drizzle(client, { schema });

export { client, db };

At this point, you should get a red underline for import * as schema, which makes sense since the file is currently blank. Let’s create a note table in the schema.

A note will have:

id (uuid)
name (text)
content (text)
color (text - will select from yellow, green, blue, purple in the ui)
created_at (timestamp)

Back in schema.ts, add the following:

// src/drizzle/schema.ts

import { timestamp, pgTable, text, uuid } from "drizzle-orm/pg-core";

export const notes = pgTable("notes", {
  id: uuid("id").defaultRandom().notNull().primaryKey(),
  name: text("name").notNull(),
  content: text("content").notNull(),
  color: text("color").notNull(),
  created_at: timestamp("created_at").notNull().defaultNow()
});

Migrate & Push

Link to Migrations in the Drizzle docs here

Now that we have a model in our schema, we can migrate our database to your schema.

Add a generate script to package.json:

{
  // ...
  "scripts": {
    // ...
    "generate": "drizzle-kit generate:pg"
  }, 
}

Then in the terminal, run:

npm run generate

We can also push our schema changes directly to the database.

Add a push script to package.json:

{
  // ...
  "scripts": {
    // ...
    "push": "drizzle-kit push:pg"
  }, 
}

Then run the command:

npm run push

If the push was successful, you should now see a notes table in DBeaver!

And if you double click on it, and switch to the Data tab, you can see the table!

It’s empty for now, but that’s ok! This is a great start!

Pro-tip: create a single db command to run the generate and push commands one after the other:

"scripts": {
  // ...
  "generate": "drizzle-kit generate:pg",
  "push": "drizzle-kit push:pg",
  "db": "npm run generate && npm run push"
},

Setting Up Site Structure

For this simple app, we will have the following pages:

home
notes

You can copy and paste these commands to create all the files and folders at once:

cd src/app/
mkdir notes
cd notes/
touch page.tsx
cd ../../../

Here’s the boilerplate code for the page.tsx:

// src/app/notes/page.tsx

const NotesPage = () => {
  return (
    <div>
      <h1>NotesPage</h1>
    </div>
  );
};

export default NotesPage;

Next, create a folder called components in the src folder.

In the components folder, create a file called navbar.tsx and add the following code to it:

// src/components/navbar.tsx

import Link from "next/link";

const Navbar = () => {
  return (
    <nav className="border-b-black border-b-2 p-2">
      <ul className="flex items-center gap-x-4">
        <li>
          <Link className="hover:text-sky-500 hover:underline" href="/">
            Home
          </Link>
        </li>

        <li>
          <Link className="hover:text-sky-500 hover:underline" href="/notes">
            Notes
          </Link>
        </li>
      </ul>
    </nav>
  );
};

export { Navbar };

Then update the root layout.tsx file to use it (as well as wrap children within the main element and add some padding):

// src/app/layout.tsx

const RootLayout = ({ children }: RootLayoutProps) => {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Navbar />

        <main className="p-2">{children}</main>
      </body>
    </html>
  );
};

Create a Form to Create a Note

Link to Server Actions in Next.js docs here

Let’s add a form to the notes page.tsx that will add a Note into the database:

// src/app/notes/page.tsx

const NotesPage = () => {
  return (
    <div>
      <h1>NotesPage</h1>

      <form
        className="inline-flex items-start flex-col space-y-4 border-solid border-black border-2 p-4 mt-2 w-80"
        action={createNote}
      >
        <div className="w-full">
          <label htmlFor="name" className="block">
            Name:
          </label>

          <input
            id="name"
            name="name" // IMPORTANT: MAKE SURE TO INCLUDE A NAME FOR INPUTS
            type="text"
            className="border-solid border-black border-2 block w-full"
            required
          />
        </div>

        <div className="w-full">
          <label htmlFor="content" className="block">
            Content:
          </label>

          <textarea
            id="content"
            name="content"
            className="border-solid border-black border-2 block w-full"
            required
          />
        </div>

        <div className="w-full">
          <label htmlFor="color" className="block">
            Color:
          </label>

          <select
            id="color"
            name="color"
            className="border-solid border-black border-2 block w-full"
            required
          >
            <option value="">Select Color</option>
            <option value="yellow">Yellow</option>
            <option value="green">Green</option>
            <option value="blue">Blue</option>
            <option value="purple">Purple</option>
          </select>
        </div>

        <button
          className="border-solid border-black border-2 py-1 px-4 hover:bg-black hover:text-white w-full"
          type="submit"
        >
          Create Note
        </button>
      </form>
    </div>
  );
};

Previously, we would have to abstract this form out into its own component and add "use client" at the top.

Now, thanks to server actions, we can keep everything in this file and write an async function that will be used as the form’s action.

To get started, we need to enable Server Actions in our Next.js project by adding the experimental serverActions flag to the next.config.js file:

// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverActions: true
  }
};

module.exports = nextConfig;

Server Actions can be defined in two places:

Inside the component that uses it (Server Components only).
In a separate file (Client and Server Components), for reusability. You can define multiple Server Actions in a single file.

Before we setup our server action, let’s install zod as we can use it to validate the data from the form:

npm i zod

To keep things simple, we’ll define our action function here in the NotesPage component:

// src/app/notes/page.tsx

import { revalidatePath } from "next/cache";
import { z } from "zod";

import { db } from "@/drizzle/config";
import { notes } from "@/drizzle/schema";

const schema = z.object({
  name: z.string().min(1),
  content: z.string().min(1),
  color: z.string().min(1)
});

const NotesPage = () => {
  const createNote = async (formData: FormData) => {
    "use server";

    // validate data
    const validated = schema.parse({
      name: formData.get("name"),
      content: formData.get("content"),
      color: formData.get("color")
    });

    try {
      await db.insert(notes).values({
        name: validated.name,
        content: validated.content,
        color: validated.color
      });

      revalidatePath("/notes");

      return {
        message: "Note created successfully!",
        revalidated: true,
        now: Date.now()
      };
    } catch (error) {
      return {
        message: "Something went wrong when creating the note!"
      };
    }
  };

  return (
    <div>
      <h1>NotesPage</h1>

      <form
        className="inline-flex items-start flex-col space-y-4 border-solid border-black border-2 p-4 mt-2 w-80"
        action={createNote}
      >
        {/* ... */}
      </form>
    </div>
  );
};

Now, open up the DevTools and go to the Network tab and clear everything out.

Next, try to submit the form with something like this:

When you click Create Note, open up the DevTools and check the Network tab:

You’ll see it sends a POST request to the URL that we are currently on.

Not only that, but if you head over to DBeaver, you should see the note has been added to the database as well (you might need to click Refresh along the bottom of the window):

Fetch and Display Notes

Now let’s add another async function, this time outside the component body, to query the database and get all the notes:

// src/app/notes/page.tsx

const schema = z.object({
  // ...
});

const getNotes = async () => {
  try {
    const nts = await db.select().from(notes);

    return nts;
  } catch (error) {
    throw new Error("Something went wrong when fetching notes!");
  }
};

Then let’s update the page component to use it, as well as set up colorVariants for dynamic background color. I personally don't like this approach. I would much rather just use string interpolation within the className prop, but this is just how it's done with Tailwind:

// src/app/notes/page.tsx

// ...

const colorVariants = {
  blue: "bg-blue-200",
  green: "bg-green-200",
  purple: "bg-purple-200",
  yellow: "bg-yellow-200"
};

const NotesPage = async () => {
  const createNote = async (formData: FormData) => {
    "use server";

    // ...
  };

  const nts = await getNotes();

  return (
    <div>
      <h1 className="text-4xl">NotesPage</h1>

      <form
        className="inline-flex items-start flex-col space-y-4 border-solid border-black border-2 p-4 mt-2 w-80"
        action={createNote}
      >
          {/*  */}
      </form>

      <div className="mt-4">
              <h2 className="text-2xl">Notes</h2>

                <ul className="grid gap-4 grid-cols-12">
                  {nts.length
                    ? nts.map((nt) => {
                        // @ts-ignore
                        const colorClasses = colorVariants[nt.color];

                        return (
                          <li key={nt.id} className={`${colorClasses} col-span-2 p-4 rounded-lg`}>
                            <h3 className="text-xl font-semibold mb-1">{nt.name}</h3>
                            <p>{nt.content}</p>
                          </li>
                        );
                      })
                    : null}
                </ul>
            </div>
    </div>
  );
};

Now our notes will appear in a nice little grid!

Deploy - Prerequisites

Now time for the main attraction: deployment!

If you’ve never deployed a full-stack app like this before, it’s a great learning experience. It certainly was for me!

First, there are a few prerequisites:

Docker: Make sure you have Docker installed on your local machine.
Docker Compose: Install Docker Compose, which is a tool for defining and running multi-container Docker applications.
DigitalOcean Account: Set up a DigitalOcean account and create a VPS (Virtual Private Server) instance.

I’ll walk you through each of these steps now.

Docker and Docker Compose

You can check if docker is already installed on your machine by going to the root directory of your machine, and running this command:

docker --version
# Docker version 24.0.6, build ed223bc

If not, then you will need to check the installation instructions online to install Docker for your machine.

Similarly, you can run this command to check if docker compose is installed on your machine or not:

docker compose version
# Docker Compose version v2.20.3

You can find installation instructions for Docker Compose here.

DigitalOcean

Next, head over to DigitalOcean’s website and click Sign Up if don’t have an account, or Login if you already have one. I choose to Sign up with GitHub

If you chose to Sign up as well, here’s what I selected in the welcome screen:

What do you plan to build on DigitalOcean? A web or mobile application
What is your role or business type? Hobbyist or Student
What is your monthly spend on cloud infrastructure across cloud platforms? (Provide an estimate): $0 - $50
How many employees work at your company? I work alone

Click Submit

Add a payment method of your choice.

Once logged in, you should land on a page that looks like this:

https://cloud.digitalocean.com/welcome

I would suggest removing the /welcome part, and go straight to https://cloud.digitalocean.com/

This should redirect you to a /projects page, with a default project already created called first-project

First, we need to Create a Droplet

To do so, click the green Create button in the top right corner, and click Droplets from the dropdown menu

Choose a Region that is closest to your location

Leave Datacenter selection alone

For Choose an image, I stuck with the default Ubuntu on Version 23.04 x64

For Droplet Type, Basic (Plan selected) is the cheapest choice

For CPU options, I selected:

Premium Intel (Disk: NVMe SSD)
$8/mo - 1GB / 1 Intel CPU, 35GB NVMe SSDs, 1000GB transfer

For Choose Authentication Method, we will be using an SSH Key.

Thankfully DigitalOcean has a nice prompt saying “We can walk you through setting up your first SSH key”, which I will walk you through now. Click on Add SSH Key.

Creating an SSH Key

Open a terminal and run the following command (at the root level):

sudo ssh-keygen

You will be prompted to save and name the key.

I will save mine in the /usr/local/bin directory. Again, I am on Ubuntu, so you will need to pick a location that works for your machine.

/usr/local/bin/digital_ocean_ssh

Next you will be asked to create and confirm a passphrase for the key. This is highly recommended, and you can use a site like this one to generate a strong passphrase.

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

Store what you’ve entered into a text file, or the .env.local file as a comment, for now

You should see the following output:

Your identification has been saved in digital_ocean_ssh
Your public key has been saved in digital_ocean_ssh.pub
The key fingerprint is:
.....
The key's randomart image is:
.....

Copy and paste this output into the same location that you pasted the filename and password from the previous step.

We need to copy the contents of the .pub file into the SSH ley field in the modal

We can do that by running:

cat PATH_TO_YOUR_PUB_FILE
# ex: cat /usr/local/bin/digital_ocean_ssh.pub

Either way, once you run the command, you should see an output that starts like this:

ssh-rsa REALLY_LONG_ASS_STRING_HERE

Copy this, and paste it into the SSH key content input field back on DigitalOcean

Give it a name. I named mine DigitalOcean Next.js SSH

Click Add SSH Key

Finish Droplet Setup

Under options, you can click to Add improved metrics monitoring and alerting (free), since it is, well, free. The others are up to you.

Scroll down to Finalize Details

Add some tags if you want, I added a few:

next_js
digital_ocean
postgres

Click Create Droplet

Wait for the blue progress bar to finish, and eventually you should see a notification that the Droplet was added to the project.

Test Droplet Connection

Once your Droplet is created, you can access it via SSH.

Click on it, and copy the ipv4 address to the same text file / .env.local file as a comment.

Run this command at root level (double check the path):

ssh -i /PATH_TO_YOUR_SSH_FILE root@YOUR_DROPLET_IP
# ex: ssh -i /usr/local/bin/digital_ocean_ssh root@##.###.###.##

If you should see this:

Are you sure you want to continue connecting (yes/no/[fingerprint])?
Please type 'yes', 'no' or the fingerprint:

Enter in fingerprint, then yes

You will then see this:

Enter passphrase for key '/home/andrew/digital_ocean_ssh':

Copy and paste the passphrase you created earlier and hit Enter

You should now see your terminal change to the root of your droplet:

root@ubuntu-s-1vcpu-1gb-35gb-intel-sfo3-01:~#

You can exit anytime by running the exit command.

Create a PostgreSQL Database Cluster

Back at the main dashboard, click the green Create button in the top right corner, and click Databases from the dropdown menu.

Choose the datacenter region closest to you.

For the database engine, select PostgreSQL (v15).

Choose whichever database configuration that best suits your budget. The same goes for storage size. I went with 20GB.

Make sure the project selected is first-project.

When you’re ready, click the Create a Database Cluster.

It’ll take approximately 5 minutes for the database to finish provisioning.

Setup `Dockerfile` and `docker-compose.yml`

While the database is provisioning, let’s Dockerize our Next.js app

Head back to the code and add these 2 files at the root level of the project:

touch Dockerfile docker-compose.yml

In the Dockerfile, add the following code:

# Dockerfile

# Use an official Node.js runtime as the base image
FROM node:18-alpine

# Set the working directory in the container
WORKDIR /usr/src/app

# Copy package.json and package-lock.json to the container
COPY package.json package-lock.json ./

# Install dependencies
RUN npm install

# Copy the rest of the application files to the container
COPY . .

# Build the Next.js application for production
RUN npm run build

# Expose the application port (assuming your app runs on port 3000)
EXPOSE 3000

# Start the application
CMD ["npm", "start"]

And in the docker-compose.yml file, add the following:

# docker-compose.yml

version: "3"

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production

  db:
    image: postgres:latest
    environment:
      POSTGRES_USER: "${POSTGRES_USERNAME}"
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
      POSTGRES_DB: "${POSTGRES_DATABASE}"

As you can see, we are using environment variables for some of our values related to Postgres.

We want to keep this information secure, and not have it in plain sight.

While we already have a .env.local, the docker-compose.yml reads from .env only.

So, duplicate the .env.local file, and rename it to .env.

You will also want to make sure to update the .gitignore:

# local env files
.env
.env*.local

In the .env file, have the following:

# .env

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"

POSTGRES_USERNAME="postgres"
POSTGRES_PASSWORD="postgres"
POSTGRES_DATABASE="postgres"

Next, make sure to push these changes up to GitHub!

Finish DigitalOcean Postgres Setup

Head back over to DigitalOcean, and under the Getting Started section, skip ahead a bit and click on 4 Next Steps.

This will contain the migrate command that we will need shortly. Click the blue show-password link, and then copy / paste the command somewhere. You can click Hide.

Import Local DB To DigitalOcean

Since we already have a local PostgreSQL database, lets export it and then import that into DigitalOcean.

To export an existing database, we can use the pg_dump command (run this at the root level of your machine):

cd ~
pg_dump -h localhost -p 5432 -U postgres -d postgres -F c -b -v -f ~/Documents/db_backup.pgsql

When you run this command, it will prompt you for the password, which is also just postgres. I am on Ubuntu, so I chose the Documents folder for convenience sake. Feel free to update the path as needed.

Here’s a quick explanation of the command options:

h localhost: Specifies the host where your PostgreSQL server is running.
p 5432: Specifies the port number on which PostgreSQL is listening.
U postgres: Specifies the username to connect to the database.
d postgres: Specifies the name of the database you want to export.
F c: Specifies the custom format for the dump file.
b: Includes large objects in the dump.
v: Enables verbose mode to see the progress.
f ~/Documents/db_backup.dump: Specifies the output file path and name. In this case, the dump file will be saved in the Documents folder with the name db_backup.dump.

And there it is!

Now we need to import this into DigitalOcean.

But before we do, we can add a connection to our DigitalOcean PostgreSQL database in DBeaver. I think this is just nice to have, so we can make sure things are working properly.

In DBeaver, click Database and then New Database Connection

Select PostgreSQL

Have Connect by set to Host

The URL field will not be adjustable, but that’s ok as it will auto update with the information we provide.

Simply copy and paste the information from DigitalOcean into their respective field. When you copy + paste the host, you should see the URL update.

You will need to update the:

Host
Database
Port
Username
Password

Once you do, click Test Connection. If you see something like this:

You’re good to proceed! I'm simply cutting off most of the information within the popup.

Click Ok to close this little popup, and then click Finish

Once the connection has been added to your sidebar, you can rename it if you like to make it clearer what the connection is for:

You can also see here there are no tables, but like before with the local setup, that’s ok!

You can view the DigitalOcean docs on Importing a database here if you like.

To import the database, we’ll take the migrate command copied from earlier, and just add on the path to our db_backup.pgsql file:

PGPASSWORD=[YOUR_DB_PASSWORD] pg_restore -U [YOUR_DB_USERNAME] -h [YOUR_DB_HOST] -p [YOUR_DB_PORT] -d [YOUR_DB_NAME] ~/Documents/db_backup.pgsql

Once you run this, you should see an output like this:

pg_restore: error: could not execute query: ERROR:  must be member of role "postgres"
Command was: ALTER TABLE public.notes OWNER TO postgres;

pg_restore: warning: errors ignored on restore: 1

Which seems like something went wrong, but don’t worry! If you head over to DBeaver, you should see that the notes table has been added!

Deploy to Droplet Using Docker Compose

To get started, in a terminal window, SSH into your DigitalOcean VPS like before. Within our VPS, we’ll need to install the following:

Docker
Docker Compose
PostgreSQL

Thankfully, it’s very easy to do so.

Install Docker:

# Update the system packages
sudo apt update

# Install necessary packages to allow apt to use a repository over HTTPS
sudo apt install apt-transport-https ca-certificates curl software-properties-common

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update the system packages again
sudo apt update

# Install Docker
sudo apt install docker-ce docker-ce-cli containerd.io

Verify Docker installation:

docker --version
# Docker version 24.0.6, build ed223bc

Install Docker Compose:

# Download the latest version of Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# Make Docker Compose executable
sudo chmod +x /usr/local/bin/docker-compose

Verify Docker Compose installation:

docker compose version
# Docker Compose version v2.21.0

Install PostgreSQL:

sudo apt update
sudo apt install postgresql postgresql-contrib

Verify PostgreSQL installation:

psql --version
# psql (PostgreSQL) 15.4 (Ubuntu 15.4-0ubuntu0.23.04.1)

cd back to the root level, and if you run the command ls, all you should see listed is snap

Create a new directory called repos and cd into it

mkdir repos
cd repos/

In this repos folder, clone the GitHub repo you setup at the start by running:

git clone https://github.com/[YOUR_GITHUB_USERNAME]/[YOUR_REPO_LINK].git

Once the clone is complete, cd into the directory, and run ls to verify the contents:

cd [YOUR_REPO_NAME]
ls

# output:

# ls
Dockerfile  docker-compose.yml  next.config.js     package.json       public  tailwind.config.ts
README.md   drizzle.config.ts   package-lock.json  postcss.config.js  src     tsconfig.json

Great!

One issue here though is we don’t have an .env file, which makes sense since we added it to the .gitignore. Thankfully, it’s very easy to not only create this file, but write to it as well.

You can create it by running:

touch .env

And if you run ls again, it’s not there? What gives??

The .env file is considered a hidden file. To view hidden files only within the current directory, you can run this command:

ls -ld .?*

You should now see .env listed, along with .git and .gitignore.

What do we need to write the .env file?

We will need DATABASE_URL for our Drizzle config + schema, and as well as POSTGRES_USERNAME, POSTGRES_PASSWORD, and POSTGRES_DATABASE for our docker-compose.yml.

To write to the .env file, you can run the following command:

echo "DATABASE_URL=[YOUR_CONNECTION_STRING_URI]" > .env
echo "POSTGRES_DATABASE=[YOUR_DATABASE_NAME]" >> .env
echo "POSTGRES_USERNAME=[YOUR_DATABASE_USERNAME]" >> .env
echo "POSTGRES_PASSWORD=[YOUR_DATABASE_PASSWORD]" >> .env

You can get all the necessary info from your DigitalOcean dashboard. I’d recommend copying and pasting the above command into a text file so you can easily swap out the placeholders for your values, and then copy and paste all 4 lines at once with the correct values into your terminal to run them one after another.

You can then verify the write was successful by running the cat command:

cat .env

# output:
# DATABASE_URL=...
# POSTGRES_DATABASE=...
# POSTGRES_USERNAME=...
# POSTGRES_PASSWORD=...

Finally, we can start our services using Docker Compose in detached mode:

docker compose up -d

It may take a bit of time to start up the services. but after a while you should see something like this:

[+] Running 3/3
 ✔ Network [YOUR_REPO_NAME]_default  Created
 ✔ Container [YOUR_REPO_NAME]-db-1   Started
 ✔ Container [YOUR_REPO_NAME]-web-1  Started

Now, if you open a new browser tab and go to the following address:

http://[YOUR_DROPLET_IPV4_ADDRESS]:3000

Voila! Your app is now running in a VPS! 🎉

Outro

I really hope you enjoyed this post and found it helpful! Some next steps to consider would be to deploy the containers as a Kubernetes cluster on DigitalOcean. However, I am a Docker noobie, and setting up a cluster with HTTPS seems like it’s a bit out of reach for me at this time. I am very happy I went through this process, and I hope you enjoyed it as well. And going through this process has definitely motivated me to learn more about Docker and Kubernetes.

As always, here is a link to my repo with the full source code you can use as a reference in case you get stuck.

Cheers, and happy coding!

How To Manage Access and Refresh Tokens for an API in Next.js 13 With Supabase and Prisma

Andrew Shearer — Fri, 22 Sep 2023 22:30:04 +0000

This article will show you how to use the Trackmania API in a Next.js 13 app using TypeScript. The API uses access and refresh tokens, so it is not as easily accessible as other APIs, like jsonplaceholder , or an API where you can include the same key(s) with every request.

So, we will use Supabase as a Postgres database to store the tokens and Prisma as our ORM of choice to communicate with our database.

The main focus of this article is to show you how to store / retrieve these tokens for API use, NOT for user authentication. If you’re looking for user authentication, I’d recommend looking at an example here over on NextAuth’s website to get you started.

Let’s get started!

Initial Setup

Quickly download and setup the latest Next.js TypeScript starter:

npx create-next-app@latest --ts .

If you are getting warnings in your CSS file complaining about unknown CSS rules, follow these steps here

Still in globals.css, update the code with this reset from Josh Comeau

/* src/app/globals.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

*, *::before, *::after {
  box-sizing: border-box;
}

* {
  margin: 0;
    padding: 0;
}

body {
  line-height: 1.5;
  -webkit-font-smoothing: antialiased;
}

img, picture, video, canvas, svg {
  display: block;
  max-width: 100%;
}

input, button, textarea, select {
  font: inherit;
}

p, h1, h2, h3, h4, h5, h6 {
  overflow-wrap: break-word;
}

#root, #__next {
  isolation: isolate;
}

Update tsconfig.json to this:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "Node",
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Update src/app/page.tsx to this:

// src/app/page.tsx

const HomePage = () => {
  return (
    <div>
      <h1>HomePage</h1>
    </div>
  );
};

export default HomePage;

Update src/app/layout.tsx to this:

// src/app/layout.tsx

import { Inter } from "next/font/google";

import type { Metadata } from "next";
import type { ReactNode } from "react";

import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  description: "Generated by create next app",
  title: "Trackmania API Demo"
};

type RootLayoutProps = {
  children: ReactNode;
};

const RootLayout = ({ children }: RootLayoutProps) => {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
};

export default RootLayout;

GitHub & Vercel

I’m a fan of setting up a GitHub repo and deploying to Vercel early, and committing + pushing often in smaller chunks

This way, if the site should not build on Vercel, it’s a lot easier to figure when the issue started occurring.

I’m going to assume that since you’re doing this advanced tutorial that you:

Already know how to create a repo on GitHub and push your code up to it
Deploy a website from your Vercel dashboard by selecting the repo you’ve created

Please do both of these things before continuing.

Getting API Access Token

In order to use Nadeo’s Trackmania API, we need to get an access_token (which also comes with a refresh_token)

There are 2 approaches to get this:

Use a dedicated Ubisoft account
Create Server Account on trackmania.com

While it is true that to login to trackmania.com, you need a Ubisoft account anyways, the flow for refreshing the access_token is much simpler using a Server Account.

On trackmania.com, once you are signed in, click on your user name in the top right corner

In the dropdown, select My Server Accounts

Enter a value for the Server Login (you can think of this is a project name)

I’ll call mine: trackmania-api-demo

Click Submit

Once you do, a message will appear to Please copy the password

Copy the Login (the name you just entered, ie trackmania-api-demo) and password into a text file for now

Let’s use Postman (or a similar platform of your choice) to send requests first to make sure things will work before coding it all up.

Create a new request with the following:

Request type to POST
URL to https://prod.trackmania.core.nadeo.online/v2/authentication/token/basic
Under Authorization:
- Set the Type to Basic Auth
- For the Username and Password, copy / paste the Login and Password fields from the Server Account
Under Headers, add
- Content-Type: application/json
Under Body
- Set the type to raw, then select JSON
- Add this:
```
{
  "audience": "NadeoLiveServices"
}
```
- NOTE: We have to include this JSON object in the body because we need a way of telling the API what to authenticate with. You can see a mapping of APIs and available audiences here.

Click Send, and you should see a response like this:

{
  "accessToken":"eyJhbGciOiJIUzI1NiIsImVudiI6InRyYWNrbWFuaWEtcHJvZCIsInZlciI6IjEifQ.PAYLOAD.SIGNATURE",
  "refreshToken":"eyJhbGciOiJIUzI1NiIsImVudiI6InRyYWNrbWFuaWEtcHJvZCIsInZlciI6IjEifQ.PAYLOAD.SIGNATURE"
}

The start of the access_tokens, known as the HEADER, is always the same, so it’s safe to display them publicly like this. However, it’s the PAYLOAD and SIGNATURE parts of the tokens that are unique.

If you URL-base64-decode the PAYLOAD part of the accessToken, you get the following JSON object:

{
  "jti": "UUID_HERE",
  "iss": "NadeoServices",
  "iat": 1595191016,
  "rat": 1595192816,
  "exp": 1595194616,
  "aud": "NadeoLiveServices",
  "usg": "Server",
  "sid": "UUID_HERE",
  "sub": "UUID_HERE",
  "aun": "mm",
  "rtk": false,
  "pce": false
}

Here, exp defines the expiration time, and rat defines the time after which you are able to refresh the token.

To URL-base64-decode something in TypeScript, you can use a function like this:

const urlBase64Decode = (input: string) => {
  // decode the base64 string
  const base64Decoded = atob(input);

  // URL-decode the data
  const urlDecoded = decodeURIComponent(base64Decoded);

  // parse the JSON data
  return JSON.parse(urlDecoded);
};

Using the Access Token

To keep things simple, let’s try and fetch the data for a single map for now to make sure our access_token is working

Let’s fetch data for the first map in the current campaign (which at the time of writing, is Summer 2023-01)

We will need send a GET request to the following URL:

<https://live-services.trackmania.nadeo.live/api/token/map/MAP_UID>

To get a MAP_UID, head back to the official Trackmania site: https://www.trackmania.com/

Once there, click on Campaigns

Then click SUMMER 2023 - 01 on the next page

The URL will be this: https://www.trackmania.com/tracks/7hk8IflYsbMbpJv2gyYzx48Zvt7

The last part in the path, 7hk8IflYsbMbpJv2gyYzx48Zvt7, is the MAP_UID

Back in Postman, create another request tab and set the following:

Request type to GET
URL to https://live-services.trackmania.nadeo.live/api/token/map/7hk8IflYsbMbpJv2gyYzx48Zvt7
Under Headers, add
- Content-Type: application/json
- Authorization: nadeo_v1 t=YOUR_FULL_ACCESS_TOKEN
Under Body
- Set the type to raw, then select JSON
- Add this:
```
{
  "audience": "NadeoLiveServices"
}
```

Click Send, and you should see a response like this:

{
    "uid": "7hk8IflYsbMbpJv2gyYzx48Zvt7",
    "mapId": "a93f902b-16a1-4448-ad34-65cf32d41425",
    "name": "Summer 2023 - 01",
    "author": "d2372a08-a8a1-46cb-97fb-23a161d85ad0",
    "submitter": "d2372a08-a8a1-46cb-97fb-23a161d85ad0",
    "authorTime": 23997,
    "goldTime": 26000,
    "silverTime": 29000,
    "bronzeTime": 36000,
    "nbLaps": 0,
    "valid": false,
    "downloadUrl": "https://prod.trackmania.core.nadeo.online/storageObjects/5e1cd15d-0b55-4db7-98ad-a82656ceb112",
    "thumbnailUrl": "https://prod.trackmania.core.nadeo.online/storageObjects/fa836805-f906-41c1-9ca2-e52a63c4b44f.jpg",
    "uploadTimestamp": 1687274471,
    "updateTimestamp": 1687274472,
    "fileSize": null,
    "public": false,
    "favorite": false,
    "playable": true,
    "mapStyle": "",
    "mapType": "TrackMania\\TM_Race",
    "collectionName": "Stadium",
    "gamepadEditor": false
}

Hazah! If you’ve made it this far, congrats! This is a very good milestone to hit.

Planning Out the App

Ok, so now that we’ve tested some queries in Postman to ensure we get the responses we want, we should pause here and plan out how we want to do code wise:

Store the access_ and refresh_token in Supabase database
Check whether or not the current access_token is expired
If it is, make a request with the refresh_token to get a new one
Store the new access_token in the Supabase database

Most resources online I’ve seen suggest using a JWT to store the refresh_token. However, using a JWT to store the refresh_token is less secure than saving it in a database.

Instead, we will use Supabase to store our tokens, and use Prisma as our ORM of choice to read and write data to / from the database.

Install and Setup Prisma

First, let’s install Prisma as a devDependency

npm i -D prisma

Next, we can initialize Prisma by running:

npx prisma init

This will create an .env file as well as a prisma folder, both at the root level

NOTES:

Do NOT change .env file name to .env.local, it must stay as .env
The DATABASE_URL will need to be updated with the URL you get when creating a DB with Supabase later on

Setup PostgreSQL on Supabase

Create an account if you do not have one already

Once logged in, go to your Dashboard

On the dashboard page, click New project

Give it a name, something in kebal-case-like-this

Click generate a password

Copy and paste the generated password into the .env file as a comment for now

Change your region accordingly

Click Create new project

Navigate to the project settings (gear icon, very bottom of sidebar nav)

Click on Database

Under Connection string, click URI

Copy this value

Back in the .env file, replace the default DATABASE_URL with the URI you just copied.

Also update the [YOUR-PASSWORD] placeholder with the generated password from before.

Back in Supabase, click on the Database icon.

Under tables, there should be nothing there. But not for long!

Create Prisma Model Schema

Open the schema.prisma file generated earlier

We’ll add a simple ApiToken model:

model ApiToken {
  tokenId        String   @id @default(cuid())
  accessToken    String
  expirationDate DateTime
  refreshToken   String
}

This will be sufficient because we are not performing any auth, we are simply saving the keys in a secure location for when we want to reach out to the Trackmania API

While we’re at it, let’s also update the .env file with Trackmania Server Account login and password from earlier:

DATABASE_URL="..."

TM_SERVER_ACCOUNT_LOGIN="..."
TM_SERVER_ACCOUNT_PASSWORD="..."

We’ll need these whenever we make the initial POST request to get the tokens

Now we need to migrate

NOTE: also any time the schema is changed, you’ll have to migrate

Run this command:

npx prisma migrate dev --name init
# "init" at the end is the name of the migration

Go back to Supabase, and click on the Table Editor icon

You should now see a User table!

Install Prisma Client

Link to Prisma Client docs here

Install it:

npm install @prisma/client

Next, inside the src folder, create a folder called lib

In the lib folder, create a file called prisma.ts

There are some common / well known issues when working with Next.js and Prisma

There is a docs page about it here

Copy and paste this snippet (taken from the docs) into prisma.ts:

import { PrismaClient } from '@prisma/client'

const prismaClientSingleton = () => {
  return new PrismaClient()
}

type PrismaClientSingleton = ReturnType<typeof prismaClientSingleton>

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClientSingleton | undefined
}

const prisma = globalForPrisma.prisma ?? prismaClientSingleton()

export default prisma

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma

What this code does is when we are not in the production environment, and the Prisma client has already run, the PrismaClient won’t be initialized again and again every time we restart the server.

At this point, it’s a good idea to update our Environment Variables on Vercel with the values we’ve added.

From your dashboard, select the project you’ve created / deployed.

Click on Settings, then Environment Variables.

Add them here (you can actually copy / paste multiple at a time!).

Adding a Row in Supabase

Head over to Supabase, and enter in a row manually.

Perform a POST request in Postman to get an up-to-date access and refresh token

You can then use the urlBase64Decode function shown earlier to get the exp value

You can then use this function to create a Date string from that value:

const convertUnixTimestampToDate = (timestamp) => new Date(timestamp * 1000);

// example
convertUnixTimestampToDate(1695344641)
"Thu Sep 21 2023 18:04:01 GMT-0700 (Pacific Daylight Time)"

Use this value for the expirationDate

For the tokenId, you can also use this generateCUID function in a browser console to generate an id for you (thanks ChatGPT!):

function generateCUID() {
  // Define a list of characters that can be used in the CUID
  const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

  // Length of the CUID
  const length = 25;

  let cuid = 'c'; // Start with the letter 'c' to mark it as a CUID

  for (let i = 0; i < length; i++) {
    const randomIndex = Math.floor(Math.random() * characters.length);
    cuid += characters[randomIndex];
  }

  return cuid;
}

console.log(generateCUID());
// cVuBo6oMxjNbc7WKpMrT6lqQg3

Using Next.js `middleware`

Since we need to always be checking whether or not the access_token is valid or not, we need some code to run on every page

A simple way to implement this is by using middleware

Inside the src directory, create a file called middleware.ts

Add this code to it for now:

// src/middleware.ts

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

// This function can be marked `async` if using `await` inside
const middleware = (request: NextRequest) => {
  console.log("middleware is running!");

  // return NextResponse.json(request)
};

export { middleware };

Then if you run npm run dev, you should see the console.log when you visit / refresh the home page.

Next, let’s update this code to fetch the example row from Supabase we added earlier:

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import prisma from "./lib/prisma";

// This function can be marked `async` if using `await` inside
const middleware = async (request: NextRequest) => {
  // console.log("middleware running!!!");

  // return NextResponse.json(request)
  const apiTokenTest = await prisma.apiToken.findUnique({
    where: {
      tokenId: "c1Z1oSjpTT3REWxoeuK0xcWQBj"
    }
  });

  console.log("apiTokenTest: ", apiTokenTest);
};

export { middleware };

However, when we do this, we will get this error:

Error: PrismaClient is unable to run in Vercel Edge Functions. As an alternative, try Accelerate: https://pris.ly/d/accelerate. If this is unexpected, please open an issue: https://github.com/prisma/prisma/issues

At the time of writing, as the error says, PrismaClient is unable to run in Vercel Edge Functions.

Thankfully, it is being discussed and it looks like a solution is being worked on.

To get around this, we can use Prisma DataProxy.

To start, head over to https://cloud.prisma.io/ and create an account with your GitHub login.

Once you’ve authorized Prisma, go to your projects dashboard here (you also might automatically be directed to the create a project flow).

Click on Create classic project.

Copy and paste your DATABASE_URL from the .env file into the Connection string field.

Click Create project.

Add your GitHub profile if not selectable.

Select your repo, and make sure the branch is set to main.

Create a Data Proxy connection string, give it a name.

Copy the value, and head back to the code and open the .env file.

Rename the existing DATABASE_URL variable to MIGRATE_DATABASE_URL.

Then create a DATABASE_URL, this time setting it to the proxy connection string you just created.

The MIGRATE_DATABASE_URL will be used to apply and pending migration to the database as the app will be deployed on Vercel.

Next, open up the terminal and run:

npx prisma generate --data-proxy

This will generate a Prisma client that will use Prisma data proxy

Next, go to prisma.ts and adjust the import path of the PrismaClientlike so:

// before
import { PrismaClient } from "@prisma/client";

// after
import { PrismaClient } from "@prisma/client/edge";

After that, run npm run dev in the terminal, and you should now see the response:

apiTokenTest:  {
  tokenId: 'TOKEN_ID_HERE',
  accessToken: 'ACCESS_TOKEN_HERE',
  expirationDate: 2023-09-21T18:04:01.000Z,
  refreshToken: 'REFRESH_TOKEN_HERE'
}

Updating the Prisma Schema

We should update the ApiToken model to also have a addedOn field

This will help us get the row in the database that was added most recently

model ApiToken {
  tokenId        String   @id @default(cuid())
  accessToken    String
  expirationDate DateTime
  refreshToken   String
  addedOn        DateTime @default(now())
}

We will also need to add a directUrl property to the datasource db:

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("MIGRATE_DATABASE_URL") // <---
}

Again, the MIGRATE_DATABASE_URL is the old DATABASE_URL that was copied from Supabase.

Make sure to also add / update your Environment Variables on Vercel too!

Now we can run migrate command:

npx prisma migrate dev --name added_on_field

If you didn’t specify the directUrl, you would get an error. So that is why we added it.

Link to the docs page about using Prisma Migrate here

Finally, we will need to add this script to our package.json (as per Prisma docs here):

"postinstall": "prisma generate"

We do this because you would run into the following error message on deployment otherwise:

Prisma has detected that this project was built on Vercel, which caches dependencies.
This leads to an outdated Prisma Client because Prisma's auto-generation isn't triggered.
To fix this, make sure to run the `prisma generate` command during the build process.

Learn how: <https://pris.ly/d/vercel-build>

Updating the `middleware`

So now we can begin writing the necessary code to check our tokens in the database

But first, let’s setup a simple request on the home page knowing it will fail:

const getMapInfo = async () => {
  const mapUId = "7hk8IflYsbMbpJv2gyYzx48Zvt7";
  const url = `https://live-services.trackmania.nadeo.live/api/token/map/${mapUId}`;

  const res = await fetch(url, {
    method: "GET",
    headers: {
      "Content-Type": "application/json"
    }
  });

  if (!res.ok) {
    const text = await res.text(); // get the response body for more information

    throw new Error(`
      Failed to fetch data
      Status: ${res.status}
      Response: ${text}
    `);
  }

  return res.json();
};

const HomePage = async () => {
  const mapInfo = await getMapInfo();

  console.log("mapInfo: ", mapInfo);

  return (
    <div>
      <h1>HomePage</h1>

      <p>Track name:</p>
    </div>
  );
};

As you can see, we are missing the Authorization along with the accessToken. This is where middleware can help us.

We can use it to set headers on requests. We will use it to set the access_token on each request to the Trackmania API. In the end, it looks like this:

// src/middleware.ts

import { NextRequest, NextResponse } from "next/server";
import prisma from "./lib/prisma";
import { unixTimestampToDate, urlBase64Decode } from "./lib/utils";

import type { AuthTokenResp } from "./types";

const middleware = async (request: NextRequest) => {
  try {
    const mostRecentApiToken = await prisma.apiToken.findFirst({
      orderBy: {
        addedOn: "desc"
      }
    });

    if (mostRecentApiToken) {
      const { accessToken, expirationDate, refreshToken } = mostRecentApiToken;

      const tokenExpirationDate = new Date(expirationDate);
      const currentDate = new Date();

      // compare the current date to the expiration date
      if (currentDate > tokenExpirationDate) {
        console.log("the token is expired - get a new one");

        const url = "https://prod.trackmania.core.nadeo.online/v2/authentication/token/basic";
                const login = process.env.TM_SERVER_ACCOUNT_LOGIN;
        const password = process.env.TM_SERVER_ACCOUNT_PASSWORD;

        const res = await fetch(url, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Basic ${btoa(`${login}:${password}`)}`
          },
          body: JSON.stringify({
            audience: "NadeoLiveServices"
          })
        });

        if (!res.ok) {
          const text = await res.text(); // get the response body for more information

          throw new Error(`
            Failed to fetch data
            Status: ${res.status}
            Response: ${text}
          `);
        }

        const newTokens: AuthTokenResp = await res.json();
        const { accessToken: newAccessToken, refreshToken: newRefreshToken } = newTokens;

        const [header, payload, structure] = newAccessToken.split(".");
        const { exp, rat } = urlBase64Decode(payload);
        const newExpirationDate = unixTimestampToDate(rat);

        await prisma.apiToken.create({
          data: {
            accessToken: newAccessToken,
            expirationDate: newExpirationDate,
            refreshToken: newRefreshToken,
            addedOn: new Date()
          }
        });
      }

      console.log("the token is valid - you good!");

            // set a new response header "Authorization"
      const response = NextResponse.next();
      response.headers.set("Authorization", `nadeo_v1 t=${accessToken}`);
      return response;
    }
  } catch (error) {
    return NextResponse.json(
      {
        message: "Something went wrong!"
      },
      {
        status: 500
      }
    );
  }
};

export { middleware };

That’s quite a lot! Let’s break it down:

First, we the most recent row in the database by using the addedOn field
Then, we check we have something we can work with
If we do, destructure the accessToken, expirationDate, and refreshToken variables out of mostRecentApiToken
We then check if the currentDate is greater than tokenExpirationDate
If it is, that means the access_token is expired and we need to get a new one
- We then make the necessary POST request, using the refresh token for the Authorization header
- We then add on a type annotation of AuthTokenResp, seen below, to the newTokens:
```
// src/types/index.ts

type AuthTokenResp = {
  accessToken: string;
  refreshToken: string;
};
```
- When the destructure again, this time using aliases to avoid naming conflicts
- We then split the access_token into 3 parts, mostly just for the payload
- We then run the payload through our urlBase64Decode function, which itself now has an updated return type DecodedPayload. That type looks like this:
```
// src/types/index.ts

type DecodedPayload = {
  aud: string;
  aun: string;
  exp: number;
  iat: number;
  iss: string;
  jti: string;
  pce: boolean;
  rat: number;
  rtk: boolean;
  sid: string;
  sub: string;
  usg: string;
};
```
- We can then destructure yet again, this time getting the value for rat
- We then run the rat value through a unixTimestampToDate conversion function, which looks like this:
```
const unixTimestampToDate = (unixTimestamp: number): Date => {
  return new Date(unixTimestamp * 1000);
};
```
- Finally, after all that, we can properly setup the create call to add the new tokens to the database
And outside this expiration check, we set new a Authorization header using the most recent access token

Whew!

Now we can go back to the home page and adjust our query:

// src/app/page.tsx

import { headers } from "next/headers";
import type { TrackmaniaTrack } from "@/types";

const getMapInfo = async (): Promise<TrackmaniaTrack> => {
  const mapUId = "7hk8IflYsbMbpJv2gyYzx48Zvt7";
  const url = `https://live-services.trackmania.nadeo.live/api/token/map/${mapUId}`;

  const auth = headers().get("Authorization") || "";

  const res = await fetch(url, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      Authorization: auth
    }
  });

  if (!res.ok) {
    const text = await res.text(); // get the response body for more information

    throw new Error(`
      Failed to fetch data
      Status: ${res.status}
      Response: ${text}
    `);
  }

  return res.json();
};

const HomePage = async () => {
  const mapInfo = await getMapInfo();

  console.log("mapInfo: ", mapInfo);

  return (
    <div>
      <h1>HomePage</h1>

      <p>Track name: {mapInfo.name}</p>
    </div>
  );
};

Here, we leverage the added on headers using the headers function from next/headers. It is read only, but that is perfectly fine since we just want to include it with our request anyways. If you don’t include this, the request fails.

Here is what the TrackmaniaTrack type looks like:

type TrackmaniaTrack = {
  author: string;
  authorTime: number;
  bronzeTime: number;
  collectionName: string;
  downloadUrl: string;
  favorite: boolean;
  fileSize: null;
  gamepadEditor: boolean;
  goldTime: number;
  mapId: string;
  mapStyle: string;
  mapType: string;
  name: string;
  nbLaps: number;
  playable: boolean;
  public: boolean;
  silverTime: number;
  submitter: string;
  thumbnailUrl: string;
  uid: string;
  updateTimestamp: number;
  uploadTimestamp: number;
  valid: boolean;
};

And now, if you check the terminal, you should get the correct response, as well as the map name should appear on the screen!

Minor Adjustments

One thing I noticed was that sometimes the site errors out instead of using the most recent access_token. The solution is to simply refresh the page. So, as a temporary fix, I’ve created some basic back up pages:

// src/app/error.tsx

"use client";

import Link from "next/link";
import { useRouter } from "next/navigation";

const RootErrorPage = () => {
  const router = useRouter();

  return (
    <div>
      <h1 className="text-4xl">Oops!</h1>
      <p>Something went wrong there. You can try refreshing the page, or go back home.</p>

      <button
        className="bg-teal-600 text-white mr-6 py-2 px-4"
        onClick={() => router.refresh()}
        type="button"
      >
        Refresh
      </button>

      <Link className="border-teal-600 border-2 py-2 px-4" href="/">
        Go Home
      </Link>
    </div>
  );
};

export default RootErrorPage;

// src/app/not-found.tsx

import Link from "next/link";

const RootNotFound = () => {
  return (
    <div>
      <h1 className="text-4xl">Oops!</h1>
      <p>Looks like you tried accessing a page that doesn't exist.</p>
      <Link className="border-teal-600 border-2 inline-block py-2 px-4" href="/">
        Go Home
      </Link>
    </div>
  );
};

export default RootNotFound;

I also created a root level loading.tsx so something is shown while the site is loading, which provides a better UX:

// src/app/loading.tsx

const RootLoading = () => {
  return <p>Loading...</p>;
};

export default RootLoading;

Outro

I cannot stress how helpful the documentation over on Openplanet was in building this app. Big thanks to them! You can also view a list of the most common endpoints here.

And that’s it! As stated in the beginning, this was mainly to demonstrate how to use Supabase to store and retrieve tokens in a secure fashion instead of using JWT for API use. Most resources I found were revolving around authorization / user accounts, not using just an API. And I wanted to push myself and reinforce what I’ve been learning lately, and I’m very proud of myself for figuring this out.

The next steps are, well, up to you! If you want to continue building out your own Trackmania web app, you now have the proper foundation to do so. If not, you have the knowledge for storing tokens if the API you are using has a similar setup.

You could perhaps display maps from the current season on the home page, and create dynamic routes to each of them. Then, on an individual map page, display some information about that map.

The next major feature would be to include NextAuth using Ubisoft as a custom provider. Buuuttt I’m gonna leave that for another day ;)

I hope you found this article helpful. As always, you can view the full source here in case you get stuck.

If you have any feedback for me on how I could improve the code, please let me know! This was only the second time I’ve built a project using this stack, so any suggestions you may have are greatly appreciated!

Cheers, and happy coding!

Integrate GitHub OAuth With NextAuth.js in Next.js 13 With Custom Sign In / Out Pages

Andrew Shearer — Sat, 16 Sep 2023 16:09:13 +0000

Link to NextAuth docs here

This page will show you how to set up basic authentication using NextAuth while using custom sign in and out pages. We will use just GitHub for this simple demo, no email / password.

Initial Setup

Quickly download and setup the latest Next.js TypeScript starter:

npx create-next-app@latest --ts .

If you are getting warnings in your CSS file complaining about unknown CSS rules, follow these steps here

Still in globals.css, update the code with this reset from Josh Comeau

/* src/app/globals.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

*, *::before, *::after {
  box-sizing: border-box;
}

* {
  margin: 0;
    padding: 0;
}

body {
  line-height: 1.5;
  -webkit-font-smoothing: antialiased;
}

img, picture, video, canvas, svg {
  display: block;
  max-width: 100%;
}

input, button, textarea, select {
  font: inherit;
}

p, h1, h2, h3, h4, h5, h6 {
  overflow-wrap: break-word;
}

#root, #__next {
  isolation: isolate;
}

Update tsconfig.json to this:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "Node",
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Update src/app/page.tsx to this:

// src/app/page.tsx

const HomePage = () => {
  return (
    <div>
      <h1>HomePage</h1>
    </div>
  );
};

export default HomePage;

Update src/app/layout.tsx to this:

// src/app/layout.tsx

import { Inter } from "next/font/google";

import type { Metadata } from "next";
import type { ReactNode } from "react";

import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  description: "Generated by create next app",
  title: "NextAuth Demo"
};

type RootLayoutProps = {
  children: ReactNode;
};

const RootLayout = ({ children }: RootLayoutProps) => {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
};

export default RootLayout;

Install the NextAuth package:

npm i next-auth

Auth Route Handler

For this demo, we won’t be using a database

Additionally, we’ll be using the default settings for JWT

In your text editor, right click on the app directory, and paste this in (or create this manually if need be)

api/auth/[...nextauth]/route.ts

This will create the route.ts file at the correct location

NOTE: Make sure the api folder is the app directory!!

Add this dummy code for now:

// src/api/auth/[...nextauth]/route.ts

import NextAuth from "next-auth"

const handler = NextAuth()

export { handler as GET, handler as POST }

In Next.js, you can define an API route that will catch all requests that begin with a certain path. Conveniently, this is called Catch all API routes.

When you define a /pages/api/auth/[...nextauth] JS/TS file, you instruct NextAuth.js that every API request beginning with /api/auth/* should be handled by the code written in the [...nextauth] file.

NextAuth `options`

Link to Options in the docs here

The NextAuth function needs an options argument, which is an object of type AuthOptions

You can do this in the same file, but we’ll separate it out so we can export it

This will benefit us later as we’ll need it in other files as well

The options object needs at least providers, which is an array of Provider objects

In the [...nextauth] directory, create another file called options.ts

Add this code to it:

// src/app/api/auth/[...nextauth]/options.ts

import type { AuthOptions } from "next-auth";

export const options: AuthOptions = {
  providers: []
};

`NEXTAUTH_SECRET`

Let’s pause here, and in a terminal window run this command:

openssl rand -base64 32

This value will be used to encrypt the NextAuth.js JWT, and to hash email verification tokens. This is the default value for the secret option in NextAuth and Middleware.

At the root level, create an .env.local file, and add the following:

NEXTAUTH_SECRET=VALUE_CREATED_FROM_OPENSSL_COMMAND

Setting up GitHub OAuth

Link to OAuth in the docs here

For this demo, we’ll be using a built-in OAuth Provider - GitHub

Link to GitHub page in the docs here

Visit this page

Click OAuth Apps in the left-hand nav menu

Click New OAuth App

Name: nextauth-demo

Homepage URL: http://localhost:3000/

NOTE: Make sure to change this URL once the app is deployed!

Application description (optional)

Authorization callback URL: http://localhost:3000/api/auth/callback/github

This is basically saying where it’s going to send you after you authenticate with GitHub

Leave Enable Device Flow unchecked

Click Register application

On the next page, we should have a Client ID

Copy and paste this into a file for now, such as the README

We also need a Client Secret, which we can generate by clicking Generate a new client secret

Confirm by entering your GitHub password again

Copy and paste the value into the env file (as well as the client):

// .env.local

NEXTAUTH_SECRET=""
GITHUB_SECRET=""
GITHUB_ID=""

Configuring Providers in options

Now that we have the Client ID and Secret, we can finish configuring the NextAuth options object

We’ll need the GitHubProvider from next-auth, so let’s import it:

// src/app/api/auth/[...nextauth]/options.ts

import GitHubProvider from 'next-auth/providers/github'

Now let’s update the providers array:

// src/app/api/auth/[...nextauth]/options.ts

import GitHubProvider from "next-auth/providers/github";
import type { AuthOptions } from "next-auth";

export const options: AuthOptions = {
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!
    })
  ]
};

TypeScript will complain that when using the environment variable, type string | null is not assignable to type string. So, we use the ! to tell TypeScript it is definitely there. You could also use as string as well.

And that’s it for the GitHub setup!

Creating Pages

Now let’s set up the pages we’ll need

In the app directory, create a sign-in, sign-out, and profile folder

And then in each of those folders, create a page.tsx file. The code can look like this for now:

// src/app/sign-in/page.tsx

const SignInPage = () => {
  return (
    <div>
      <h1>SignInPage</h1>
    </div>
  );
};

export default SignInPage;

// src/app/sign-out/page.tsx

const SignOutPage = () => {
  return (
    <div>
      <h1>SignOutPage</h1>
    </div>
  );
};

export default SignOutPage;

// src/app/profile/page.tsx

const ProfilePage = () => {
  return (
    <div>
      <h1>ProfilePage</h1>
    </div>
  );
};

export default ProfilePage;

The sign-in and sign-out pages should be self explanatory. The profile page will be used to display basic info about the user from their GitHub profile page. This page should only be accessible once logged in.

While we’re at it, let’s create a simple Navbar component:

// src/components/Navbar.tsx

import Link from "next/link";

const Navbar = () => {
  return (
    <nav className="bg-indigo-600 p-4">
      <ul className="flex gap-x-4">
        <li>
          <Link href="/" className="text-white hover:underline">
            Home
          </Link>
        </li>

        <li>
          <Link href="/sign-in" className="text-white hover:underline">
            Sign In
          </Link>
        </li>

        <li>
          <Link href="/profile" className="text-white hover:underline">
            Profile
          </Link>
        </li>

        <li>
          <Link href="/sign-out" className="text-white hover:underline">
            Sign Out
          </Link>
        </li>
      </ul>
    </nav>
  );
};

All the links / pages will be accessible for now, but we’ll change that soon.

Back in the route.ts file, let’s import the options and pass them into NextAuth function so we don’t see the red underline anymore:

import NextAuth from "next-auth";
import { options } from "./options";

const handler = NextAuth(options);

export { handler as GET, handler as POST };

Send a `GET` request to `/api/auth/providers`

Let’s finally start up the app! Run npm run dev

Then, you can either:

Go to http://localhost:3000/api/auth/providers in the browser
Send a GET request with a service like Postman (to that same URL, just make sure the dev server is running)

And you should get the following JSON response:

{
    "github": {
        "id": "github",
        "name": "GitHub",
        "type": "oauth",
        "signinUrl": "<http://localhost:3000/api/auth/signin/github>",
        "callbackUrl": "<http://localhost:3000/api/auth/callback/github>"
    }
}

Apply NextAuth with Middleware

Link to the docs regarding matcher here

Using middleware is one of the easiest ways to apply NextAuth to the entire site

In the src directory, create a file called middleware.ts

This file runs on the edge, and we only need to add one line to this file:

// src/middleware.ts

export { default } from "next-auth/middleware"

Now, with just this one line, NextAuth is applied to ALL pages

You can of course set this for a few select pages using a matcher like so:

// src/middleware.ts

export { default } from "next-auth/middleware";

// applies next-auth only to matching routes
export const config = { matcher: ["/profile"] };

Custom Sign In / Out Pages

Link to pages option in the docs here

Let’s go back to the options.ts file and update our options variable with the pages property:

// src/app/api/auth/[...nextauth]/options.ts

export const options: AuthOptions = {
  providers: [
    GitHubProvider({
      name: "GitHub",
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!
    })
  ],
  pages: {
    signIn: "/sign-out",
    signOut: "/sign-out"
  }
};

Adding Sign In / Out Functionality

Let’s start with the sign-in page.

But before we do, let’s be aware of something.

Since we are no longer using the default settings provided by NextAuth, we will not get the default “Login with GitHub” button which is styled.

So, we will need to create this component ourselves. Furthermore, this component will need to be a client component since we’ll be using the onClick event handler.

We can keep the sign-in page as a server component, and then add in the button as a child component.

This is my preferred approach: the page (parent) is a server component, and then any child components can be client components if need be.

In the components folder, create a SignInButton.tsx and SignOutButton.tsx:

// src/components/SignInButton.tsx

"use client";

import { signIn } from "next-auth/react";

const SignInButton = () => {
  return (
    <button
      className="bg-slate-600 px-4 py-2 text-white"
      onClick={() => signIn("github", { callbackUrl: "/profile" })}
      type="button"
    >
      Sign In With GitHub
    </button>
  );
};

export default SignInButton;

For the signIn function, we need to pass in at least an id. Since we are using GitHub as our OAuth provider, we’ll use github. If you ran the GET request earlier, you would’ve seen what ids are available to you.

We’ll also specify the callbackUrl to tell NextAuth where to redirect the user once they are logged in. By default, you’ll be redirected to the same page that you logged in from. This is typically not the behaviour you want, so that is why we specify where to go.

The SignOutButton component:

// src/components/SignOutButton.tsx

"use client";

import { signOut } from "next-auth/react";

const SignOutButton = () => {
  return (
    <button
      className="bg-slate-600 px-4 py-2 text-white"
      onClick={() => signOut({ callbackUrl: "/" })}
      type="button"
    >
      Sign Out of GitHub
    </button>
  );
};

export default SignOutButton;

Since this is just a simple login using OAuth, we do not need an entire form with other fields. We just need a button to click to sign us in and out.

Next, in the SignInPage, update the code to this:

// src/app/sign-in/page.tsx

import { getServerSession } from "next-auth";
import { redirect } from "next/navigation";
import { options } from "../api/auth/[...nextauth]/options";

import SignInButton from "@/components/SignInButton";

const SignInPage = async () => {
  const session = await getServerSession(options);

  if (session) {
    redirect("/profile");
  } else {
    return (
      <div>
        <h1>SignInPage</h1>

        <SignInButton />
      </div>
    );
  }
};

export default SignInPage;

Inside the component, we await the getServerSession, and pass in our options

We assign the result of this to the session variable

Then we conditionally render the JSX based on whether or not a session is active

You might be wondering why we specify a callbackUrl in the signIn function, as well as use the redirect function here in the page component.

The reason for this is that without this conditional rendering, we could still access the sign-in page while logged in by changing the URL manually. And as you’ll see shortly, the same applies to the sign-out page. We could still access the sign-out page, even though we are already logged out. So this is a nice extra layer of protecting our routes.

The SignOut page:

// src/app/sign-out/page.tsx

import { getServerSession } from "next-auth";
import { redirect } from "next/navigation";
import { options } from "../api/auth/[...nextauth]/options";

import SignOutButton from "@/components/SignOutButton";

const SignOutPage = async () => {
  const session = await getServerSession(options);

  if (!session) {
    redirect("/");
  } else {
    return (
      <div>
        <h1>SignOutPage</h1>

        <SignOutButton />
      </div>
    );
  }
};

export default SignOutPage;

From here, we can also update our Navbar component based on whether or the user is logged in (a session is active):

// src/components/Navbar.tsx

import Link from "next/link";
import { getServerSession } from "next-auth/next";
import { options } from "@/app/api/auth/[...nextauth]/options";

const Navbar = async () => {
  const session = await getServerSession(options);

  return (
    <nav className="bg-indigo-600 p-4">
      <ul className="flex gap-x-4">
        <li>
          <Link href="/" className="text-white hover:underline">
            Home
          </Link>
        </li>

        {!session ? (
          <li>
            <Link href="/sign-in" className="text-white hover:underline">
              Sign In
            </Link>
          </li>
        ) : (
          <>
            <li>
              <Link href="/profile" className="text-white hover:underline">
                Profile
              </Link>
            </li>

            <li>
              <Link href="/sign-out" className="text-white hover:underline">
                Sign Out
              </Link>
            </li>
          </>
        )}
      </ul>
    </nav>
  );
};

export default Navbar;

Next.js Images from an OAuth Provider

Next, let’s display some basic information about our GitHub profile on the profile page:

// src/app/profile/page.tsx

import Image from "next/image";
import { getServerSession } from "next-auth";
import { options } from "../api/auth/[...nextauth]/options";

const ProfilePage = async () => {
  const session = await getServerSession(options);

  return (
    <div>
      <h1>ProfilePage</h1>

      <div>
        {session?.user?.name ? <h2>Hello {session.user.name}!</h2> : null}

        {session?.user?.image ? (
          <Image
            src={session.user.image}
            width={200}
            height={200}
            alt={`Profile Pic for ${session.user.name}`}
            priority={true}
          />
        ) : null}
      </div>
    </div>
  );
};

export default ProfilePage;

When we display images that are being fetched from a 3rd party, you need to make sure to update the next.config.js file with that service’s domain:

// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ["avatars.githubusercontent.com"]
  }
};

module.exports = nextConfig;

And that’s it! Thank you so much for reading this article, and I hope you found this simple demo helpful. This is my first time using NextAuth, so if you have any suggestions for improvement, please let me know. The repo can be found here, which you can use as a reference in case you get stuck.

Cheers, and happy coding!

Use Next.js 13 With TypeScript To Create a Headless Shopify App

Andrew Shearer — Tue, 29 Aug 2023 18:32:06 +0000

This doc will show you how to set up a simple ecommerce app using Next.js 13 and Shopify as a headless ecommerce platform. We will use the following:

Next.js w/ TypeScript
GraphQL
Shopify

Our goal for this simple demo will be to fetch products from Shopify and display them on the homepage. Then we will add dynamic routing to go to an individual product page, and view the details of that product there.

Initial Setup

Quickly download the latest Next.js TypeScript starter:

npx create-next-app@latest --ts .

Answer the questions like this:

✔ Would you like to use ESLint? … **No** / Yes
✔ Would you like to use Tailwind CSS? … No / **Yes**
✔ Would you like to use `src/` directory? … No / **Yes**
✔ Would you like to use App Router? (recommended) … No / **Yes**
✔ Would you like to customize the default import alias? … **No** / Yes

We need to correct some things before getting started. First, open tsconfig.json and update it to this:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "Node",
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Then open src/app/globals.css. You might be getting an unknownAtRules warning. If you are, follow these steps here to fix the issue.

Still in globals.css, update the code with this reset from Josh Comeau:

/* src/app/globals.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

*, *::before, *::after {
  box-sizing: border-box;
}

* {
  margin: 0;
    padding: 0;
}

body {
  line-height: 1.5;
  -webkit-font-smoothing: antialiased;
}

img, picture, video, canvas, svg {
  display: block;
  max-width: 100%;
}

input, button, textarea, select {
  font: inherit;
}

p, h1, h2, h3, h4, h5, h6 {
  overflow-wrap: break-word;
}

#root, #__next {
  isolation: isolate;
}

Update src/app/page.tsx to this:

// src/app/page.tsx

const HomePage = () => {
  return (
    <div>
      <h1>Shopify + Next.js 13!</h1>
    </div>
  );
};

export default HomePage;

I like to use function expressions, so I will be using those throughout. If you prefer the function keyword, absolutely feel free to do so. All that matters is you pick one and stick with it.

Next, let’s update the root layout.tsx to this:

// src/app/layout.tsx

import { Inter } from "next/font/google";

import type { Metadata } from "next";
import type { ReactNode } from "react";

import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  description: "Generated by create next app",
  title: "Shopify + Next.js 13!"
};

type RootLayoutProps = {
  children: ReactNode;
};

const RootLayout = ({ children }: RootLayoutProps) => {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
};

export default RootLayout;

Next, go to GitHub and create a repo (if you want). If you do, you only need to run the following 3 commands to push it up to the remote repo:

git branch -M main
git remote add origin <https://github.com/YOUR_USERNAME_HERE/GIT_LINK_HERE>
git push -u origin main

Store Setup

Go to Shopify Partners and create an account if you do not have one already. Once in your dashboard, click Stores. If you do not have any Stores, click Add store, and then select Create development store, and then go through the process of creating a dev store.

Just make sure to select Create a store to test and build

Shopify Products Setup

If you’re in need of some products, you can either get some dummy products from this repo, or you can download my small list of products which we’ll use for this demo.

products_export_1.csv

Shopify Storefront API Setup

Enable custom app development

From your Shopify admin, click Settings > Apps and sales channels.
Click Develop apps.
Click Allow custom app development.
Read the warning and information provided, and then click Allow custom app development.

Create and install a custom app

From your Shopify admin, click Settings > Apps and sales channels.
Click Develop apps
Click Create an app
In the modal window, enter the App name and select an App developer
Click Create app.

Select API scopes

Click Configure Admin API scopes.
In the Admin API access scopes section, select the API scopes that you want to assign to the app.
- For this demo, select at least write_products & read_productsunder Products.
Click Save
- Make sure to copy the Admin API access token as you can only see it once!
Click Install App.

Configure Environment Variables

Back in the code, create a .env.local file at the root level and add the following:

ADMIN_API_ACCESS_TOKEN=YOUR_TOKEN_HERE

Replace YOUR_TOKEN_HERE with your Admin API access token

You do not need the API key or the API secret key

Shopify GraphiQL App Setup

Go here to install the GraphQL API app
On this page:
- Enter your Shop URL
  - To get your shop url, when in the admin, click on home
  - The URL should be something like:
  https://admin.shopify.com/store/STORE_NAME_HERE
  - Copy and paste whatever is your STORE_NAME_HERE
- You can leave the Admin API and Storefront API checkboxes alone, or check more if you want
- Click Install
- Wait for the redirect to finish, and click Install app
Once finished, you should be in the GraphiQL playground with this query to start with:

{
  shop {
    name
  }
}

Run it and you should see something like this:

{
  "data": {
    "shop": {
      "name": "Next.js Headless"
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 1,
      "actualQueryCost": 1,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 999,
        "restoreRate": 50
      }
    }
  }
}

We want to query for products, so let's create a ProductsQuery.

Let's start off simple with getting just the product titles:

query ProductsQuery {
  products(first: 6) {
    nodes {
      title
    }
  }
}

We must provide an argument to products(). Typically it is eitherfirst or last

Now we should see a result:

{
  "data": {
    "products": {
      "nodes": [
        {
          "title": "Head Bust Digital Print"
        },
        {
          "title": "Dripping Hand Digital Print"
        },
        {
          "title": "Woman's Face Digital Print"
        },
        {
          "title": "Purpe & Red Waves Digital Print"
        },
        {
          "title": "Purple Rock Sculpture Digital Print"
        },
        {
          "title": "Tree on a Hill Digital Print"
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 8,
      "actualQueryCost": 3,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 843,
        "restoreRate": 50
      }
    }
  }
}

Let's just display this data on the homepage for now, and we'll come back to it and add more

Displaying Simple Shopify Data

Let’s start off simple by fetching just the product titles for now to ensure everything is working correctly

Inside .env.local file and add the following and update the placeholders accordingly:

GRAPHQL_API_URL=https://STORE_NAME.myshopify.com/admin/api/API_VERSION/graphql.json

You get the API_VERSION while in the GraphiQL playground. There is a drop down called API version. You just need the year-month. Currently at the time of writing, the current version is 2023-07
And your STORE_NAME is this part of your store url: https://my-store-name.myshopify.com

To have Next.js load these variables, simply restart the dev server. You should see info - Loaded env from ... in the terminal.

Open src/app/page.tsx and add this above the component:

const getProducts = async () => {
    // ...
}

In the src folder, create a utils folder

Inside the utils folder, create a file called gql.ts and add this to it:

export const gql = String.raw;

This gives us a nice wrapper around multi line template strings, making it much easier to construct / format our GraphQL queries.

Now let's fetch some data! First, let’s add this type above the function:

type GraphQLResponse = {
  data: {
    products: {
      nodes: {
        title: string;
      }[];
    };
  };
  extensions: {
    cost: {
      requestedQueryCost: number;
      actualQueryCost: number;
      throttleStatus: {
        maximumAvailable: number;
        currentlyAvailable: number;
        restoreRate: number;
      };
    };
  };
};

const getProducts = async () => {
    // ...
}

Now let’s create the fetch call:

// src/app/page.tsx

type GraphQLResponse = {
  // ...
}

const getProducts = async (): Promise<GraphQLResponse> => {
  const res = await fetch(process.env.GRAPHQL_API_URL!, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Shopify-Access-Token": process.env.ADMIN_API_ACCESS_TOKEN!
    },
    body: JSON.stringify({
      query: gql`
        query ProductsQuery {
          products(first: 6) {
            nodes {
              title
            }
          }
        }
      `
    })
  });

  if (!res.ok) {
    const text = await res.text(); // get the response body for more information

    throw new Error(`
      Failed to fetch data
      Status: ${res.status}
      Response: ${text}
    `);
  }

  return res.json();
};

NOTE 1: For the env variables to work, you MUST put them inside template strings, or use the ! operator to note they are not null. Otherwise, you get a type error that string | undefined does not work for type string. The “proper” approach would be to actually handle the undefined case, but this is just a quick demo, so I think this is ok for now.
NOTE 2: For some reason, Shopify does not like when you have the API_VERSION as it's own env variable. Perhaps due to being a number, or enum? Just put the whole URL as a variable and it will be ok

Here is a link to the Shopify GraphQL docs if you want to check it out. Previously, the access token header was called X-Shopify-Storefront-Access-Token. Do not use this! Ensure you are using the updated name as seen in the code above. I may or may not have gotten stuck on this for an unnecessary amount of time >_>

Our query is pretty straightforward. We use the GRAPHQL_API_URL environment variable as the endpoint, make sure to use POST for the method, set the headers as seen above, and then wrap the query in a JSON.stringify. You could certainly abstract this out into its own function later on, if you prefer. Again, since this is a simple demo, it’s fine here for now.

Now let's update the page component to show the product titles in a list:

const HomePage = async () => {
  const json = await getProducts();

  return (
    <main>
      <h1>Shopify + Next.js 13!</h1>

      <ul>
        {json.data.products.nodes.map((product) => (
          <li key={product.title}>{product.title}</li>
        ))}
      </ul>
    </main>
  );
};

Here, we are leveraging the power of React Server Components, which is the default in Next.js 13. We don’t have to use getStaticProps like we used to, or use the useEffect hook. We can use plain old async/await with the standard fetch api. Which, to me at least, feels a lot better is a much simpler approach than in the past.

And if you go to the browser, you should see the list of product names on the page.

Getting and Display More Data

Now let's update our product query on the home page to show the description, featuredImage, handle, price, tags, and title

But before we do, we need to add Shopify’s CDN to the list of domains in next.config.js

Otherwise, we’ll get an error and won’t be able to display the images. Shut down the local dev server, and update the code to this:

// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ["cdn.shopify.com"]
  },
  reactStrictMode: true
};

module.exports = nextConfig;

After changing it, start the server back up again.

Next, let's update our GraphQL query to this:

query ProductsQuery {
  products(first: 6) {
    nodes {
      description
      featuredImage {
        altText
        height
        id
        url
        width
      }
      handle
            id
      priceRangeV2 {
        minVariantPrice {
          amount
          currencyCode
        }
      }
      tags
      title
    }
  }
}

The altText for the images will be null at first if you run this in the GraphiQL playground . To fix this, so go to

Products, then select a product
Click on the image
Click add alt text
Add something simple like Preview for PRODUCT_NAME
Click Save alt text
- Repeat this for all product images

Go back to Shopify GraphiQL App, and rerun the query. altText should have a value now

Now is also a good time to setup some types for Shopify

In the src directory, create another directory called types, and inside there, create a file called index.ts

Add these types:

// src/types/index.ts

export type ShopifyExtension = {
  cost: {
    actualQueryCost: number;
    requestedQueryCost: number;
    throttleStatus: {
      currentlyAvailable: number;
      maximumAvailable: number;
      restoreRate: number;
    };
  };
};

export type ShopifyProduct = {
  description: string;
  featuredImage: {
    altText: string;
    height: number;
    id: string;
    url: string;
    width: number;
  };
  handle: string;
  id: string;
  priceRangeV2: {
    minVariantPrice: {
      amount: string;
      currencyCode: string;
    };
  };
  tags: string[];
  title: string;
};

There are certainly way more fields than these in the Schema, but this is a good starting point based on our query / small demo.

Back in src/app/page.tsx, we can update our GraphQLResponse type to this:

import type { ShopifyExtension, ShopifyProduct } from "@/types";

type GraphQLResponse = {
  data: {
    products: {
      nodes: ShopifyProduct[];
    };
  };
  extensions: ShopifyExtension;
};

Looks a lot cleaner!

Next, we need to update our query in the fetch request

const getProducts = async (): Promise<GraphQLResponse> => {
  const res = await fetch(process.env.GRAPHQL_API_URL!, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Shopify-Access-Token": process.env.ADMIN_API_ACCESS_TOKEN!
    },
    body: JSON.stringify({
      query: gql`
        query ProductsQuery {
          products(first: 6) {
            nodes {
              description
              featuredImage {
                altText
                height
                id
                url
                width
              }
              handle
              priceRangeV2 {
                minVariantPrice {
                  amount
                  currencyCode
                }
              }
              tags
              title
            }
          }
        }
      `
    })
  });

  // ...
};

Now we can update the JSX to this:

<main className="container mx-auto">
  <div className="px-5">
    <h2 className="font-bold text-2xl mb-3">Our Products:</h2>
    <ul className="grid grid-cols-12 gap-4 pb-12">
      {json.data.products.nodes.map((product) => {
        const prodId = product.id.split("/").pop();

        return (
          <li
            key={product.id}
            className="border border-slate-200 rounded-md overflow-hidden col-span-full md:col-span-6 lg:col-span-4"
          >
            <div>
              <Image
                src={product.featuredImage.url}
                alt={product.featuredImage.altText}
                width={product.featuredImage.width}
                height={product.featuredImage.height}
                className="h-96 w-full object-cover"
                placeholder="blur"
                blurDataURL={product.featuredImage.url}
              />
            </div>

            <div className="p-5">
              {product.tags.map((tag) => (
                <span
                  key={tag}
                  className="bg-yellow-400 font-bold py-1 px-3 rounded-full text-xs"
                >
                  {tag}
                </span>
              ))}

              <h3 className="font-medium mt-3 text-3xl">{product.title}</h3>

              <h4>
                {formatPrice(product.priceRangeV2.minVariantPrice.amount)}{" "}
                {product.priceRangeV2.minVariantPrice.currencyCode}
              </h4>

              <p className="mt-2 mb-4">{product.description}</p>

              <Link
                href={`/product/${prodId}`}
                className="border border-blue-600 inline-block p-2 rounded-md text-blue-600 hover:bg-blue-600 hover:text-white ease-in-out duration-150"
              >
                View Product
              </Link>
            </div>
          </li>
        );
      })}
    </ul>
  </div>
</main>

WIth this update, we’ll need to import a few things from next:

import Image from "next/image";
import Link from "next/link";

The price doesn't display correctly, so we can create a formatPrice util function to do that for us:

// src/utils/formatPrice.ts

export const formatPrice = (price: string) =>
  Intl.NumberFormat("en-CA", {
    style: "currency",
    currency: "CAD",
    minimumFractionDigits: 2
  }).format(parseInt(price, 10));

Creating Product Pages

In our home page JSX, we have this link at the bottom:

<Link href={`/product/${prodId}`} className="...">
  View Product
</Link>

Notice we are linking to a dynamic page using the product’s id. We had to format it a bit because otherwise the full id is this:

"gid://shopify/Product/PRODUCT_ID_HERE"

Which is not very url friendly. Previously we could use the handle, but now id with a type of ID is the only accepted argument

To create this route, in the app directory we can create a directory called product, then another directory inside there called [id]. In the [id] directory, create a page.tsx file. For now, let’s use this dummy JSX code:

// src/app/product/[id]/page.tsx

const SingleProductPage = () => {
  return <div>SingleProductPage</div>;
};

export default SingleProductPage;

Now if we go back to the browser and click on any of the “View Product” buttons, it should take us to the page for that product

Now let’s flesh out the page some more to display the info for a given product. First, let's create our type:

// src/app/product/[id]/page.tsx

type GraphQLResponse = {
  data: {
    product: ShopifyProduct;
  };
  extensions: ShopifyExtension;
};

Notice the structure for data is slightly different now that we are querying a single product instead of a group of products

Next, our getProduct function:

// src/app/product/[id]/page.tsx

const getProduct = async (id: string): Promise<GraphQLResponse> => {
  const res = await fetch(process.env.GRAPHQL_API_URL!, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Shopify-Access-Token": process.env.ADMIN_API_ACCESS_TOKEN!
    },
    body: JSON.stringify({
      query: gql`
        query SingleProductQuery($id: ID!) {
          product(id: $id) {
            id
            title

          }
        }
      `,
      variables: {
        id: `gid://shopify/Product/${id}`
      }
    })
  });

  if (!res.ok) {
    const text = await res.text(); // get the response body for more information

    throw new Error(`
      Failed to fetch data
      Status: ${res.status}
      Response: ${text}
    `);
  }

  return res.json();
};

In GraphQL, if we want to dynamically query something, we need to use variables like $id here. Previously, we could use the type String!, but that is no longer possible. We must now use the type ID!. Not a big deal, just pointing out the change. And we’ll just fetch the product title and id for now to get started.

Furthermore, along with the query property, we must also pass along the variables property. Here, we must use the full "gid://shopify/Product/ID_HERE” shown earlier. We cannot simply use the number portion, we must use the full string. We then interpolate the id parameter into this id string.

With Next, we can access the id from the URL by using the params prop in our component. And as a quick note, whatever you call the dynamic segment, in this case id, will be the property availabe in the params object.

So in the component we can do this:

// src/app/product/[id]/page.tsx

type SingleProdutPageProps = {
  params: {
    id: string;
  };
};

const SingleProductPage = async ({ params }: SingleProdutPageProps) => {
  const json = await getProduct(params.id);
  const { product } = json.data;

  return (
    <div>
      <h1>View page for: {product.title}</h1>
    </div>
  );
};

And we should see the product title on the page. Now let’s update the query to get and display more data on the page!

But before we do that, the page is kind of awkward. It’s just the h1 with no navigation. Let’s set up a simple global Navbar and Footer. We’ll also move the main h1 from the home page into the nav so the simple demo feels a bit more cohesive

Adding Global Nav & Footer

To get started, in the src directory, create another directory called components

In this components directory, create 2 files: Navbar.tsx and Footer.tsx

Here is the code for the Navbar:

// src/components/Navbar.tsx

import Link from "next/link";

const Navbar = () => {
  return (
    <nav className="mt-10">
      <h1 className="font-bold mb-3 text-3xl text-center">Shopify + Next.js 13!</h1>

      <ul className="text-center">
        <li>
          <Link href="/" className="text-blue-600 hover:underline">
            Home
          </Link>
        </li>
      </ul>
    </nav>
  );
};

export default Navbar;

Here is the code for the Footer:

// src/components/Footer.tsx

const Footer = () => {
  return (
    <footer className="bg-blue-600 mt-auto py-3 text-center text-white">
      Shopify + Next.js 13!
    </footer>
  );
};

export default Footer;

Next, in the root layout.tsx, let’s update the JSX to this:

// src/app/layout.tsx

const RootLayout = ({ children }: RootLayoutProps) => {
  return (
    <html lang="en">
      <body className={`${inter.className} flex flex-col min-h-screen`}>
        <Navbar />
        {children}
        <Footer />
      </body>
    </html>
  );
};

With this in place, the footer will always be on the bottom of the page.

Single Product Page

First, let’s update our GraphQL query with the other pieces of data we want to display:

body: JSON.stringify({
  query: gql`
    query SingleProductQuery($id: ID!) {
      product(id: $id) {
        description
        featuredImage {
          altText
          height
          id
          url
          width
        }
        id
        priceRangeV2 {
          minVariantPrice {
            amount
            currencyCode
          }
        }
        tags
        title
      }
    }
  `,
  variables: {
    id: `gid://shopify/Product/${id}`
  }
})

Next let’s update the JSX for the single product page to this:

<div className="container mx-auto md:pb-10">
  <div className="flex flex-col md:flex-row md:items-center">
    <div className="md:basis-1/2">
      <Image
        src={product.featuredImage.url}
        alt={product.featuredImage.altText}
        width={product.featuredImage.width}
        height={product.featuredImage.height}
        placeholder="blur"
        blurDataURL={product.featuredImage.url}
      />
    </div>

    <div className="p-5 md:basis-1/2">
      {product.tags.map((tag) => (
        <span key={tag} className="bg-yellow-400 font-bold py-1 px-3 rounded-full text-xs">
          {tag}
        </span>
      ))}

      <h3 className="font-medium mt-3 text-3xl">{product.title}</h3>

      <h4>
        {formatPrice(product.priceRangeV2.minVariantPrice.amount)}{" "}
        {product.priceRangeV2.minVariantPrice.currencyCode}
      </h4>

      <p className="mt-2 mb-4">{product.description}</p>

      <button
        className="border border-blue-600 inline-block p-2 rounded-md text-blue-600 hover:bg-blue-600 hover:text-white ease-in-out duration-150"
        type="button"
      >
        Add to Cart
      </button>
      <span className="block mt-1 text-xs">* Note: this won't actually do anything</span>
    </div>
  </div>
</div>

And that’s it! You’re done!

Host on Vercel

Go to Vercel and create an account if you don't already have one. Once signed in, go to your dashboard.

Click + New Project, and select the project from GitHub (authorize if needed). Make sure to enter the environment variables! Click Deploy.

Next Steps

This was intended to be a starting point for using Next.js 13 and Shopify as a headless backend. Some things to implement going forward would be:

Add to cart functionality
Display products in a cart
Going through checkout process
User sign in / sign out

I hope you enjoyed this article! You can view my repo here to see the code for reference if you ever get stuck. Cheers!

I Used ChatGPT to Answer Questions on Stack Overflow

Andrew Shearer — Sun, 04 Dec 2022 23:40:39 +0000

Hi dev.to! It’s been a while since I’ve written a blog post, and I’m really excited to share this one with you all. Recently, OpenAI opened (released?) their ChatGPT AI for a Free Research Preview, which has been all the buzz lately. I created an account, and just started asking simple questions, watched some videos of other people using it, and used it to help me write up some simple boilerplate code for a fun side project I had in mind. Then I thought, what would happen if I started giving it questions from Stack Overflow? Some questions I had mind were:

How accurate would the answers be?
How often would the answers I provided be chosen as the accepted answer?
How often would the answers I provide not work at all?

In this post, I will answer those questions, as well as provide my experience in doing this, pros and cons, things I noticed along the way, and what I plan on doing on going forward

My Experience

Overall, I would say my experience in doing this has been quite positive. My intent was to help people and answer their question, or rather have ChatGPT answer their question. This has also been a bit of a double-edged sword though, because I would often find myself answering questions I would have little to no idea where to start or how to start troubleshooting the problem if I were doing it on my own. At first, I tried answering as many questions as possible, simply copy + paste the answer and submit. The idea here was to see the success / fail rate of just blindly copying the answer. Not surprisingly, the success rate was rather low. Once I started double checking the answers ChatGPT provided me, however, the rate at which my answers were accepted increased. Only a bit, but still, it was noticeable.

This took place over the last 3 days (Dec 01 - Dec 03). Let’s look at the data:

I answered 46 questions. Of those 46 questions:

My answer was the selected answer for 10 of them (21.7%)
Another answer was selected for 7 of them (15.2%)
My answer was incorrect for 4 of them (8.6%)
For the remaining 25 questions, no answer has been selected yet (54.3%).

I gained 392 rep, which was an increase of 247%. I started with 159 rep, and I am currently at 551 at time of writing. Also at the time of writing, this has ranked me 69th for rep gained this month. Nice.

My original plan was to do this for the entire month of December. I then re-assessed and decided to do it for 1 week. But after only 3 days, I decided I simply cannot continue running this experiment. Perhaps I could dial it back, but I was spending a large amount of time doing this. It was fun at first, and still is highly interesting to me, this concept of using AI to answer coding questions from humans, but I noticed I was developing some unhealthy habits, so I have decided to stop completely. Perhaps, if allowed and after some community discussion, I will return and answer only a handful of questions a day, somewhere in the range of 1-3 or so. Or give myself a time limit of an hour or so, and stop after that.

I can confidently say though, I was NOT the only one doing this. If you have used ChatGPT to answer coding questions, you may have noticed it uses the same terminology very often in its responses. I noticed that it after it was done explaining why the code wasn’t working, or explaining steps I should take for what I wanted to accomplish, right before the code snippet, it would say something like:

“Here is an example of how you would do X:”

Also, if the code it would send you would be too long, it would just abruptly stop and the code would be unfinished. This happened somewhat often with React code where the component was quite large, so the JSX would be incomplete. So if you’re browsing Stack Overflow, looking at people's answers, and they show either of these 2 traits, that’s a ChatGPT answer right there.

Furthermore, I also noticed quite a lot of new accounts answering questions using ChatGPT. And I know they were using ChatGPT because of the way ChatGPT words its answers. It looks like a lot of users were looking to also gain a bunch of rep. The issue here is that they would very often not format the answer properly. Code blocks were fine, but any variables, npm libraries, etc., would not be surrounded in backticks for better readability in the plain text parts of the answer. I think what is happening here is that people who (may) have little to no experience with coding are answering questions to solely gain rep.

Pros and Cons

Next, I want to go over some of the pros and cons that I experienced during these last few days.

One downside that comes to mind having done this, and a point I think people will argue, to which I agree, is that it doesn’t benefit me to just copy and paste answers to questions that ChatGPT gives me without understanding what the code is doing. Now, to be fair, ChatGPT does a pretty damn good job (at least in my opinion) of explaining what the code is doing. It typically provides at least a paragraph or 2 of explanations.

The upside to this though, is that it has opened to me many different areas of web development / programming I wouldn’t have thought to explore. For example, one question was working with the webcam with React. I found that so interesting, so I went and built a simple demo of simply turning my webcam on and off using React + TypeScript. I also ended up answering a question where someone was having an issue with their Discord bot. Now I want to go and build a simple Discord bot. There were a few questions regarding MongoDB, so now I am motivated to go back to learning more about the MERN stack, and try to put together some simple projects there.

So while I may not have fully understood the answer I was providing sometimes, it did motivate me to go out on my own and try some things out I likely wouldn’t have gotten to, and / or reigniting my interest in areas I was previously exploring.

Another downside I found was that I personally found it quite difficult to answer questions where the person provided, for example, the code for a React component or two, and explained the issue(s) they were having. I found this difficult because to me it’s hard to look at only that code in isolation, and not in the larger context of the entire project. Where is that component being used? What are the types of the data / props, etc. I am so used to using TypeScript now that reviewing React code written in JS was a bit difficult. This really made me appreciate those who have not only answered my questions in the past, but also continue answering these types of questions on a regular basis. It is definitely a skill I want to improve upon.

Going Forward

This is where things get tricky, because I am not sure if what I have been doing is against Stack Overflow’s ToS. I am definitely going to pause on this for a while now, and switch my focus on the areas I’m interested in that I listed above. I’ll just be upfront and share the link to my Stack Overflow account here. Feel free to take a look at the answers I provided, and let me know your thoughts. I am really interested in discussing this with the web dev community, so please leave your comments down below! Also, if anyone from Stack Overflow, or highly ranked members have anything to say, or want to get in touch with me directly, you can please do so as well.

Cheers!

Update

Stack Overflow has enacted a temporary policy of banning ChatGPT answers.

My account has also been suspended for 1 week for the use of ChatGPT. I'm not even a little bit mad, I had a good laugh.

What are some non-coding skills that make a strong developer?

Andrew Shearer — Wed, 21 Sep 2022 19:15:34 +0000

Set Up a Modern Shopify Online Store 2.0 Workflow with Shopify CLI

Andrew Shearer — Fri, 22 Apr 2022 01:46:59 +0000

In this post, I'll walk you through setting up a modern Shopify Online Store 2.0 workflow using the Shopify CLI. We'll essentially be creating themes off of branches from a GitHub repo! If that sounds exciting to you, or you want to start learning a bit about Shopify theme development, then let's get started!

Prerequisites

First, I'd highly recommend watching this YouTube video on the ShopifyDevs channel if you want to get up to speed with Shopify Online 2.0 and all of it's features.

After that, you'll need to create a Shopify Partners account. You can sign up for an account here.

Next, we'll need to install the Shopify CLI. But before we do that, we need to install Ruby first. Instructions for installing Ruby can be found here. Once you have Ruby installed, run the command ruby -v to make sure installation was successful. You'll see a version number appear if it was.

After that, you can then follow the instructions here to install the Shopify CLI. Similarly, you can run the command shopify version to make sure installation was successful. Again, you'll see a version number appear if it was.

Once you've got those installed, you're ready to get started!

Shopify Store Setup

Once you are in your Shopify Partners dashboard, click Stores, then Add Store. For a quick setup:

Click Development Store
Enter a Store Name and password
Select I'm just playing around for Store purpose

Now simply wait for the store setup to complete.

Once you are in the store admin, click Online Store. Here you should see Dawn as the Current theme. Dawn is now the default theme for OS 2.0 stores, and is actually open source!

Next, click Actions, and then click Download theme file. A popup will appear and say "Your theme files will be emailed to [YOUR-EMAIL-ADDRESS].". Click Send email. Go to your email, and click on the link "Your theme export is ready to download." link, and a .zip folder should be downloaded. Unzip the folder, and move the project to wherever you store your projects.

GitHub Setup

Go here to create a new repo. Then in your terminal, cd into the directory where you moved the theme files into, and open it in your text editor of choice

At the root level, create a .gitignore and README file:

touch .gitignore README.md

In the .gitignore file, add the code listed here to it as a starting point. In the README add any necessary info there, such as a main heading and some quick body text.

Next, run through all the git commands as shown in the GitHub page:

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/[YOUR_GITHUB_USERNAME]/[REPO_NAME].git
git push -u origin main

After that, go back to Shopify Admin. On the Themes page in the admin, scroll down to the Theme library section. Once there, click Add theme, and then select Connect from GitHub. Click Login to GitHub, choose your Shopify account, and click Authorize Shopify. If you cannot login and / or see a warning, simply logout and then login into the Partners dashboard again.

Select your GitHub account, and install Shopify if needed and give access to the repo, and then click Install. Enter in GitHub password if prompted.

Next, select your GitHub account from the dropdown, and then select the repo. We only have a main branch at this point, so you should only see main listed. Click Connect, and you should see the theme being added.

On this newly added theme, click Actions, then click Publish, then click Publish again in the popup. Now the published theme will be updated with all the latest commits on the main branch!

Local Development

To get started, use the Shopify CLI to login and select your account in the browser once the tab opens:

shopify login --store [STORE_NAME].myshopify.com

You can then run shopify whoami to confirm the login was successful.

To start a local development server, run the command: shopify theme serve. If you are not able to login and / or see this:

ERROR: You are not authorized to edit themes on online-store-2-0-learning.myshopify.com.

Try the following:

Logout of all Shopify accounts (both in the browser and in the CLI)
If your partner account AND personal account use the same email, try clicking on "Login with different account" - Clear browser cache
See this GitHub issue for other recommendations

And as a quick side note, once you are able to get the local development server up and running, you can open a new tab in your terminal check for any obvious linting or performance issues by running the command: shopify theme check

Making a Simple Change

In your text editor, open the file assets/base.css. Scroll down to around line 2185 and you should see this:

#shopify-section-header {
  z-index: 3;
}

Update it to this:

#shopify-section-header {
  background-color: transparent; /* this will do nothing, just making sure the workflow is working */
  z-index: 3;
}

Commit and push the change by running the command:

git commit -am 'simple change to header'
git push

Go back to the Store Admin, and click on View your store. Open dev tools and inspect the element #shopify-section-header, the background-color should be there!

Realistic Workflow

Now, it's really bad practice to work on the main branch / published theme as you don't want to push changes without being able to preview them first. Imagine you are working on a store for a client, and push changes to the main branch without getting their approval first!

So, to avoid any possible issues, we'll now setup the following:

Create a new staging branch and push this branch up to GitHub
Create a new theme based off the staging branch in the Theme Admin
Make any changes on a new branch, such as feature/... or bug-fix/...
- It's common when working on teams to prefix branch names this way
Create a PR to merge that branch into staging
We preview the changes on the staging theme
If we like the changes, we then merge staging into main

Full chain of commands to create a new staging branch, switch over to it, and push it up to GitHub:

git branch staging
git checkout staging
git push --set-upstream origin staging

To create a new theme based off this branch in the Theme Admin, scroll down to the Theme library section. Click Add theme, then Connect from GitHub. Select your GitHub account in the dropdown, and the repo. You should now see a staging branch listed. Click Connect, and wait for the theme to finish setting up.

Then, make any changes on a new branch, such as feature/... or bug-fix/.... We'll make a very obvious change: changing all text to red!

Create a new branch, switch to it, and push the branch up to GitHub:

git branch feature/red-text
git checkout feature/red-text
git push --set-upstream origin feature/red-text

Open assets/base.css, scroll down to the very bottom, and add this:

* {
  color: red;
}

Commit and push the change:

git commit -am 'changed all text color to red'
git push

Go back to Store admin, and on both the main and staging themes, click Actions, and then click Preview. You should NOT see red text color, which is correct!

Back in GitHub, open a PR to merge the feature/red-text branch into staging. You should be able to automatically merge, so click on Merge pull request.

Back in Store admin, you should now see the /staging theme, the time for Last saved should be Just now. If not, simply refresh the page.

Click Actions, then Preview for the /staging theme. You should see all the text is now red!

Let's assume we (we being an imaginary client) like this change. Repeat the above process to merge staging into main. Now we should see the red text on the main published theme.

But of course, we don't actually want this change. So, to practice this process a bit more, simply remove the code snippet and repeat the merging process again. After merging the PRs, you can delete the feature/red-text branch both locally and remotely by running:

git checkout staging
git branch -d feature/red-text
git push origin --delete feature/red-text

You can then double check the branch was deleted by running git branch, which displays a list of the local branches for your repo.

Moving Forward

Going forward, all work should be done off the staging branch. At the start of each update / ticket / etc.:

Switch to the staging branch: git checkout staging
Get the latest from GitHub: git pull origin staging
Create a branch off of staging:

git branch [NEW_BRANCH_NAME]
git checkout [NEW_BRANCH_NAME]
git push --set-upstream origin [NEW_BRANCH_NAME]

Make your changes, then commit and push to GitHub:

git add .
git commit -m 'MESSAGE_HERE'
git push -u origin [NEW_BRANCH_NAME]

Create a PR (ideally have someone review your PR if possible. If you are working by yourself, you can merge the branch into staging). Have the client review changes on the staging theme, and once approved, merge changes into main. Finally, delete the new branch locally and remotely:

git checkout staging
git branch -d feature/red-text
git push origin --delete feature/red-text

And repeat!

Here is a visual aid in case it is not clear:

main
^
|
|
staging <----------------
^           |           |
|           |           |
|           |           |
feature/... bug-fix/... update/...

I hope you enjoyed this article and found it useful. Thanks for reading!

An Extensive Comparison of Gatsby & Next.js (While Rebuilding My Portfolio)

Andrew Shearer — Fri, 15 Apr 2022 15:58:54 +0000

I was looking at my developer portfolio recently and decided it could use an update. While I kept it up to date with my most recent projects that I wanted to showcase, I wasn't a fan of the look anymore. I also thought it would be nice to use Contentful as a headless CMS to manage the content of the site, as well as fetch and display a couple of my most recent blog posts from here on dev.to.

I've mostly used Gatsby both at work and for personal projects, and I've been wanting to learn more about Next.js and become more familiar with using it, so I took this opportunity to start rebuilding my portfolio using both of these frameworks. I had a list of requirements in mind, so along the way I noted my experience with both frameworks and I want to share that experience with you here. Perhaps you will find it helpful the next time you need to decide which framework to use.

Requirements

I like to keep my portfolio nice and simple. The order of the sections are:

Hero (including nav)
Projects
About Me
Blog Posts
Contact
Footer

It's a single page, so I will not be looking to create dynamic routes / pages for any of my content. I would consider doing so for the blog posts since Contentful has a Markdown text box, and on dev.to you write in Markdown, so it would just be a copy paste. However, I wanted to see what would be considered best practice / convention for both:

Fetching content from Contentful using GraphQL
Fetching blog posts from the dev.to API using the good ol' Fetch API

A few other things I wanted to compare between the two were:

Downloading and starting with a basic boilerplate with TypeScript support
Integrating styled-components
A few points regarding Contentful:
- The use of environment variables
- Using webhooks to automatically update the hosted site whenever I make a change in Contentful
- Similarly, how changes in Contentful appear during local development
- Local development experience
- Using fragments for reusable queries
Optimizing images from Contentful
How easy is it to host a Gatsby and Next.js site

I also want to note that my intention wasn't to fully rebuild my portfolio with each, but more so I wanted to get the scaffolding done, compare my notes as well as any pros and cons of the requirements I've listed above, and from there I'll decide which one I plan to proceed with to complete the project.

I simply created 2 new branches on my existing portfolio repo, which I aptly named gatsby and next, and worked with each framework on their respective branch. In hindsight, it would've been much easier to just work with framework each in their own folders in isolation. Oh well! ¯\_(ツ)_/¯

So, let's get started!

Boilerplate

To start, I looked at what possible starter / boilerplates both frameworks offered. While both offer Contentful based starters, they are not in TypeScript OOTB. So, I decided upon using their basic TypeScript starter and building it up from there. That way, I have as close as a starting point for each as possible.

Next.js has supported TypeScript for a while now, but thankfully Gatsby also now has full TypeScript support too. Not just with pages and components, which they also have supported for a while now, but all of the Gatsby API files (gatsby-browser, gatsby-node, etc.) can also be written in TypeScript as of Gatsby v4.8 and 4.9.

For Gatsby, you can run the command:

npm init gatsby -ts

And for Next.js you can run the command:

npx create-next-app@latest --ts

A quick, minor note regarding Gatsby: in the documentation it says to run npm init gatsby and select TypeScript as your language when prompted. Or you can run npm init gatsby -ts to skip that question. In my experience, that is not true. When you run npm init gatsby -ts, you still have to select TypeScript as your language. So, it doesn't matter whether or not you include the -ts flag.

For Next.js, there is no questionnaire during setup, and I actually don't mind this at all, and it kind of makes sense if you think about it. Gatsby is focused on creating fast, static sites using headless CMSs. As such, it gives you a few options to pick from during setup in the CLI, as well as a few options for styling your app.

With Next, since it is a hybrid framework and it can be used for much more than static headless CMS-based sites, including a questionnaire is not ideal because there are just so many things to consider. Perhaps including a step for styling would be nice, and some other common inclusions such as linting, but I think it's fine without one.

Either way, both startup just fine after running npm run dev!

Styled Components

This is where things start to get interesting. styled-components is my go to approach for styling React apps myself. Otherwise, I usually go with Material UI (now MUI) or React Bootstrap.

Implementing styled-components into Gatsby and Next are quite different.

First, let's take a look at Gatsby.

Gatsby

With Gatsby, you will need to install the following NPM packages:

babel-plugin-styled-components
gatsby-plugin-styled-components
styled-components

And if you're using TypeScript like I do, then the @types package from DefinitelyTyped as well:

@types/styled-components

So, in total 3-4 packages. From there, you simply need to add gatsby-plugin-styled-components to your plugins array inside your gatsby-config file. After that, I typically create a styles folder inside the src folder, and then inside the styles folder I create 2 files:

GlobalStyle.ts
theme.ts

theme.ts will hold variables for the project such as colours, font sizes, breakpoints, etc. Here's the starting code I typically use:

const theme = {
  mediaQueries: {
    desktopHD: 'only screen and (max-width: 1920px)',
    desktopMedium: 'only screen and (max-width: 1680px)',
    desktopSmall: 'only screen and (max-width: 1440px)',
    laptop: 'only screen and (max-width: 1366px)',
    laptopSmall: 'only screen and (max-width: 1280px)',
    tabletLandscape: 'only screen and (max-width: 1024px)',
    tabletMedium: 'only screen and (max-width: 900px)',
    tabletPortrait: 'only screen and (max-width: 768px)',
    mobileXLarge: 'only screen and (max-width: 640px)',
    mobileLarge: 'only screen and (max-width: 576px)',
    mobileMedium: 'only screen and (max-width: 480px)',
    mobileSmall: 'only screen and (max-width: 415px)',
    mobileXSmall: 'only screen and (max-width: 375px)',
    mobileTiny: 'only screen and (max-width: 325px)'
  },
  shades: {
    white: '#fff',
    black: '#000'
  },
  greys: {
    // add any greys here
  },
  colors: {
    primary: {
      // add primary colors here
    },
    secondary: {
      // add secondary colors here
    }
  },
  fonts: {
    // add font-families here
  },
  fontWeights: {
    thin: 100,
    extraLight: 200,
    light: 300,
    normal: 400,
    medium: 500,
    semiBold: 600,
    bold: 700,
    extraBold: 800,
    black: 900
  },
  fontSizes: {
    // add font sizes here
  }
};

export default theme;

And GlobalStyle.ts will use the createGlobalStyle helper function to create a GlobalStyle component. This component will house global styles and any styling resets you want to include. Here is what I typically start with:

import { createGlobalStyle } from 'styled-components';
import theme from './theme';

// destructured theme properties
const { mediaQueries } = theme;

const GlobalStyle = createGlobalStyle`
  html {
    box-sizing: border-box;
    font-size: 100%;

    @media ${mediaQueries.desktopSmall} {
      font-size: 87.5%;
    }
  }

  body {
    /* add custom font-family here */
    line-height: 1;
  }

  *,
  *::before,
  *::after {
    box-sizing: inherit;
    color: inherit;
    font-size: inherit;
    -webkit-font-smoothing: antialiased;
    margin: 0;
    padding: 0;
  }

  button,
  input,
  textarea {
    /* add custom font-family here */
  }

  img,
  svg {
    border: 0;
    display: block;
    height: auto;
    max-width: 100%;
  }

  a {
    &:link,
    &:visited {
      text-decoration: none;
    }

    @media (hover) {
      &:hover,
      &:active,
      &:focus {
        outline: 0;
        text-decoration: underline;
      }
    }
  }

  ol,
  ul {
    list-style: none;
  }

  blockquote,
  q {
    quotes: none;
  }

  blockquote:before,
  blockquote:after,
  q:before,
  q:after {
    content: '';
    content: none;
  }

  table {
    border-collapse: collapse;
    border-spacing: 0;
  }

  audio,
  canvas,
  video {
    display: inline-block;
    max-width: 100%;
    zoom: 1;
  }
`;

export default GlobalStyle;

From here, we open the Layout component and wrap everything with the ThemeProvider component provided by styled-components. ThemeProvider must have a theme prop, so we can import the theme above. We will also place the GlobalStyle component as a child inside the ThemeProvider. In the end, your Layout file should look something like this:

const Layout = ({ children, title }) => (
  <ThemeProvider theme={theme}>
    <GlobalStyle />

    <Seo title={title} />

    <Navigation />

    <main>{children}</main>

    <Footer />
  </ThemeProvider>
);

And that's it! Now, any styled components we create will have access to our theme via props.theme like so:

background-color: ${(props) => props.theme.shades.white};

And just as a quick note, we can use destructuring to shorten it a bit:

background-color: ${({ theme }) => theme.shades.white};

In the end, a pretty quick setup! Now let's take a look at Next.js.

Next.js

With Next.js, we install all the same packages we would with Gatsby, except gatsby-plugin-styled-components of course.

From there, we can create a styles folder and also create the GlobalStyle.ts & theme.ts files as we did with Gatsby.

Next, while with Next.js you would typically have a Layout component, you actually do not want to wrap that component with ThemeProvider. Instead, you want to wrap everything in the _app.tsx file in the pages folder like so:

Before:

const MyApp = ({ Component, pageProps }: AppProps) => <Component {...pageProps} />;

export default MyApp;

After:

const MyApp = ({ Component, pageProps }: AppProps) => (
  <ThemeProvider theme={theme}>
    <Layout>
      <GlobalStyle />
      <Component {...pageProps} />
    </Layout>
  </ThemeProvider>
);

export default MyApp;

And we're done! Actually, no we're not. At this point, using styled-components will work just fine...sort of. If you either:

Manually refresh the page in the browser
Host this project, on Vercel or Netlify, for example

The styles will likely break. This is because the server-side rendering does not fetch the styles before rendering the page. To correct this issue, we need to inject server-side rendered styles to the head so it can render the page and its styles correctly.

Inside the pages folder, we need to create a file called _document.tsx. In that file, you will need this:

// next
import Document, { Head, Html, Main, NextScript } from 'next/document';
import type { DocumentContext, DocumentInitialProps } from 'next/document';

// styled components
import { ServerStyleSheet } from 'styled-components';

class MyDocument extends Document {
  static getInitialProps = async (ctx: DocumentContext): Promise<DocumentInitialProps> => {
    const sheet = new ServerStyleSheet();
    const originalRenderPage = ctx.renderPage;

    try {
      ctx.renderPage = () =>
        originalRenderPage({
          enhanceApp: (App) => (props) => sheet.collectStyles(<App {...props} />)
        });

      const initialProps = await Document.getInitialProps(ctx);

      return {
        ...initialProps,
        styles: (
          <>
            {initialProps.styles}
            {sheet.getStyleElement()}
          </>
        )
      };
    } finally {
      sheet.seal();
    }
  };

  render() {
    return (
      <Html>
        <Head>
          <link rel='preconnect' href='https://fonts.googleapis.com' />
          <link rel='preconnect' href='https://fonts.gstatic.com' crossOrigin='true' />
          <link
            href='https://fonts.googleapis.com/css2?family=Roboto:wght@100;300;400;500;700;900&display=swap'
            rel='stylesheet'
          />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

A BIG shoutout to Nicolás M. Pardo here on dev.to as he posted this in a comments section from a different article and it saved the day! And as you can see, I also just added the necessary code to include links to Google Fonts. If you don't need that, you can simply get rid of it.

Now we just need to restart the server and everything should be a-ok!

Contentful

In this section, we'll take a look at a few key areas:

The use of environment variables
Querying data from Contentful using GraphQL
The use of webhooks
Local development experience
Using fragments for reusable queries

The use of environment variables

Somewhat disappointingly, while going through the setup for Gatsby, after selecting Contentful as your headless CMS, the necessary .env files are not created as part of the setup. And with Next, you will need to set them up manually yourself.

Now to be fair to both, if you use the starter-gatsby-blog from Contentful themselves, the new gatsby-starter-contentful-homepage from Gatsby, or the Next.js Contentful example, these do use environment variables. It's just these basic starters that do not.

For Next.js, you simply need to create a .env.local file, and add in your variables like so:

VARIABLE_NAME=VALUE

Then restart your local dev server if it is currently running so Next.js can load in the variables. You should see Loaded from env in your terminal after the local dev server starts up.

For Gatsby, create 2 files:

.env.development
.env.production

Add in the same variables in both files and you will be good to go.

Querying data from Contentful using GraphQL

Both frameworks take a similar approach to querying data from Contentful using GraphQL. To greatly oversimplify things, the process essentially boils down to:

Make a query using GraphQL
Pass that returned data to your components as props
Display the data in your components

How each framework does that is of course different, and we'll explore it in further detail below.

But first, one thing I do want to give big props to is Gatsby's implementation of the GraphiQL playground. Specifically, including an Explorer. I have to admit, I have taken this for granted, as it makes structuring queries so, so much easier.

With Next.js, I ended up using the GraphiQL playground provided by Contentful themselves. You can view it here:

https://graphql.contentful.com/content/v1/spaces/YOUR_SPACE_ID_HERE/explore?access_token=YOUR_ACCESS_TOKEN_HERE

Just make sure to update the placeholders with your actual Contentful Space ID and Access Token.

Gatsby

With Gatsby, querying data from Contentful using GraphQL is very straightforward. In your page component file, you add your GraphQL query typically beneath the export default:

// component code up here...

export default Home;

export const homePageQuery = graphql`
  query HomePageQuery {
    contentfulHero(id: { eq: "ID_HERE" }) {
      title
      tagline
      backgroundImage {
        id
        description
        gatsbyImageData
      }
    }
  }
`;

In this example, I'm querying data from a specific Hero model I created, and I want the values from the title, tagline, and backgroundImage fields. I'll be discussing images in more detail later on.

To actually consume this data, the page component can access the returned data via the data prop. From there, you can pass it down as a prop to the corresponding component like so:

const Home = ({ data, location }: PageProps<GraphQLResult>) => {
  // just double check...
  console.log('data: ', data);

  return (
    <Layout title='Home'>
      <Hero contentfulData={data.contentfulHero} />
    </Layout>
  );
};

With TypeScript, we can also type out how the response will look. The name I've always used is GraphQLResult, but you can name it whatever you like. The type for this is just above the component like so:

type GraphQLResult = {
  contentfulHero: ContentfulHero;
};

const Home = ({ data, location }: PageProps<GraphQLResult>) => {
  // just double check...
  console.log('data: ', data);

  return (
    <Layout title='Home'>
      <Hero contentfulData={data.contentfulHero} />
    </Layout>
  );
};

I like to keep my types in a separate folder, so I import ContentfulHero wherever I need it. The type looks like this:

import type { IGatsbyImageData } from 'gatsby-plugin-image';

export type ContentfulHero = {
  title: string;
  tagline: string;
  backgroundImage: {
    id: string;
    description: string;
    gatsbyImageData: IGatsbyImageData;
  };
};

And the Hero component can also use this type for props:

type HeroProps = {
  contentfulData: ContentfulHero;
};

const Hero = ({ contentfulData }: HeroProps) => (
  <div className='wrapper'>
    <h1>{contentfulData.title}</h1>
    <p>{contentfulData.tagline}</p>
  </div>
);

export default Hero;

This way I have full type checking for my data, as well as some nice auto-completion when using the data in my component.

There are some tools you can use to automatically generate the types for your GraphQL Schema, such as GraphQL Code Generator. However, since this is a fairly small project, and I am the only dev working on it, I don't mind setting things up manually myself.

Next.js

With Next.js, the process is quite similar. However, there are multiple ways to query data with Next.js:

React hooks at the component level (useEffect with an async function is a common approach)
getStaticProps() at the page level
getServerSideProps() at the page level
useSWR() hook at the component level

For my purposes, since this is a static portfolio site, I will be using the getStaticProps() function. As outlined in the Next.js documentation, if the data is coming from a headless CMS, then getStaticProps() is a great choice. Check out the documentation on how the function works if you are not familiar with it, as I do not have the courage to explain it since I am still new to it.

Inside this function, we can make our request. This video from the Contentful YouTube channel was very helpful, and required minimal modification for TypeScript.

In the video, Lee recommends using the graphql-request package. And I have to say, as a first time user, I quite liked it! I will definitely look to use this again in the future!

To start, we will need to import GraphQLClient & gql from graphql-request as named imports:

import { GraphQLClient, gql } from 'graphql-request';

Then inside the getStaticProps() function, we can start with the following:

const endpoint = `https://graphql.contentful.com/content/v1/spaces/${process.env.CONTENTFUL_SPACE_ID}`;

const options = {
  headers: {
    authorization: `Bearer ${process.env.CONTENTFUL_ACCESS_TOKEN}`
  }
};

const graphQLClient = new GraphQLClient(endpoint, options);

Notice the value for endpoint is different than that of the URL you would visit in the browser!

Next, we can use the gql function to write our GraphQL Query, and we'll see some noticeable differences:

const homePageQuery = gql`
  {
    hero(id: "ID_HERE") {
      backgroundImage {
        sys {
          id
        }
        description
        height
        url
        width
      }
      tagline
      title
    }
  }
`;

The first is actually ID_HERE. When using the Explorer in Gatsby's GraphiQL playground, you can either use the ContentfulId or Id. The latter looks like this:

a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1

Where the As and 1s could be any combination of letters and numbers. With Next.js, you don't get this type of ID. Instead, you simply use the ENTRY ID for whichever piece of content you are querying for.

To see this ENTRY ID, select any piece of content you have created in Contentful. Then on the right-hand sidebar menu, select the Info tab. Second from the top is the ENTRY ID. In all fairness, you could also use this in your GraphQL queries with Gatsby as well. I've always just used the long-form id above out of habit.

The next difference are the fields we can query for the image. We'll need these files to pass them on to Next.js's <Image /> component. Again, we'll discuss each framework's approach to images and image optimization later.

Finally, store the returned data in a variable like so:

const data: ContentfulResponse = await graphQLClient.request(homePageQuery);

Then return in a props object:

return {
  props: {
    data
  }
};

Here, I am using the ES6 object shorthand where if the key and value are the same, we can write like I have above instead of like this:

return {
  props: {
    data: data
  }
};

So all together, getStaticProps() looks like this:

export async function getStaticProps() {
  // get contentful data
  const endpoint = `https://graphql.contentful.com/content/v1/spaces/${process.env.CONTENTFUL_SPACE_ID}`;
  const options = {
    headers: {
      authorization: `Bearer ${process.env.CONTENTFUL_ACCESS_TOKEN}`
    }
  };

  const graphQLClient = new GraphQLClient(endpoint, options);

  const homePageQuery = gql`
    query HomepageQuery {
      hero(id: "ID_HERE") {
        backgroundImage {
          sys {
            id
          }
          description
          height
          url
          width
        }
        tagline
        title
      }
    }
  `;

  const data: ContentfulResponse = await graphQLClient.request(homePageQuery);

  return {
    props: {
      data
    }
  };
}

Now in the Home page component, we can access this data prop like so:

const Home: NextPage<HomeProps> = ({ data }) => {
  console.log('data: ', data);

  return (
    <div>
      <Hero />
    </div>
  );
};

And to be clear, data is just the name I chose. I could've called it hero if I wanted to, and accessed it via a hero prop instead. I like using data because I'll be adding on to the GraphQL query later on querying for multiple pieces of content. So, data is just a generic variable name I like to use, and comes from the habit of using Gatsby.

And just like before with Gatsby, we pass the data down to the corresponding component:

const Home: NextPage<HomeProps> = ({ data }) => {
  console.log('data: ', data);

  return (
    <div>
      <Hero contentfulData={data.contentfulHero} />
    </div>
  );
};

And that's it! That's how we can query data from Contentful with both frameworks with GraphQL. Personally, I don't really have a preference. I think both are perfectly fine.

And as a quick side note, I would extract the querying logic in getStaticProps() into a separate file and folder to make the code inside getStaticProps() cleaner, as well as make the query a bit more reusable. It would require some modification, but it would make for a good starting point.

The use of webhooks

When it comes to hosting, whether you choose Netlify, Gatsby Cloud, or Vercel, they all have options to set up both environment variables, as well as webhooks that you can use with Contentful. This way, whenever you make a change, or mutliple changes, in Contentful, the site will rebuild with the latest data.

Local development experience

An interesting note here is that with Gatsby, during local development, whenever you make a change in Contentful, it will not appear while the local dev server is running. You must restart the server, and clean the public and .cache folders as well. So, I would recommend adjusting the dev script in package.json to the following:

"clean": "gatsby clean",
"dev": "npm run clean && gatsby develop",

This is because Gatsby will run your GraphQL queries during build time, and not run time. Therefore, a restart is required.

With Next.js however, you simply need to manually refresh the page in the browser, and any changes will be seen.

Using fragments for reusable queries

The great thing about querying data with GraphQL is you can use something called fragments. Fragments help by cutting down on repeated query fields.

Gatsby

With Gatsby, creating reusable fragments is very straightforward. In the src folder, I typically create another folder called graphql. In the graphql folder, I then create a file called fragments.ts. Here, let's create a highly reusable fragment for fields for an image:

export const imageFields = graphql`
  fragment ImageFields on ContentfulAsset {
    id
    description
    gatsbyImageData(placeholder: BLURRED)
  }
`;

What's so nice about this is that Gatsby automatically exports these queries to the global scope. So, these fragments are available in any other GraphQL query in the entire project! We can even use our fragments in other fragments!

And just as a quick side note, I like to include id here even if I'm only querying for a single image because in the instance I do query for multiple images, I have the id's ready to use for mapping over the array and using them as the value for the key prop.

Now, let's say for example we have a standard 50/50 model, with heading & copy on the left and an image on the right. For the fragment, it would look something like this:

export const fiftyFiftyFields = graphql`
  fragment FiftyFiftyFields on ContentfulFiftyFifty {
    id
    heading
    copy {
      copy
    }
    image {
      ...ImageFields
    }
  }
`;

Now we can use this fragment in the HomePageQuery, for example, like so:

export const homePageQuery = graphql`
  query HomePageQuery {
    firstFiftyFifty: contentfulFiftyFifty(id: { eq: "ID_1_HERE" }) {
      ...FiftyFiftyFields
    }
    secondFiftyFifty: contentfulFiftyFifty(id: { eq: "ID_2_HERE" }) {
      ...FiftyFiftyFields
    }
  }
`;

In this example, we can also see aliases being used. Aliases let you rename the result of a field to anything you want. This is helpful for when you are querying the same thing but with different arguments.

So, combining fragments and aliases really help make our queries shorter, cleaner, and easier to read and write.

Next.js

With Next.js, while we don't get automatic global scoped fragments, we can still create and use them, just with a little bit of extra work.

We can start with the same process by creating a fragments.ts file inside of a graphql folder. Let's create a reusable Image fragment:

import { gql } from 'graphql-request';

export const FRAGMENT_IMAGE = gql`
  fragment ImageFields on Asset {
    sys {
      id
    }
    description
    height
    url
    width
  }
`;

Now back in the index page file, inside getStaticProps() and then inside our gql template string, we can go from this:

const homePageQuery = gql`
  query HomepageQuery {
    hero(id: "ID_HERE") {
      backgroundImage {
        sys {
          id
        }
        description
        height
        url
        width
      }
      tagline
      title
    }
  }

  # fragments
  ${FRAGMENT_IMAGE}
`;

To this:

const homePageQuery = gql`
  query HomepageQuery {
    hero(id: "ID_HERE") {
      backgroundImage {
        ...ImageFields
      }
      tagline
      title
    }
  }

  # fragments
  ${FRAGMENT_IMAGE}
  # make sure to import this!
`;

It may not look very powerful right now when querying a single piece of content, but I'm sure you can imagine if this homepage had say 8-10 sections, all of them containing images, having the same fields repeated over and over again would make the query very long and rather difficult to traverse.

Image Optimization

Both frameworks come with image optimization OOTB in the form of components. Next.js has <Image />, and Gatsby has both <StaticImage /> and <GatsbyImage />.

Let's explore their differences:

Gatsby

Gatsby comes with 2 different image components. When you should use which? The answer to that is very simple.

Is the image you're using the same every time the component is rendered? For example, the site logo, or any other picture located within the project locally? Then use <StaticImage />.

Is the image you're using going to be passed into a component as a prop, and / or coming from an external source, such as Contentful? Then use <GatsbyImage />.

Since this article is all about Contentful, we'll be focusing on <GatsbyImage />!

In the GraphiQL playground, whenever you want to query for an image (or multiple images), I'd recommend getting the following fields:

id
description
gatsbyImageData

With this, we can create a reusable fragment for querying those fields on images (known as Assets in Contentful):

export const imageFields = graphql`
  fragment ImageFields on ContentfulAsset {
    id
    description
    gatsbyImageData(placeholder: BLURRED)
  }
`;

When you execute the query with these fields, you'll see a ton of data for the gatsbyImageData field. But don't worry, the <GatsbyImage /> component will handle all of that for us!

You would use that data like so:

<GatsbyImage image={contentfulData.image.gatsbyImageData} alt={contentfulData.image.description} />

You can see in my fragment above I also added (placeholder: BLURRED). This will do as the wording suggests! It will blur the image until the full res version is ready to use. This will help cut down on page load time and help improve performance.

Next.js

With Next.js, we get a single <Image /> component that we can use for both static and dynamic images. And very similarly to Gatsby, as long as we pass it the right data for its various props, it will handle all the heavy lifting for us!

And just like with Gatsby, we can create a highly reusable fragment like we did above in the previous section to query certain fields from Contentful. We would then use that data like so:

<Image
  src={data.hero.backgroundImage.url}
  alt={data.hero.backgroundImage.description}
  width={data.hero.backgroundImage.width}
  height={data.hero.backgroundImage.height}
/>

And that's it! Well...sort of. With Next.js, there is one more step. We have to add the domain these images are coming from to an array in our next.config.js file. This array holds an array of domains that are whitelisted. This tells Next.js that it is ok to fetch the images from these external sources and optimize them:

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ['images.ctfassets.net']
  },
  reactStrictMode: true
};

module.exports = nextConfig;

Ok, now we have optimized images from Contentful!

Blog Posts

Now that I'm writing blog posts here on dev.to, I wanted to incorporate them into my portfolio as well. While Contentful does have a Markdown text box that I could just copy and paste the post into and create dynamic routes with either framework, I was more interested in how I would query data from 2 different data sources using 2 different methods:

Querying content from Contentful using GraphQL
Querying posts from dev.to using REST API w/ Fetch

Let's take a look!

Gatsby

With Gatsby, I had an assumption of how I would query for my blog posts, and after some research (aka quick Googling), it seems like my assumption was correct.

I created a BlogPosts component, and inside that component I made the fetch call like so:

const BlogPosts = () => {
  const [posts, setPosts] = useState<DevPost[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  const fetchBlogPosts = async () => {
    setIsLoading(true);

    const response = await fetch('https://dev.to/api/articles?username=andrews1022');
    const data: DevPost[] = await response.json();

    setPosts(data);

    setIsLoading(false);
  };

  useEffect(() => {
    fetchBlogPosts();
  }, []);

  return (
    <div>
      <h2>Posts</h2>
      <div>
        {isLoading ? (
          <p>Loading...</p>
        ) : (
          posts.map((post) => (
            <div key={post.id}>
              <p>{post.title}</p>
            </div>
          ))
        )}
      </div>
    </div>
  );
};

Now I realize I don't have error handling in the form of an error state, or a cleanup in my useEffect, but that's ok since I'm just trying things out before making any large commitments.

This is a pretty standard approach:

Have state for the data, loading, and error
Write an async function that queries the data, and updates the various pieces of state accordingly
In the useEffect hook, call the async function and have an empty array of dependencies so this function will only be executed once when the component is first mounted / rendered

And that's it! My blog post titles display just fine. With Next.js though, that's where things get a little spicy.

Next.js

With Next.js, we can take advantage of the getStaticProps() function and add this additional request below the GraphQL query to Contentful and return it alongside the data like so:

export async function getStaticProps() {
  // make the contentful query up here...

  // get dev.to data
  const postsResponse = await fetch('https://dev.to/api/articles?username=andrews1022');
  const posts: DevPost[] = await postsResponse.json();

  return {
    props: {
      data,
      posts
    }
  };
}

Again, I realize there isn't any error handling here, this is just for the sake of demonstration purposes. And in case I didn't mention earlier, the DevPost type is a custom type I created.

With these posts, I can pass them down to my BlogPosts component:

<BlogPosts posts={posts} />

And then loop over them and display them like so (just the title for now to make sure things are working):

type BlogPostsProps = {
  posts: DevPost[];
};

const BlogPosts = ({ posts }: BlogPostsProps) => {
  return (
    <div>
      <h2>Posts</h2>
      <div>
        {posts.map((post) => (
          <div key={post.id}>
            <p>{post.title}</p>
          </div>
        ))}
      </div>
    </div>
  );
};

Why I think this is spicy is because since Next.js pre-renders the page at build time using the props returned by getStaticProps(), there is no awkward Loading... text or spinner being shown temporarily. Everything is just...there! I'm still getting used to Next.js, so I probably didn't explain that very well but I just think it's neat (insert Marge Simpson meme here)!

Hosting

Hosting is dead simple no matter which you pick. Each framework has their own hosting service which they recommend:

Gatsby Cloud for Gatsby projects, and Vercel for Next.js projects.

You could also use Netlify if you wish.

Whichever you pick, you can select your project from GitHub (once you have given it authorization to do so), and the service will automatically build and host the site for you!

And as previously mentioned, you can include environment variables for your Contentful API keys, as well as setup webhooks with Contentful.

Final Thoughts

Whew, that was a lot! If you made it this far, thank you so much for reading this post. I had a lot of fun researching and trying out the various points I mentioned here, and it was great to try out and learn more about Next.js some more as well.

My goal for this article was to simply show you each framework's approach for common tasks and let you decide which approach(es) you do or don't like. Personally, I'm going to stick with Next.js to build out the rest of my portfolio simply because I want to become more familiar with it and learn more about it.

In my opinion, for a simple static like this, you really can't go wrong with either framework. If you have more experience with one over the other, I would recommend trying the other and see what you think. I provided my experience here and I hope you found it useful.

Cheers!

The New Gatsby Homepage Starters - Less Is More

Andrew Shearer — Sun, 13 Mar 2022 16:35:50 +0000

GatsbyConf was just last week, March 2nd & 3rd 2022, and it was a blast! A ton of informative talks, workshops, and being able to talk directly with sponsors was something I've never done before and thoroughly enjoyed and I can't wait for it to happen again next year!

During the conference, a couple of things in particular that were announced piqued my interest:

TypeScript support - between v4.8 & v4.9, we can now have the Gatsby API files (gatsby-browser, gatsby-srr, gatsby-config, and gatsby-node) using .ts without any extra configuration!
New CMS starters - new headless CMS starters were released for Contentful, DatoCMS, Drupal, & WordPress!

So, I recently decided to sit down and try out the new Contentful Homepage Starter, as that is the CMS I am most familiar with. And what I found was rather interesting.

I truly enjoy using Gatsby to build Jamstack websites. Integrating a headless CMS like Contentful is so simple to do thanks to Gatsby's plugin ecosystem. From my experience, it basically boils down to:

Adding the plugin to gatsby-config
Double checking I entered in the correct API keys

And it just works seamlessly. Gatsby makes it so simple, which I greatly appreciate.

This post outlines my experience with the new Contentful Homepage starter. I am going to provide my honest and upfront feedback and I hope that it is found helpful. If I say anything that is incorrect from a technical perspective, then please let me know and I will absolutely correct that mistake.

Setup

The setup for the starter was very straightforward. I created a new folder in my projects directory, downloaded the starter using npx, ran the setup command, entered in my Contentful API keys, started up the local dev server, and I was up and running (more detailed steps can be found on the GitHub page, of course)!

At this point I will mention that I cleared out my existing Contentful space of all the content and content models I had previously created. It was merely a playground for testing things, and had no real purpose, so I didn't mind. The setup script also recommends an empty space too anyways.

Next, I opened the project in VS Code and I noticed the typical starting files and folders for a Gatsby project. However, once I started digging a bit deeper, I noticed quite a few things which I thought were quite atypical. And once I opened Contentful in my browser, I couldn't help but be a bit surprised.

Contentful Overload

During setup, I noticed it was taking longer than I expected to generate & import the content into Contentful. That's because compared to the Contentful Gatsby Blog Starter, there is A LOT more content being created here. Like, a lot. With this new homepage starter, you get in total:

33 content models
113 pieces of content
55 pieces of media (images, icons, etc.)

Compared to the Contentful Gatsby Blog Starter:

2 content models
4 pieces of content
4 pieces of media

That is quite a significant difference. So, why is there so much content at the start here? The answer to this question, I think, can be found at the top of the README:

"This starter demonstrates how to use Contentful to build a homepage and can be customized to match your own visual branding."

The keyword here, I think, is "demonstrates". This is supposed to be a demonstration of how to use Contentful with Gatsby. But after having gone through the code and looking at the abundance of generated content, I found myself trying to answer yet another question:

"Who is this starter for?"

The answer to this question, for me, is:

I don't know.

Generic Content

One glaring issue with the generated content in Contentful is that most of it is tied too heavily to a specific page. With this homepage starter, while we have in total 9 links in the main navigation, we only get 2 fully built pages: Home and About.

Which is fine, no problem there. However, out of the 33 generated content models:

17 are for the Homepage (not including the page itself)
6 are for the About page (again, not including the page itself)

Combined, that means approximately 70% of the content models are tied to specific parts of a specific page. Now, one possible reason for this might be to very explicitly tell devs where everything is exactly. However, I feel like there are 2 major issues with this approach, aside from it being rather hand-holding:

Price
Reusability

Price

Let's tackle price first. If you head over to Contentful's pricing page, you'll quickly realize that Contentful is NOT cheap once you move out of the free Community tier. I'll be nice and tell you if you're too lazy to look: it's $490 USD per month. Yes, that's right, per month. Now, granted that is intended for a team, but still, quite the jump from $0 to $490. Or for me as a Canadian, that is ~$625/month! Granted, again, it is intended for a team and you likely have a source of income to offset the cost.

However, the reason why I bring this up is because with the Community tier, AND with the Team tier actually, you are limited to only 48 different content models. And if you recall, I previously said that this starter comes with 33 content models out of the box. So, that means you are already using up ~68% of your total allowed content models. Therefore, this pattern of creating models for specific parts of a specific page simply cannot sustain itself.

Reusability

This is where the issue of reusability comes in. I think it would be better to create more generic named content models, as it would better highlight their reusability by placing the same types of content on multiple pages throughout the site.

Not only this, but there is some duplication with the existing content models as well. There is Homepage Stat List and About Stat List. What's the difference here? The difference is on the Homepage, there is some extra/surrounding content, and on the About page it is just the group of stats in a row. Why not create a single generic Stat List model, and reference a Stat List piece of content either in a different model or just display it in a simple row/grid wherever you want?

I really like some of the existing models, such as Blog Post, NavItemGroup, Page, SocialLink, and the 3 Layout models (although a minor thing, I would change LayoutFooter and LayoutHeader to just Footer and Header. I think we all know what a Footer and Header are). These provide great flexibility and are highly reusable, which is fantastic! Perhaps consider making some more generic models like:

CTA
- Have fields for the text and the slug where the CTA should take you
Author
- Have this as a reference field for Blog Post
[SOMETHING] Group
- In this model you reference as many of the individual content models as you like
- For example, Stat Group. You then have a field to reference as many individual Stats as you like
- Now you have created a single Group which can be reused wherever you like
- Do the same for things like Cards (Icon, Heading, Copy, Link), Team Members (Picture, Name, Role in Company), and more

So, I think to truly show the power of Gatsby + Contentful, it would be wise to consider:

Creating more generic pieces of content
Building out more of the pages within the starter using these pieces of content

The benefits of this are:

I can see how reusable pieces of content can be
I can change which pieces of content I want to show on a given page (using the Page model) that were already in place, or I can add new ones that I create

Ultimately, I think there is too much content being created at the start here. There is, I think, a pretty decent chance you will end scrapping a decent portion of these models and content. Or, you will have to spend a lot of time restructuring/renaming it to meet your project's needs, which is not ideal. On the other hand, the existing contentful/starter-gatsby-blog I think has too little content. Therefore, I think there needs to be a nice middle ground with the quantity of content being generated out of the box.

Lastly, while I like the idea behind the About Page and Homepage models, this isn't exactly ideal. Due to the limitation of the number of content models you can create, this pattern will not be able to continue much longer (creating models for individual pages). Something I have tried to do before is create a single Page model and render that model using a single template file in the code. This model would have fields like:

Title
Slug (automatically generated based off the Title)
Content or Sections (reference as many pieces of content as you wish. Things like 50/50's, Groups, Hero's, etc., to structure the various blocks/sections for a page as needed)

Some issues with this approach though are:

This gets kinda sloppy with GraphQL, as you have 1 really large query at the bottom of the template file. I suppose you could try breaking it up with fragments to make it a bit cleaner, though
You need to make sure to have a ComponentToRender field on all of the models you wish to use as a section

You can see my approach here (at the time I already had a Page model, so I named it Dynamic Page just for testing as an FYI). We can use React.lazy() to dynamically import and render each component based on the value of the ComponentToRender field, and pass along the content as a prop. You then set the styles/props/types/etc. for each component as you normally would.

I like this approach as it allows you to create a single template for (theoretically) an endless number of pages. Again, the GraphQL query would become incredibly long and rather difficult to maintain.

Another drawback to this setup though is that the workflow has a lot of steps that you have to do each time:

Create the model
Ensure the model has a ComponentToRender field (you can set a default value to save you some time from entering in a value each time you create a Page)
Create/style/type the component
Add it to the long GraphQL query in the template file

Where I do think this approach might come in handy is if you have a parent page, say Services, and then you have multiple pages for each Service where the order of the sections on each page is the exact same, just that the content is different. So, you can create a single template like I did, and this ensures that the GraphQL query is of a certain length, remains consistent, and is easier to maintain.

The Code

Regarding the code of this starter, I'm just going to list a few things I noticed and outline some areas that I think could be improved:

Organize scripts in `package.json`

This is something that annoys me a bit not with this starter, but most projects in general. Put your scripts in alphabetical order! It makes it so much easier to find/edit/update/add scripts to the list.

Organize `dependencies` in `package.json`

I've personally never understood why we need both dependencies AND devDependencies. Either way, you depend on that package. Why the separation? It seems highly redundant to me. Why not group all of them together into a single dependencies object and order them alphabetically to keep things nice and tidy?

Create React App made the decision to consolidate everything to into dependencies a few years agi, and you can see Dan Abramov's explanation here. I of course agree with the reasons he provided, but in all reality, if you want to move packages out of dependencies into devDependencies, you are more than free to do so.

Organize components into their own folders

This starter comes with 22 different component files. I understand everyone has their preferred approach for organizing components (and that may be why things are as they are as devs will move things around as they please anyways), but a common approach I see mentioned online often is:

src/
  components/
    ComponentA/
      ComponentA.js - The actual React component
      ComponentA.styles.js - The Styled Components file for the component (could also be .css or .scss module, of course)
      ComponentA.test.js - The tests for the component
      ComponentA.stories.js - The Storybook file for the component
    ComponentB/
      ComponentB.js
    ComponentC/
      ComponentC.js
    etc.

I think when you have this many components all grouped together, it looks disorganized. Gatsby is an opinionated framework, and therefore it makes sense to have an opinion on how components should be organized. But if this is their opinion on how things should be organized, having nothing in folders, then that is pretty disappointing, and I would strongly encourage Gatsby to reconsider.

Lastly, I noticed there was a Fallback component being used in both the home and about page files. I think it would be wise to create a single Fallback component in the components folder and import it from there to cut down on duplication of code.

UI Components

In addition to the point above, there is a file in the components folder called ui.js. In this one file, there are 28 UI components. Now, having all your components all in a single file should make it easier to maintain, in theory. In practice, this also feels highly disorganized. I think it's best to keep a 1:1 ratio: 1 component to 1 file. So, the structure would then ideally be something like this:

src/
  components/
    ...
    ui/
      Base
      Container
      Flex
      etc.

The import would then look something like:

import Base from 'components/ui/Base'

Which I think is totally fine! This is similar to how you import components from Material UI, a popular React UI library.

Finally, I found the code in ui.js difficult to understand. I'm not entirely sure what is going on for some of the components, specifically the cx & Base components. I think it would be helpful to at least include some comments noting what their purpose is and/or how they work.

Conditional Rendering

I would suggest not using && for conditional rendering. You should be using the ternary operator with the desired 'or' case, or just return null. The reasons why are explained here by Kent C. Dodds in a blog post.

Spacing

A lot of the code is not spaced enough, I think. For example, the component caret.js.

I think there should be a line break between the imports and the function, as well as a line break between const height ... and return. I personally find that when code is spaced out a bit, it makes it much easier to read.

Custom Hooks

I would like to suggest moving the uses of useStaticQuery into their own hooks. For example, the footer and header components. Extract these hook calls out and wrap them in their own custom hooks, such as useFooter() and useHeader(). The benefits of this are that it shows devs how to use custom hooks if they have little or no experience doing so before, and it makes the function code a lot leaner and easier to read.

Props Spreading

I would like to strongly encourage prop spreading to be removed where it is being used. The reason for this I think is explained perfectly on the react/jsx-props-no-spreading ESLint page:

"Enforces that there is no spreading for any JSX attribute. This enhances readability of code by being more explicit about what props are received by the component. It is also good for maintainability by avoiding passing unintentional extra props and allowing React to emit warnings when invalid HTML props are passed to HTML elements."

This leads into my next point, which is regarding TypeScript.

TypeScript

As mentioned near the beginning of this post, between Gatsby v4.8 & v4.9, we can now have the Gatsby API files using .ts without any extra configuration. Which is fantastic! I was so happy to see this update!

However, with the heavy use of props spreading, I think it might lead to some frustration/confusion over how to type each of the components props, as well as typing out values returned via GraphQL queries (although, there are ways of doing the latter automatically with tools like GraphQL Code Generator).

Furthermore, it would be great to have an all TypeScript version of not only this starter, or these new homepage starters, but for all official Gatsby starters. As far as I can tell, this is only true for gatsby-starter-minimal. And while we can have our entire Gatsby project using TypeScript, we still do not get type checking in the CLI. Hopefully this comes in a future release.

gatsby-config

A minor point, but in gatsby-config.js, there is require('dotenv').config() twice, one with and one without an options object argument. Not sure why that is the case, as the second one with the options object being passed in is perfectly fine on its own.

Also, if you implement ESLint into your project, you will get the import/no-extraneous-dependencies error. This error appears when you are using a specific package not listed in your package.json. Gatsby uses dotenv under the hood, so everything will work just fine, but I think it is best to include it in package.json.

Optional

Now, just a short list of some minor things you may or may not be looking to do, or have to do, depending on your/your teams workflow:

Replace react-feather with something like Font Awesome or Material UI Icons, or another icon library
Replace @vanilla-extract with styled-components, emotion, or other CSS-in-JS library, or .css/.scss modules
Convert all components to use function expression syntax if that is your preference
Change import * as React from 'react'; to import React from 'react';
- This way you can stop using React.something(), and just import what you need (ie. hooks): import React, { useState } from 'react';

Going Forward

So, let's try and answer this question from before:

"Who is this starter for?"

Based off the time I have spent with this, I believe the answer to this question is a developer who is:

New to Gatsby (or React in general)
New to not just Contentful, but building Jamstack apps/using headless CMSs in general

Now, there is nothing wrong with creating a starter for that type of developer. However, if you meet that criteria, you might:

Find the amount of pre-generated content overwhelming
Like that content models are separated by page. However, as outlined earlier, both the Community and Team tiers for Contentful have a limit to how many models you can create, and Contentful is not cheap

If you are an experienced dev, and have your own preferred workflow, you will find yourself spending a lot time initially updating/refactoring both the code and the content in Contentful.

If you work for an agency, you/your team may or may not:

Have your own starter that you may or may not maintain
Have a go-to list of NPM packages for certain functionality. Therefore, you may or may not have to heavily modify this starter
Take this starter and modify it to your teams workflow, and have your own custom starter
- Or you can start from scratch each time for a new project/client. But if you create your own custom starter, you then have to maintain it / update it

So, how do we move forward from here?

I think there are a few options to consider:

Refactor this starter both content and code wise
Create slightly different versions of these starters with varying quantities of content for varying skill levels
Make TypeScript only versions of these starters

In the end, these are just my opinions and my opinions alone. Gatsby could absolutely just ignore what some random person is saying about them on the internet. However, I do truly hope you’ve found the opinions I have expressed here in this post at least a little helpful. And even if Gatsby took 1 small, minor thing I've mentioned here and implemented it, I would take immense pride in knowing that. If anyone from the Gatsby team would like to get in touch with me to discuss any of the points I've made, or if I can assist in any other way, you can reach out to me on Twitter and I would be more than happy to discuss things there.

Thank you for reading.

Setup a modern Jamstack project using Gatsby, TypeScript, Styled Components, and Contentful

Andrew Shearer — Sat, 26 Feb 2022 21:37:59 +0000

In this post I will walk you through setting up a modern Jamstack project using Gatsby, TypeScript, Styled Components, and Contentful! Contentful and Gatsby work very well together, as Contentful allows you to focus on easily creating content for your site, and Gatsby provides a super fast, static site.

Here's a quick rundown of the tech we'll be using:

Before we started, there are a few prerequisites:

Node.js (which comes with NPM) is installed on your machine
Text editor of your choice (I will be using VS Code)

Something else I will also mention is that I use Linux, so all the commands listed below work in a UNIX environment, such as Mac or Linux. For Windows, some of these commands may not work, so you will have to find out the equivalent.

Please check out the repo I've created with the finished files. You can use this if you get stuck and need to reference anything.

You'll also notice that I make push commits to GitHub frequently throughout the process. I like this approach because it's easier for me to see incremental progress rather than a large number of changes all at once.

Lastly, I prefer to stick with NPM. If you use Yarn, simply replace NPM commands (such as npm i) with the corresponding Yarn command (yarn add).

With all that out of the way, let's get started!

Contentful Setup Pt. 1

The first thing we'll do is set up a free account with Contentful. You can do that here. To keep things simple, I would recommend signing up with your GitHub account.

After you've created your account, you should see your empty space (or be prompted to create one, and please do if you are). It is important that you do NOT add anything to this space. The reason why will come up soon!

Go to Settings, and then API Keys. Make sure you are on the Content delivery / preview token tab. Click Add API key in the top right corner, and then give the keys a name, something like "Gatsby Blog" for example, and perhaps also a short description, then click Save.

Make sure to keep this tab open as we will definitely need it later!

GitHub Setup

First, create a new GitHub repo here. Give it at least a name, and perhaps also a short description, then click Create repository. Keep this tab open, we'll need it in just a bit!

On your local machine, open up your terminal of choice, and cd where you store your projects. From there, create a new directory and then go into it:

mkdir PROJECT_NAME && cd PROJECT_NAME

PROJECT_NAME here being the name of the repo.

Next, download the Gatsby Contentful starter:

npx gatsby new . https://github.com/contentful/starter-gatsby-blog

Using npx means we don't have to install the gatsby package globally on our machine, which I personally prefer.

After the starter is done downloading, open it in your code editor of choice. Again, I use VS Code, so I can run the command code . and it will open the project in VS Code for me.

Next, let's remove git from this folder so we can start from scratch:

rm -rf .git

Finally, go back to the GitHub tab in your browser and run each of the git commands listed. If you want to make things easier on yourself, here they all are below in one long command:

git init && git add . && git commit -m "project setup" && git branch -M main && git remote add origin https://github.com/GITHUB_USERNAME/PROJECT_NAME.git && git push -u origin main

Just make sure to replace GITHUB_USERNAME with your GitHub username, and PROJECT_NAME with the name of the repo you just created.

Contentful Setup Pt. 2

Now, typically when you finish downloading a React boilerplate/starter project such as this, you may be inclined to start up the local development server and take a look. Well, you can do that here too, but as you may have guessed by the way I said that first thing, it's not going to work. If you run the command npm run dev to start up the local dev server, you'll see an error like this:

Error: Contentful spaceId and the access token need to be provided.

At this point, I want to give props (pun absolutely intended) to the Contentful team because with this starter, they have actually included a setup script for us! This script will generate a couple of basic content models in our space, as well as a few pieces of starting content! This is why it's important to keep the space empty, so that the setup script can populate it. It's as simple as running the command: npm run setup.

Once you run this command, you will have to enter your API keys in the following order:

Space ID
Content Management API Access Token *
Content Delivery API Access Token

Go back to your browser and go to the tab/window you had open with Contentful. You can easily copy and paste in your Space ID first, but, wait...where's the Content Management API Access Token? And why is there a * next to it above?

For this, I would recommend clicking on Settings, then clicking on API keys but this time open it in a new tab. Here, you can click on the Content management tokens tab. Click Generate personal token, give the token a name, and then click Generate. Copy and paste this token into the terminal. Then go back to the other tab and copy and paste in your Content Delivery API Access Token.

The reason we did it this way is because if you:

Got your Space ID
Went back, got your Content Management API Access Token
Went back again, got your Content Delivery API Access Token

It's just a lot of back and forth in the same tab.

Also, as you would have seen when you generate your Content Management API Access Token, this token will NO LONGER be accessible once you close the tab / move away from this page. Save it if you wish, but we actually do not need it at any other point in this process. We just needed it for the setup script.

After that is done, now you can run npm run dev to start the local development server!

Gatsby Cloud Setup

For deployment, we'll be using Gatsby Cloud. Gatsby Cloud is set up to optimize your Gatsby site, and adding a new site is very easy to do.

First, you'll need to create a free account if you do not have one already. You can sign up here.

For any subsequent visits, you can go straight to your dashboard here.

Once you are in your dashboard, click Add a site +. Choose to import a GitHub repository (at this point you will have to authorize Gatsby Cloud to access your GitHub repos if this is your first time using it). Find the repo you created, and click Import.

For Basic Configuration, you can leave the settings as-is and click Next.

For Connect Integrations, Gatsby Cloud should automatically detect you're using Contentful based on your gatsby-config. Click Connect, then click Authorize, then click Authorize again. Select the Space you created earlier, then click Continue.

For Environment variables, Gatsby Cloud actually sets up a couple extra ones for us that we don't need to use. You only need the following:

Build Variables
- CONTENTFUL_ACCESS_TOKEN --> Your Content Delivery API access token
- CONTENTFUL_SPACE_ID --> Your Space ID
Preview Variables
- CONTENTFUL_PREVIEW_ACCESS_TOKEN --> Your Content Preview API access token
- CONTENTFUL_HOST --> preview.contentful.com
- CONTENTFUL_SPACE_ID --> Your Space ID

If you're wondering how I figured that out, I found this piece of documentation which outlines what you need.

After you've filled in all the variables, click Save. Then click Build site. The build can take a couple of minutes, so you will have to wait! But, it should build successfully and now our site is deployed to Gatsby Cloud for all the world to see!

Testing the Workflow

Before we continue, let's take just a moment to test / make sure our workflow can do 2 things. Whenever we either

Push code to GitHub
Make a change in Contentful

Gatsby Cloud should automatically rebuild the site. But, we haven't setup any webhooks? How will Gatsby Cloud know when to rebuild?

Wrong! That was actually done automatically for us when we added the site to Gatsby cloud. In fact, if you go to your Contentful space, then go Settings, and then Webhooks, you should see one there!

If you do not, no worries! The documentation I linked above also includes the steps for configuring webhooks. So, just follow the steps and you'll be good to go.

Simple Code Change

In VS Code, go to /src/components/article-preview.js. Find this piece of JSX:

<h2 className={styles.title}>{post.title}</h2>

We'll make a very simple change, such as adding on a few exclamation points:

<h2 className={styles.title}>{post.title}!!</h2>

Next, commit / push the change:

git add . && git commit -m 'quick commit for testing workflow' && git push -u origin main

Go to your Gatsby Dashboard. This should've triggered a rebuild of the site (you might need to just refresh the page so that it is).

Simple Contentful Change

As mentioned previously, the setup script we ran earlier created some starter content models and content for us, so we will make a simple change to the Person content John Doe.

Go to your Contentful Space, then go to the Content tab, and click on the John Doe piece of content. Make a simple change, such as changing the name to your name, then click Publish Changes.

Go to your Gatsby Dashboard. This should've triggered a rebuild of the site (you might need to just refresh the page so that it is).

The build time for this (at least in my experience) is typically VERY quick, only 3 - 5 seconds! Although, if you are changing/adding in a LOT of content, it will likely take longer.

So, at this point, we have confirmed whenever we either:

Commit / push code to GitHub
Make a change in Contentful

Gatsby Cloud will automatically trigger a re-build of the site, keeping it up-to-date at all times!

Starter Cleanup

As is typically the case with starters/boilerplates, there are some things we don't need to keep around.

Removing Unnecessary Files & Folders

First, let's remove some of the files & folders at the root level of the project. After some testing, here is a list of the files folders we can & cannot delete post-setup:

✓ --> CAN be removed
✕ --> CANNOT be removed

[✓] .cache --> Can be deleted, but is regenerated each time you rebuild, and is ignored by git anyways
[✓] /bin & related package.json scripts --> Used for running npm run dev to setup Contentful
[✓] /contentful --> Used for running npm run dev to setup Contentful
[✓] /node_modules --> Can be deleted, but is regenerated each time you install packages, and is ignored by git anyways
[✓] /public --> Can be deleted, but is regenerated each time you rebuild, and is ignored by git anyways
[✕] /src --> Essential
[✕] /static --> Used to house files like robots.txt and favicon
[✓] _config.yml --> Used for GitHub pages and we're using Gatsby Cloud
[✕] .babelrc --> Babel config file
[✓] .contentful.json.sample --> Sample Contentful data file
[✕] .gitignore --> Used to intentionally ignore/not track specific files/folders
[✕] .npmrc --> configuration file for NPM, defines the settings on how NPM should behave when running commands
[✕] .nvmrc --> specify which Node version the project should use
[✓] .prettierrc --> Config for Prettier. This is entirely subjective, so it is up to you if you wish to delete it or not. I use Prettier settings in VS Code
[✓] .travis.yml --> Config file for Travis CI. Travis CI is a hosted continuous integration service
[✓] app.json --> Unsure what this is used for, as it is not used anywhere in the project
[✕] gatsby-config.js --> Essential
[✕] gatsby-node.js --> Essential
[✕] LICENSE --> Okay to leave
[✓] package-lock.json --> can be deleted, but is regenerated each time you install packages
[✕] package.json --> Essential
[✕] README.md --> Essential
[✓] screenshot.png --> Was used in the README, but is no longer needed
[✓] static.json --> Unsure what this is used for, as it is not used anywhere in the project. Possibly used for Heroku
[✓] WHATS-NEXT.md --> Simple markdown file

You can use this command to remove all the files with a ✓ next to them at once:

rm -rf bin contentful _config.yml .contentful.json.sample .prettierrc .travis.yml app.json package-lock.json screenshot.png static.json WHATS-NEXT.md

Let's commit this progress:

git add . && git commit -m 'removed unnecessary files and folders' && git push -u origin main

Updating NPM Scripts

Next, we'll quickly update our scripts in package.json.

First, let's add the gatsby clean script back in (I've found most starters remove it):

"clean": "gatsby clean"

Next, update the dev command to be:

"dev": "npm run clean && gatsby develop"

This is really handy as it'll delete the .cache and public folders each time we start up the development server, which gives us the latest changes from Contentful. If you don't want this, you can simply add on another script:

"start": "gatsby develop"

But this is not necessary, and you'll see why later.

I've also found this utility script I created for myself a while ago has really come in handy:

"troubleshoot": "rm -rf .cache node_modules public package-lock.json && npm i && npm run dev"

This is basically a hard reset of the project.

Let's commit this progress:

git add . && git commit -m 'updated package.json scripts' && git push -u origin main

At this point, I personally encountered a git error along the lines of:

Fatal unable to access, could not resolve host when trying to commit changes.

If this happens, it's likely a proxy issue. Simply run this command and it should fix the problem:

git config --global --unset http.proxy && git config --global --unset https.proxy

Components & Pages

Somewhat frustratingly, the starter uses a mix of Classes and Functions for components & pages. Let's convert all the files using classes to use the function syntax. Specifically, the function expression syntax. This makes it easier when we convert the files to TypeScript later when everything is consistent.

The files we need to adjust are:

src/components/layout.js
src/pages/blog.js
src/pages/index.js
src/templates/blog-post.js

Furthermore, all the component files use kebab-case for naming. Personally, I prefer to use PascalCase, as I am used to in other React projects. So, I will update all file names to use PascalCase instead. I understand that they are likely all kebab-case to be consistent with the naming of the pages and templates, so this just a personal preference.

As a quick reminder, when working with Gatsby, it is very important that you DO NOT rename page files to use PascalCase. Gatsby uses the file name for routing, so if you change blog.js to Blog.js, the route will no longer be /blog, but /Blog.

Lastly, I will group each component and it's CSS module file together in a folder to keep things organized. The file/folder structure will now be:

/components
  /ArticlePreview
    - index.js
    - article-preview.module.css
  /Container
    - index.js
  /Footer
    - index.js
    - footer.module.css
  etc.

Again, this is just my personal approach that I've always used. Totally up to you how you want to organize things.

Later on when we set up Styled Components, we will replace each module.css file with a styles.ts file. This styles.ts file will house any styled components used only by the functional component in the same folder. So, the structure then will be:

/components
  /ArticlePreview
    - index.tsx
    - styles.ts
  /Container
    - index.tsx
  /Footer
    - index.tsx
    - styles.ts
  etc.

So, I will not bother renaming the CSS module files since they will be replaced anyways.

If you wish to convert these on your own, by all means please do! Below I've provided the code you will need. You can check out the repo which I linked to earlier again here if you wish, but keep in mind since they're all in TypeScript and we have converted them over yet.

layout.js:

const Layout = ({ children, location }) => {
  return (
    <>
      <Seo />
      <Navigation />
      <main>{children}</main>
      <Footer />
    </>
  );
};

export default Layout;

blog.js:

const BlogIndex = ({ data, location }) => {
  const posts = data.allContentfulBlogPost.nodes;

  return (
    <Layout location={location}>
    <Seo title='Blog' />
    <Hero title='Blog' />
    <ArticlePreview posts={posts} />
    </Layout>
  );
};

export default BlogIndex;

With Gatsby, pages access the data returned from the GraphQL query via props.data. We can tidy up the code a bit by destructuring our props in the ( ). We will use this approach for the remaining files.

index.js:

const Home = ({ data, location }) => {
  const posts = data.allContentfulBlogPost.nodes;
  const [author] = data.allContentfulPerson.nodes;

  return (
    <Layout location={location}>
      <Hero
        image={author.heroImage.gatsbyImageData}
        title={author.name}
        content={author.shortBio.shortBio}
      />
      <ArticlePreview posts={posts} />
    </Layout>
  );
};

export default Home;

blog-post.js:

const BlogPostTemplate = ({ data, location }) => {
  const post = data.contentfulBlogPost;
  const previous = data.previous;
  const next = data.next;

  return (
    <Layout location={location}>
    <Seo
      title={post.title}
      description={post.description.childMarkdownRemark.excerpt}
      image={`http:${post.heroImage.resize.src}`}
    />
    <Hero
      image={post.heroImage?.gatsbyImageData}
      title={post.title}
      content={post.description?.childMarkdownRemark?.excerpt}
    />
    <div className={styles.container}>
      <span className={styles.meta}>
      {post.author?.name} &middot; <time dateTime={post.rawDate}>{post.publishDate}</time> –{' '}                  
      {post.body?.childMarkdownRemark?.timeToRead} minute read
      </span>

      <div className={styles.article}>
        <div className={styles.body} dangerouslySetInnerHTML={{ __html: post.body?.childMarkdownRemark?.html }} />

        <Tags tags={post.tags} />

        {(previous || next) && (
          <nav>
            <ul className={styles.articleNavigation}>
              {previous && (
                <li>
                  <Link to={`/blog/${previous.slug}`} rel='prev'>                                            
                    ← {previous.title}                                 
                  </Link>
                </li>
              )}
              {next && (                                     
                <li>
                  <Link to={`/blog/${next.slug}`} rel='next'>
                    {next.title} →
                  </Link>
                </li>
              )}
            </ul>
          </nav>
        )}
       </div>
      </div>
    </Layout>
  );
};

Let's commit this progress:

git add . && git commit -m 'updated components and pages to use function syntax' && git push -u origin main

Uninstalling Some NPM Packages

At this point, we are no longer using the following packages:

contentful-import
gh-pages
lodash
netlify-cli

We can uninstall them all by running:

npm un contentful-import gh-pages lodash netlify-cli

We can also simplify our scripts in package.json to:

"scripts": {
  "build": "gatsby build",
  "clean": "gatsby clean",
  "dev": "gatsby develop",
  "rebuild": "rm -rf .cache public && npm run dev",
  "serve": "gatsby serve",
  "troubleshoot": "rm -rf .cache node_modules public package-lock.json && npm i && npm run dev"
}

Let's commit this progress:

git add . && git commit -m 'uninstalled some npm packages and updated package.json scripts' && git push -u origin main

Organizing Components Into Folders

First, go into the components folder: cd src/components/

We need to create all the necessary folders for each component:

ArticlePreview
Container
Footer
Hero
Layout
Navigation
Seo
Tags

We can create all these folders at once by running the command:

mkdir ArticlePreview Container Footer Hero Layout Navigation Seo Tags

Now, one at a time, move the corresponding files into their folders. Hopefully VS Code automatically updates the import path(s) for you. If not, you will have to manually update them yourself.

After moving everything around, you should see the following warning:

warn chunk commons [mini-css-extract-plugin]

This error/warning is caused by the Webpack plugin mini-css-extract-plugin wanting all CSS imports to be in the same order. This is because it has confused CSS modules with plain CSS. However, since we will be using Styled Components, we can ignore this warning and continue.

Let's commit this progress:

git add . && git commit -m 'organized components into folders' && git push -u origin main

Converting to TypeScript

UPDATE: As of Gatsby v4.8, there is full TypeScript for the gatsby-browser and gatsby-ssr files. Also, as of Gatsby v4.9, there is full TypeScript for the gatsby-config and gatsby-node files! So, if you are able to use those versions, check out the 2 links on how to best setup those files!

Now comes a BIG step: converting everything to TypeScript! We will convert all components, pages, and even the Gatsby API files (gatsby-config, gatsby-node, etc.) at the root level to use TypeScript.

For this portion, I want to give a huge thanks to Progressive Dev on YouTube. His video was immensely helpful when I first wanted to work with Gatsby and TypeScript.

Gatsby claims to support TypeScript out of the box.and this is partially true. If we create a simple Copy component Copy.tsx:

const Copy = () => (
  <p>Lorem ipsum dolor sit amet consectetur.</p>
);

And use it in ArticlePreview above the tags, for example, it will work just fine. However, we don't get 100% proper type checking. VS Code will highlight the error, but the Gatsby CLI will not.

The other rather annoying thing to do is we have to manually convert all the .js/.jsx files to .ts/.tsx files as Gatsby does not have TypeScript versions of their starters.

Here is a summary of the steps we will take:

Setup tsconfig.json
Convert all the components & pages to TypeScript
Convert the Gatsby API files to use TypeScript

Setup

To start things off, let's install the TypeScript package:

npm i typescript

Also install the following @types packages:

npm i @types/node @types/react @types/react-dom @types/react-helmet

Next, create a tsconfig file:

tsc --init

Select everything in tsconfig.json, and replace it with this:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "jsx": "react",
    "module": "commonjs",
    "noEmit": true,
    "pretty": true,
    "skipLibCheck": true,
    "strict": true,
    "target": "es5"
  },
  "include": ["./src", "gatsby"],
  "exclude": ["./node_modules", "./public", "./.cache"]
}

You can always add on more, but this will suffice for now.

Next, we need a way to run our local development server, AND get proper type checking in the CLI. For this, we can use the package concurrently:

npm i concurrently

concurrently will allow us to run multiple scripts, well, concurrently! Next, let's update our scripts in package.json to use concurrently:

"dev-gatsby": "gatsby develop",
"dev-typescript": "tsc -w",
"dev": "npm run clean && concurrently \"npm:dev-gatsby\" \"npm:dev-typescript\""

At this point, we should run npm run dev to start up the local dev server and make sure everything is still working fine.

Converting Pages

Now, we can convert the .js files to .tsx files. Let's start with the Home Page. I will walk you through the process once, and leave it up to you to repeat the process for the other pages/templates.

To start, rename the file from index.js to index.tsx. When you do that though, TypeScript will complain about a few things:

It's not sure what the types of the components are that we are using. That is because they are still plain .js files, and we will convert them to .tsx in a bit anyways, so no worries there
The props data & location have the any type implicitly
The types for allContentfulBlogPost & allContentfulPerson are also unknown
A type error for the CSS Modules. Again, since we are replacing them with Styled Components later on, no worries here either

Luckily, Gatsby has types for us, and the one we need to use for pages is PageProps. So, import it:

import type { PageProps } from 'gatsby'

You'll notice here that I specifically put import type at the beginning. I do this because while this:

import { PageProps } from 'gatsby'

Is perfectly fine and will work without issue, I think it's a bit misleading. When I see that, my initial reaction is that PageProps is a component. But it is not, it is a type. This syntax for importing types also works:

import { type PageProps } from 'gatsby'

But I prefer the way I initially did it because if we import multiple types like this, for example:

import { type PageProps, type AnotherType, type YetAnotherType } from 'gatsby'

It looks kind of messy. We can simplify it by having the single type in front of the curly braces. Also, using { type PageProps } is a newer syntax, and might not work with older versions of React (say an old create-react-app you have, or something like that).

So, the syntax type { PageProps } then is the better choice because:

We only use the type keyword once, making the code a bit cleaner
It can be used with older and current React + TypeScript projects

Alright, back to the page! We can then set the type of our destructured props to PageProps:

const Home = ({ data, location }: PageProps) => {
  // ...
};

Next, outside the function body, just above, create a new type called GraphQLResult:

type GraphQLResult = {};

const Home = ({ data, location }: PageProps) => {
  // ...
};

Inside this object, we need to set the types for the GraphQL data being returned.

Now would be a good time to create a types folder, and inside it a file called types.ts.

types.ts will house our re-usable types throughout the project. I typically use just the one file, but you can certainly separate types for specific things into their own files if you wish. For example:

/types/global.ts
/types/graphql.ts

At the top, import the following:

import type { IGatsbyImageData } from 'gatsby-plugin-image';

We will use this type multiple times in this file alone, and I know from experience that we would get type errors where we use the GatsbyImage component if we didn't.

In types.ts, add the following:

export type BlogPost = {
  title: string;
  slug: string;
  publishDate: string;
  tags: string[];
  heroImage: {
    gatsbyImageData: IGatsbyImageData;
  };
  description: {
    childMarkdownRemark: {
      html: string;
    };
  };
};

export type Person = {
  name: string;
  shortBio: {
    shortBio: string;
  };
  title: string;
  heroImage: {
    gatsbyImageData: IGatsbyImageData;
  };
};

Back in index.tsx, adjust the GraphQLResult type we created to:

type GraphQLResult = {
  allContentfulBlogPost: {
    nodes: BlogPost[];
  };
  allContentfulPerson: {
    nodes: Person[];
  };
};

Make sure to import these types too, of course. Now, we can pass this type in as an additional argument to PageProps:

const Home = ({ data, location }: PageProps<GraphQLResult>) => {
  // ...
};

And now the type errors for the Contentful data should be gone!

You should be able to repeat this process for blog.js without issue. blog.js, or rather blog.tsx, will use the BlogPost type as well.

If you are stuck, you can always take a look at the final code here.

For converting blog-post.js to blog-post.tsx, there are a couple of extra steps. After renaming it to .tsx, you will get an error saying Module not found.

This is because in gatsby-node.js, there is this line:

const blogPost = path.resolve('./src/templates/blog-post.js');

Simply change it to .tsx at the end there. Then, in types.ts, add the following:

export type SingleBlogPost = {
  author: {
    name: string;
  };
  body: {
    childMarkdownRemark: {
      html: string;
      timeToRead: number;
    };
  };
  description: {
    childMarkdownRemark: {
      excerpt: string;
    };
  };
  heroImage: {
    gatsbyImageData: IGatsbyImageData;
    resize: {
      src: string;
    };
  };
  publishDate: string;
  rawDate: string;
  slug: string;
  tags: string[];
  title: string;
};

export type NextPrevious = { slug: string; title: string } | null;

Back in the blog-post.tsx, adjust the GraphQLResult type to:

type GraphQLResult = {
  contentfulBlogPost: SingleBlogPost;
  next: NextPrevious;
  previous: NextPrevious;
};

Then pass it to PageProps like before:

const BlogPostTemplate = ({ data, location }: PageProps<GraphQLResult>) => {
  // ...
};

And with that, all our pages are now using TypeScript! Let's commit this progress:

git add . && git commit -m 'updated pages to use typescript' && git push -u origin main

Converting Components

Now let's update the components to .tsx! The steps for this process are much simpler than with converting pages:

Rename .js to .tsx
Setup type for the props (if any)

For example, ArticlePreview:

// props
type ArticlePreviewProps = {
  posts: BlogPost[];
};

const ArticlePreview = ({ posts }: ArticlePreviewProps) => {
  // ...
};

Again, if you are having trouble/unsure how to type the pre-existing components, you can see how I did so here.

After converting all components to TypeScript, let's commit this progress:

git add . && git commit -m 'updated components to use typescript' && git push -u origin main

Converting Gatsby API Files

Now we will convert the Gatsby API files (gatsby-config, gatsby-node, etc.) to use TypeScript. The advantage of this is if the project should grow, it will be nice to have everything type-checked. The other benefit of .ts files is that we can use the more modern import/export syntax instead of modules.export/require syntax.

The issue is, though, these files MUST be in .js for the Gatsby Runner to use them. So, how do we solve this problem?

To start, at the root level of the project, create a folder called gatsby.

Copy and paste gatsby-config.js & gatsby-node.js at the root level into this folder and rename them to .ts.

Next, we'll need the following packages:

dotenv --> Because we will get an ESLint error later on called import/no-extraneous-dependencies
gatsby-plugin-typescript --> Allows Gatsby to build TypeScript and TSX files
ts-node --> Will allow us to recognize the TS syntax called from the JS files

Run the command:

npm i dotenv gatsby-plugin-typescript ts-node

Go to gatsby-config.js at the root level, select everything and replace it with just these 2 lines:

require("ts-node").register();

module.exports = require("./gatsby/gatsby-config");

Now, the Gatsby runner will recognize our TypeScript files.

Note, gatsby-config.js at the root level MUST remain as .js. We will be able to switch gatsby-node to .ts though.

Go gatsby-config.ts in the gatsby folder, and replace this code:

require('dotenv').config({
  path: `.env.${process.env.NODE_ENV}`
});

With this code:

import dotenv from 'dotenv';

dotenv.config({ path: `.env.${process.env.NODE_ENV}` });

Also update the object with the plugins, etc., being exported at the bottom from this:

module.exports = {
  // ...
};

To this:

export default {
  // ...
};

Make sure to gatsby-plugin-typescript to the array of plugins!

Lastly, we need to update the contentfulConfig object to include this: host: process.env.CONTENTFUL_HOST. If we don't, we get an error down below in the if check because we try to access contentfulConfig.host, but host doesn't exist initially in this variable. So, contentfulConfig should look like this:

const contentfulConfig = {
  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN || process.env.CONTENTFUL_DELIVERY_TOKEN,
  host: process.env.CONTENTFUL_HOST,
  spaceId: process.env.CONTENTFUL_SPACE_ID
};

Now to update gatsby-node! As previously mentioned, for the gatsby-node.js file at the root level, we can actually rename it to .ts. Once you do, select everything and replace it with just this one line:

export * from "./gatsby/gatsby-node";

You will get an error saying something like this file is not a module. We just need to update the file to use the import/export syntax.

Open gatsby-node.ts in the gatsby folder, and replace this:

const path = require('path');

With this:

import { resolve } from 'path';

Next, import the following type from the gatsby package:

import type { GatsbyNode } from 'gatsby';

Next, update the createPages to this:

export const createPages: GatsbyNode["createPages"] = async ({ graphql, actions, reporter }) => {
  // ...
};

At this point, we should see a type error down below for const posts = result... saying:

Property 'allContentfulBlogPost' does not exist on type 'unknown'

We need to set up the type for the result from the GraphQL query. Just outside & above the createPages function, create a type called GraphQLResult. It will look like this:

type GraphQLResult = {
  allContentfulBlogPost: {
    nodes: {
      slug: string;
      title: string;
    }[];
  };
};

Next, simply apply this type to the result variable and the error should go away:

const result = await graphql<GraphQLResult>(
  // ...
);

And now another error should appear on result.data saying: Object is possibly 'undefined'. Just above this line, add the following if check and the error should go away:

if (!result.data) {
  throw new Error('Failed to get posts.');
}

Whew! That was a lot! But now our entire Gatsby project is set up to use TypeScript!

Let's commit this progress:

git add . && git commit -m 'updated gatsby api files to use typescript' && git push -u origin main

ESLint Setup

Let's add ESLint to our project for some sweet-sweet linting!

To start, run the command: npx eslint --init

Answer the questions how you like, but make sure that whichever answers you choose, you make sure to pick the same ones each time you set up ESLint. This way, you can save any custom rules in a separate repo, like I've done here, and copy and paste them in. Now, your code will be consistent across all your projects.

This is how I answer the questions:

How would you like to use ESLint? · style
What type of modules does your project use? · esm
Which framework does your project use? · react
Does your project use TypeScript? · Yes
Where does your code run? · browser, node
How would you like to define a style for your project? · guide
Which style guide do you want to follow? · airbnb
What format do you want your config file to be in? · JSON

Download any additional packages if prompted. Once done, add in your custom rules if you have any, or you can add them as you go. Then commit this progress:

git add . && git commit -m 'added eslint' && git push -u origin main

Styled Components Setup

My go-to approach for styling React projects is Styled Components. At first, I didn't really like it. I was used to Sass for styling, and the syntax was weird at first, but after having used it in a few projects, I absolutely love it, and I haven't looked back since.

We'll need the following packages:

react-is --> Because if we don't, we get an error on Gatsby Cloud saying: Can't resolve 'react-is' ...
babel-plugin-styled-components, gatsby-plugin-styled-components, & styled-components --> These are the packages recommended by Gatsby themselves in their documentation
@types/styled-components --> Needed since styled-components don't come with types out of the box

Run the command:

npm i babel-plugin-styled-components gatsby-plugin-styled-components react-is styled-components @types/styled-components

Open gatsby-config.ts in the gatsby folder and add gatsby-plugin-styled-components to our plugins array.

Simple Component Change

Let's make a simple adjustment to the ArticlePreview component to make sure everything will work.

In the ArticlePreview folder, create a file called: styles.ts

Import styled-components:

import styled from 'styled-components';

Open up the CSS modules file. Let's convert the .article-list selector to a styled component. Copy and paste this into styles.ts:

export const ArticleList = styled.ul`
  display: grid;
  grid-gap: 48px;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  list-style: none;
  margin: 0;
  padding: 0;
`;

Back in index.tsx, add the following import:

import * as S from './styles';

I'll explain why I import it this way in just a bit. In the JSX, replace this:

<ul className={styles.articleList}>
  // ...
</ul>

With this:

<S.ArticleList>
  // ...
</S.ArticleList>

And if we check the Elements Tab in DevTools, we should see something like:

<ul class="styles__ArticleList-bfmZnV jUEOQo">
  // ...
</ul>

Of course, the randomly generated class names will be different from what you see here.

So, the reason why I use import * as S from './styles';, along with named exports from styles.ts, is because it very easily allows me to differentiate styled components from functional components in the JSX. The S is just for for Styled/. So, you could use import * as Styled instead if you would like.

Adding Global Styles

Now, let's add some global styles to the project. For that we will need 2 things:

GlobalStyle component
theme object

First, let's create the GlobalStyle component. Inside the src folder, create a new folder called styles. In this folder, create a file called GlobalStyle.ts. In this file, import createGlobalStyle:

import { createGlobalStyle } from "styled-components";

Next add this starting code:

const GlobalStyle = createGlobalStyle``;

export default GlobalStyle;

Inside the backticks is where you can place the global styles you want applied. Let's copy and paste some from global.css into there and make the necessary adjustments:

const GlobalStyle = createGlobalStyle`
  html {
    scroll-behavior: smooth;
  }

  html * {
    box-sizing: border-box;
  }

  body {
    background: #fff;
    color: #000;
    font-family: 'Inter var', -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
    font-size: 16px;
    font-weight: 400;
    line-height: 1.5;
    margin: 0;
    text-rendering: optimizeLegibility;
    -webkit-font-smoothing: antialiased;
  }
`;

Next, let's create the global theme object. Inside the styles folder, create a new file called theme.ts, and add this code to start:

const theme = {
  mediaQueries: {
    desktopHD: 'only screen and (max-width: 1920px)',
    desktopMedium: 'only screen and (max-width: 1680px)',
    desktopSmall: 'only screen and (max-width: 1440px)',
    laptop: 'only screen and (max-width: 1366px)',
    laptopSmall: 'only screen and (max-width: 1280px)',
    tabletLandscape: 'only screen and (max-width: 1024px)',
    tabletMedium: 'only screen and (max-width: 900px)',
    tabletPortrait: 'only screen and (max-width: 768px)',
    mobileXLarge: 'only screen and (max-width: 640px)',
    mobileLarge: 'only screen and (max-width: 576px)',
    mobileMedium: 'only screen and (max-width: 480px)',
    mobileSmall: 'only screen and (max-width: 415px)',
    mobileXSmall: 'only screen and (max-width: 375px)',
    mobileTiny: 'only screen and (max-width: 325px)'
  },
  colors: {
    red: 'red'
  }
};

export default theme;

Now, let's use both of them. To do so, open the Layout component file (src/components/Layout/index.tsx). In there, import both of these files, along with ThemeProvider from styled-components:

import { ThemeProvider } from "styled-components";
import GlobalStyle from '../../styles/GlobalStyle';
import theme from '../../styles/theme';

To use GlobalStyle, use it as a component and place it above the Seo component (at the same level). To use ThemeProvider, replace the fragment with it. At this point, you should get a red underline. This is because the ThemeProvider component expects a theme prop. So, we can pass in our theme object as the value. In the end, the JSX should look like this:

const Layout = ({ children, location }: LayoutProps) => (
  <ThemeProvider theme={theme}>
    <GlobalStyle />
    <Seo title='Gatsby Contentful Blog w/ TypeScript' />
    <Navigation />
    <main className='test'>{children}</main>
    <Footer />
  </ThemeProvider>
);

If you've never used Styled Components before, you might be asking "What does ThemeProvider allow us to do?"

When using Styled Components, we automatically get access to props, as well as children, and we can tap into our theme by doing props.theme. Let's see an example.

In the components folder, create a new folder called UI. In this folder I like to store very simple styled components that ONLY affect the UI, such as a Wrapper component, or Copy component like I showed in an example earlier (of course in this instance it would be purely for styling copy throughout the site), and they can be re-used throughout the project. Think of them like global UI components.

In this starter, a few elements use a container class. So, let's create a simple styled component that we can use to wrap JSX elements with.

In the UI folder, create a file called Container.ts. Since this is a simple styled component, and no JSX is involved, we name it .ts.

In the file, add this code:

import styled from 'styled-components';

export const Container = styled.div`
  margin: 0 auto;
  max-width: 80rem;
  padding: 24px;
`;

Next, let's go to ArticlePreview/index.tsx. We can see the starter already has a Container component, buuuttt I think the code there is pretty janky, and it's only meant for styling anyways. So, let's replace it with our styled component.

First, let's update our imports:

import * as S from './styles';
import { Container } from '../UI/Container';

Then simply remove the functional component Container being imported to avoid conflicts. Since the name is the same, it will work just like before.

I like to have my styled components imported and exported this way, because I have set rules for myself that:

Styled components should be named exports
Functional components should be default exports
Import everything as S from styles.ts in the component folder
Import components from the UI folder below it in alphabetical order

I would highly encourage you to create rules like this for yourself. You should do this because then your code will be consistent across all your projects, and when you use the same structure and self-imposed rules, it makes sharing code between your projects a LOT easier. Try new things out here and there, but once you've found what works for you, I would then encourage you to refactor all your existing projects (on your portfolio or not), to use these rules. Think of all the green squares you'll have on GitHub!! But in all seriousness, it shows you care about the quality of your code, which I think is important. And honestly having everything be consistent is just so satisfying.

Ok, now let's use our theme in the Container. You may have noticed there is a red color:

colors: {
  red: 'red'
}

This is just the default red, and it looks terrible, but at least we will know it's working! Simply add this to the styled component:

background-color: ${(props) => props.theme.colors.red};

Now the ArticlePreview component should be wrapped in a glorious red color!

Once you start using styled components, you may notice writing props.theme a lot is kind of annoying. Just like with functional components, we can destructure our props inline. So, we can update the background-color to be like this:

background-color: ${({ theme }) => theme.colors.red};

This is optional, but I like doing it this way as I think it's a bit cleaner.

Similarly to functional components, we can set up our own custom props for our styled components and type them as well. For example, let's say we want to have this Container component take in a dynamic backgroundColor prop, and that value be a string. How would we do that?

In Container.ts, just above the variable, create a new type ContainerProps, and add the following value:

type ContainerProps = {
  backgroundColor: string;
}

Next, we need to update the styled component to use this type. We can do so like this:

export const Container = styled.div<ContainerProps>`
  margin: 0 auto;
  max-width: 80rem;
  padding: 24px;
  background-color: ${({ theme }) => theme.colors.red};
`;

Now, we just need to update the component to use props.backgroundColor instead of props.theme:

export const Container = styled.div<ContainerProps>`
  margin: 0 auto;
  max-width: 80rem;
  padding: 24px;
  background-color: ${({ backgroundColor }) => backgroundColor};
`;

Now we can pass in a dynamic color to our Container each time we use it:

return (
  <Container backgroundColor='blue'>
    // ...
  </Container>
)

You can take this a step further and set the backgroundColor type to only accept certain values. For instance, the backgroundColor should only be red, green, or blue:

type ContainerProps = {
  backgroundColor: 'red' | 'green' | 'blue';
}

Now you should get some sweet auto-completion in VS Code when entering in a value for this prop!

Done!

At this point, we're done all the setup! Whew! That was a lot! Now, it is up to you to build out your project. Some things you can do from here:

Add custom fonts (Google Fonts, Adobe Typekit, etc.)
Add any more desired plugins and/or npm packages
Convert the remaining existing components using CSS modules to Styled components, or just delete them entirely and start from scratch
Update GlobalStyle and Theme to your liking

Happy coding!

DEV Community: Andrew Shearer

git commit -m is a lie! How to commit like a pro

Build an Express App Using Bun and Deploy It To Render With Docker

Links

Initial Setup

Comparison to Node

Deploying to Render using Docker

Setup Docker

Deploy to Render

Deploy a Full Stack Next.js App to a DigitalOcean VPS With Docker

Project Info

Setting Up PostgreSQL & DBeaver

Setup Next.js App

Setup GitHub Repo

Setup Drizzle

Migrate & Push

Setting Up Site Structure

Create a Form to Create a Note

Fetch and Display Notes

Deploy - Prerequisites

Docker and Docker Compose

DigitalOcean

Creating an SSH Key

Finish Droplet Setup

Test Droplet Connection

Create a PostgreSQL Database Cluster

Setup Dockerfile and docker-compose.yml

Finish DigitalOcean Postgres Setup

Import Local DB To DigitalOcean

Deploy to Droplet Using Docker Compose

Outro

How To Manage Access and Refresh Tokens for an API in Next.js 13 With Supabase and Prisma

Initial Setup

GitHub & Vercel

Getting API Access Token

Using the Access Token

Planning Out the App

Install and Setup Prisma

Setup PostgreSQL on Supabase

Create Prisma Model Schema

Install Prisma Client

Adding a Row in Supabase

Using Next.js middleware

Updating the Prisma Schema

Updating the middleware

Minor Adjustments

Outro

Integrate GitHub OAuth With NextAuth.js in Next.js 13 With Custom Sign In / Out Pages

Initial Setup

Auth Route Handler

NextAuth options

NEXTAUTH_SECRET

Setting up GitHub OAuth

Configuring Providers in options

Creating Pages

Send a GET request to /api/auth/providers

Apply NextAuth with Middleware

Custom Sign In / Out Pages

Adding Sign In / Out Functionality

Next.js Images from an OAuth Provider

Use Next.js 13 With TypeScript To Create a Headless Shopify App

Initial Setup

Store Setup

Shopify Products Setup

Shopify Storefront API Setup

Enable custom app development

Create and install a custom app

Select API scopes

Configure Environment Variables

Shopify GraphiQL App Setup

Displaying Simple Shopify Data

Getting and Display More Data

Creating Product Pages

Adding Global Nav & Footer

Single Product Page

Host on Vercel

Next Steps

I Used ChatGPT to Answer Questions on Stack Overflow

My Experience

Pros and Cons

Setup `Dockerfile` and `docker-compose.yml`

Using Next.js `middleware`

Updating the `middleware`

NextAuth `options`

`NEXTAUTH_SECRET`

Send a `GET` request to `/api/auth/providers`

Organize scripts in `package.json`

Organize `dependencies` in `package.json`