Forem: Jussi Nevavuori

How to Deploy Astro on Google Cloud with Bitbucket.

Jussi Nevavuori — Mon, 18 Sep 2023 09:41:37 +0000

Lighthouse score for improved SEO**

Note: This guide does not only apply to Astro but can be applied and adapted to suit any static site deployment needs for any SSG codebase.

Project repository

Project repository available here.

Requirements

The setup requires

Google Cloud
- Google Cloud Project (New or existing).
- Billing Account connected to the Project.
- Permissions to enable APIs, create load balancers, storage buckets etc.
Domain
- Access to DNS settings.
Bitbucket
- Access to repository settings.

This guide assumes

This guide assumes that you are using the main branch. In order to use the master branch, you might have to change main to master in many scripts.

This guide does not include

Partial redeployments: Using this guide, you rebuild and redeploy your entire site on all changes. Setup for a system which only redeploys changed pages is beyond the scope of this guide and often not required.
Staging or other preview deployments: Using this guide, you only get a main branch that automatically deploys to your live site. Staging and other preview deployments are beyond the scope of this guide.

This guide does not support

Server-side rendering or other server methods: This guide only applies to static sites and static site generation. In order to use server-side rendering or other server-side methods, you must deploy to a server using other available guides.

Step-by-step setup guide

1. Setup Google Cloud Project.

Create a new GCP project or use your existing GCP project.

Ensure that the project has an attached billing account.

2. Creating your Storage Bucket

Create a new bucket under Cloud Storage and name the bucket, for example astro. Use the following recommended options.

Setting	Recommended value
Name	Any name, e.g. `astro`
Location	Multi-region or other preffered
Storage class	Standard
Public access	*Do NOT* enforce public access prevention on bucket**
Access control	Uniform
Protection tools	None

2.1. Configuring your Storage Bucket to be public to everyone

Enable public access by adding a new permission to allUsers called Storage Object Viewer.

This can be done in your bucket under Permissions and Grant access by selecting allUsers as the principal and assigning the Storage Object Viewer role to that principal. No IAM condition is required. Then save and allow public access.

2.2. Customize Storage Bucket website configuration

Navigate to all buckets and under the overflow settings ("..." icon), select edit website configuration. Set the following options.

Setting	Recommended value
Entrypoint	`index.html`
Error page	`404.html`

3. Initial file upload

Build your project locally using npm run build, then upload the contents of your /dist folder (not the folder itself) to your storage bucket.

This is done so that you can test your site and that the automated pipelines gsutil rm step won't error when it tries to delete from an empty bucket. The upload will later be automated using the pipeline.

4. Enabling required APIs

Navigate to APIs and Services and enable the following APIs:

Compute Engine API
Certificate Manager API

5. Set up a Load balancer

Navigate to Load Balancing under Networking and create a new load balancer.

Select Application Load Balancer and Start Configuration.
Leave default options (From Internet to my VMs or serverless services and Global external Application Load Balancer) and create the load balancer.
Name your load balancer, e.g. astro-lb.

5.1. Configure the Load Balancer Frontend

Configure the load balancer frontend with the following options, including a static IP and a SSL certificate.

Setting	Recommended value
Name	Any name, e.g. `astro-lb-frontend`
Protocol	HTTPS (includes HTTP/2)
IP address	1. Create new IP address. 2. Name the IP address, for example `astro-lb-frontend-ip`. 3. Reserve the IP address.
Certificate	1. Create new certificate 2. Name the certificate, for example `astro-lb-certificate`. 3. Select Create Google-managed certificate. 4. Add your domain, for example `www.example.com`. 5. Create the certificate.
Port	`443`
IP version	`IPv4`
HTTP to HTTPS redirect	Enabled

5.2. Configure the Load Balancer Backend

Configure the load balancer backend. Start by under Backend services & backend buckets selecting Create a backend bucket. Then create the bucket with the following recommnended options.

Setting	Recommended value
Name	Any name, e.g. `astro-lb-backend-bucket` (Does not have to match the bucket name from before).
Cloud storage buckets	Browse and select your bucket from before.
Cloud CDN	Enabled
Cache options	Recommended to leave default options (Cache static content only).

5.3. Finalizing the Load Balancer

You can skip configuring routing rules and optionally go to review and finalize. Once done, click create.

5.4. Enabling compression

By default, your files are sent uncompressed. In order to further optimize and speed up your site, we enable compression. First, navigate to Cloud CDN under Network services. Select your backend bucket and edit.

Under cache performance, select Compression mode: Cutomatic and save.

6. Connect your domain to the Load Balancer

Open your created load balancer to find the load balancer's IP address. Then go to your domain's DNS settings. Create required A records to point to your load balancer's IP address. For example (given the example load balancer IP address 30.90.80.100).

NAME	TYPE	VALUE
`www`	`A`	`30.90.80.100`
`@`	`A`	`30.90.80.100`

7. Wait, up to 24 hours

Next you have to wait up to 24 hours for the SSL certificate to be signed and for DNS settings to propagate.

To inspect these settings, you can try:

dig to inspect your DNS settings and to ensure the A records have succesfully been set.
Navigating to your domain. If this works, the configuration should be ok. However, ensure HTTPS redirection works.
Navigating to your load balancer IP address. If this works, the configuration should be ok. However, ensure HTTPS redirection works.
curl -v to inspect that your load balancer works. It should provide you with redirects which you can follow using more curl -v invocations until you reach a text/html response.
In Google Cloud Console, navigate to Certificate Manager under Security. Select the Classic certificates tab and open your certificate to view its status.

8. Set up Bitbucket repository

Follow the Bitbucket instructions and create a new Bitbucket repository. Push your code onto a main branch with git (how to push code to remote repo with git).

8.1. Enable Bitbucket pipelines in your repository

To enable bitbucket pipelines in your repository, navigate to Repository settings and then Settings under Pipelines. Here you can enable pipelines. We will configure the bitbucket-pipelines.yml file later.

9. Set up Google Cloud for Bitbucket pipelines

The Bitbucket pipelines script will need access to Google Cloud. We do this by creating a service account for the pipeline as follows.

9.1. Creating a service account for Bitbucket pipelines

Navigate to IAM & Admin in Google Cloud Console, then to Service Accounts, then Create a service account using the following options.

Setting	Recommended value
Name	Any name, e.g. `Bitbucket Pipelines Service Account`
ID	Any ID, e.g. `bitbucket-pipelines`
Description	Optional

Then grant the service account the following roles:

Storage Admin to access and manage the files in Google Cloud Storage.
Compute Load Balancer Admin to access and manage the load balancer, e.g. invalidating the cache.

No users need access to the service account.

9.2. Creating a key for the service account

Select the created service account, then navigate to the Keys tab. Select Add key and Create a new key. Create a JSON key. This will download a new .json file, which is the service account key.

NOTE: Keep this key safe and private, do NOT upload it to any repository.

9.3. Base64 encoding the key

Bitbucket requires the key as a base64 encoded string. To encode the JSON file in base64, we use openssl (if not available on your platform, search online how to base64 encode files on your operating system). Run the following command in your terminal:

$ openssl base64 -A -in {path/to/key.json} -out {base64-key-file}

Now, the base64 encoded key is saved in the file defined as the base64-key-file.

9.4. Uploading the key and other repository variables to Bitbucket

Ensure you have enabled bitbucket pipelines in step 8.1. Open your Bitbucket repository, navigate to Repository settings and Repository variables under Pipelines. Add the Google Cloud Service Account key as a repository variable with the following settings. Also, add the other following variables

Name	Value	Secured
`GCLOUD_KEY`	The base64 encoded string †	✅ Recommended
`GCLOUD_PROJECT`	Your Google Cloud Project ID	Not required
`GCLOUD_BUCKET`	Your Google Cloud Bucket name	Not required
`GCLOUD_SOURCE`	`dist/**` or other ††	Not required
`GCLOUD_LOAD_BALANCER`	Your load balancer's name	Not required

† Can be found in the output file from step 9.3. Useful tip for copying a file to clipboard is to use

$ pbcopy < path/to/file

†† You can also use your custom build output folder. ** ensures the directory is not copied but its contents. See gsutil cp reference for more information.

Now your pipeline can access your google cloud account by using $GCLOUD_KEY, and other details about your Google Cloud deployment setup with the associated variables. Learn more about repository variables

10. Set up Bitbucket pipelines

Next we create a pipeline to automatically build and re-deploy the site to Google Cloud Storage on any changes to the main branch.

10.1. Creating the `.env.example` file

If you have a static site with no build step, you can skip this step.

Start by creating a .env.example file, which contains all your environment variables with placeholder values and optionally descriptions on their usage. This is used to detech which environment variables should be fetched from the deployment environment into the pipeline for building.

# Description about the usage of FOO
FOO="your-foo-value"

# Description about the usage of BAR
BAR="your-bar-value"

The file must end in a newline

10.2. Uploading environment variables into Bitbucket

If you have a static site with no build step, you can skip this step.

Upload all your environment variables into Bitbucket by navigating to Repository settings, then Deployments under Pipelines. If there doesn't already exist a Production deployment, create a new deployment named Production.

Open the Production deployment and add any environment variables required for your production build there. Secure them optionally. If you do not have any custom environment variables, leave the file empty.

10.3. Utility script for pulling environment variables into build

If you have a static site with no build step, you can skip this step.

Create a new folder in your project called pipeline-scripts. In there, create a new script file called create-dot-env.sh and copy the following script into that file.

#!/bin/sh

# Define input file to parse environment variable names from and output files
# where final values will be written.
INPUT_FILE=".env.example"
OUTPUT_FILE=".env"

# Use a while loop to read each line of the example file
while read line; do

  # Extract the variable name from the line
  VAR_NAME=$(echo "$line" | grep -o "^[A-Za-z_][A-Za-z0-9_]*")

  # Check if the variable name is not empty
  if [ -n "$VAR_NAME" ]; then

    # Get the value of the variable from the environment
    VAR_VALUE=$(echo "${!VAR_NAME}")

    # Write the variable and its value to the output file
    echo "${VAR_NAME}=${VAR_VALUE}" >> "$OUTPUT_FILE"

  fi

done < "$INPUT_FILE"

This script will find all environment variables defined in .env.example, copy their respective values from the deployment and populate a new .env file with those values to be used in the build.

10.4. Creating the pipeline

If you have a static site with no build step, modify the pipeline script by removing the installations and commands as instructed in the comments.

Copy the following bitbucket-pipelines.yml code to a file called bitbucket-pipelines.yml in your project. The file can also be found in this project's repository. It uses the repository variables from steps 9 and 10.

You can copy and paste this file as is, without customization.

image: "node:18"

# Run pipelines when code is merged (or pushed) onto the `main` branch or when
# the `branches: main` is otherwise triggered.
pipelines:
  branches:
    main:
      # This line might incorrectly show an error if you have automatic pipeline linting enabled in your editor.
      - stage:
          # Use environment variables from the "Production" deployment.
          deployment: Production
          name: Deploy to production
          steps:
            - step:
                # Use Google Cloud SDK image to access `gsutil` and `gcloud`.
                image: google/cloud-sdk:alpine
                name: Build and deploy app to Google Cloud Storage
                script:
                  # -------------------------------------------
                  # NOTE FOR STATIC WEBSITES WITHOUT BUILD STEP
                  # -------------------------------------------
                  # In order to deploy sites that do not have a build step,
                  # ensure your $GCLOUD_SOURCE is correctly set. In addition,
                  # you can remove `nodejs` and `npm` from the `apk add`
                  # command. Additionally, you can remove the
                  # `bash ./pipeline-scripts/create-dot-env.sh`,
                  # `npm install` and `npm run build` steps.

                  # Install `node` and `npm` (google/cloud-sdk does not come
                  # with node) and coreutils to support e.g. base64 --decode
                  # flag, which is by default not supported on alpine.
                  - apk add --update nodejs npm coreutils

                  # Export all environment variables and build a `.env` file
                  # for the build step. Requires a `.env.example` file.
                  - bash ./pipeline-scripts/create-dot-env.sh

                  # Decode base64 encoded service account key into key-file.json
                  # for use in gcloud tool
                  - echo $GCLOUD_KEY > base64-key-file
                  - base64 --decode base64-key-file > key-file.json

                  # Activate service account in gcloud and select currently active project
                  - gcloud auth activate-service-account --key-file key-file.json
                  - gcloud config set project $GCLOUD_PROJECT

                  # Install dependencies and build project
                  - npm install
                  - npm run build

                  # Delete all previous files and upload new built files to Google Cloud Storage
                  # https://cloud.google.com/storage/docs/gsutil/commands/rm
                  # NOTE: If the "gsutil rm" fails, upload any files to your gcloud bucket for it to delete.
                  - gsutil -m rm -a gs://$GCLOUD_BUCKET/**
                  - gsutil cp -r $GCLOUD_SOURCE gs://$GCLOUD_BUCKET/

                  # Invalidate cloud CDN cache (All paths with "/*")
                  - gcloud compute url-maps invalidate-cdn-cache $GCLOUD_LOAD_BALANCER --path "/*" --async

10.5. Applying the pipeline

Push your changes to Bitbucket and merge them to main. This will automatically register the pipeline. Navigate to pipelines and you should see your pipeline running. Ensure the pipeline runs correctly.

11. Deployment options

Your site is now live and can be deployed using bitbucket pipelines. However, in the next steps we are going to create more deployment options to ease deployment. All deployment options work by triggering the

The four deployment options we are going to have are

#	Name	Type	Usage
1	Automatically on code changes	Automatic	Redeploy on code changes.
2	Manually	Manual	Redeploy manually when content changes from Bitbucket console.
3	On a schedule	Automatic	Redeploy periodically on a schedule when content changes constantly.
4	Programmatically	Automatic	Automate deployments via any other needs programmatically, e.g. via a webhook on your CMS that listens to changes.

11.1. Deploy automatically on code changes

Already done and available. The bitbucket pipeline has already been setup during this guide and any code changes to the main branch will trigger a redeployment.

11.2. Deploy manually

Already done and available. The bitbucket pipeline has already been setup during this guide and can be deployed manually:

Navigate to your Bitbucket repository and select Pipelines.
Select Run pipeline in the top-right corner with the following options:
- Branch: main
- Pipeline: branches: main
Run the pipeline.

11.3. Deploy on a schedule

We use the Scheduled pipelines feature available in Bitbucket to automatically redeploy your site either hourly, daily or weekly.

Navigate to your Bitbucket repository and select Pipelines.
Select Schedules and create a New schedule with the following options:
- Branch: main
- Pipeline: branches: main
- Schedule: Configure as best suits your use case.
Create the schedule.
You can later manage the schedule by toggling it, editing it, removing it or adding new schedules.

If you need more complex schedules not supported by Bitbucket scheduled pipelines, look into 11.4. for programmatic deployment options that can be integrated with Google Cloud Scheduler to enable deployment on any Cron schedule.

11.4. Deploy programmatically

Next we are going to setup programmatic deployments. These can be used to create multiple customized deployment methods, such as

Webhooks, e.g. on every change in your CMS.
Cron jobs, e.g. with Google Cloud Scheduler when Bitbucket pipeline schedules are not enough.
A custom deploy button in a protected interface that can make a post request.
A custom deploy.sh deployment script to deploy from your terminal (included in repo).

11.4.1. Create repository access token

In your Bitbucket repository settings, go to Access tokens and Create Repository Access Token. Use the following settings:

Setting	Recommended value
Name	Any value, e.g. `pipeline-deployer`.
Scopes	At the least `Pipelines / Read` and `Pipelines / Write`.

Create the access token and copy the token (from now on referred to as $BITBUCKET_REPOSITORY_ACCESS_TOKEN) to a safe place, such as your .env file.

11.4.2. Formulating the API call

You can automatically trigger Bitbucket pipelines using the following curl command or any equivalent method, e.g. fetch() in Node.

Easiest way to access the $BITBUCKET_USERNAME and $BITBUCKET_REPOSITORY_SLUG variable values are in your Bitbucket repository URL (https://bitbucket.org/$BITBUCKET_USERNAME/$BITBUCKET_REPOSITORY_SLUG/).

Shell

curl -X POST -is \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $BITBUCKET_REPOSITORY_ACCESS_TOKEN" \
 https://api.bitbucket.org/2.0/repositories/$BITBUCKET_USERNAME/$BITBUCKET_REPOSITORY_SLUG/pipelines/ \
    -d '
    {
        "target": {
            "ref_type": "branch",
            "type": "pipeline_ref_target",
            "ref_name": "main"
        }
    }'

JavaScript

const BITBUCKET_USERNAME = "..."
const BITBUCKET_REPOSITORY_SLUG = "..."
const BITBUCKET_REPOSITORY_ACCESS_TOKEN = "..." // From process.env preferrably

await fetch(
    `https://api.bitbucket.org/2.0/repositories/${BITBUCKET_USERNAME}/${BITBUCKET_REPOSITORY_SLUG}/pipelines/`
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "Authorization": `Bearer ${BITBUCKET_REPOSITORY_ACCESS_TOKEN}`,
        },
        body: JSON.stringify({
            target: {
                ref_type: "branch",
                type: "pipeline_ref_target",
                ref_name: "main",
            }
        })
    }
);

References and troubleshooting

Below is a list of some of the references used for creating this documentation. Use these for further reference if you encounter more problems or want to further develop the deployment.

Rich text and images with Contentful, Next.js and Zod

Jussi Nevavuori — Thu, 18 Aug 2022 09:09:00 +0000

The previous article demonstrated how we can create models in our codebase for our existing Contentful models to fetch them and interact with them in a fully typesafe manner. We also hinted at how we’re going to work with images and rich text, and what the context object in the previous tutorial will do.

Read the previous article

In the previous article we explored creating the createContentfulModel function that provides a useful abstraction for working with Contentful models.

How to optimise and tweak Contentful images

In this article we’re going to explore how we can create a contentfulImage function which allows us to automatically fetch our images in optimised next-gen formats and more.

Setting up schemas for Contentful images and rich text

Contentful image fields are regular Contentful entries. We’ll create a schema for the fields of an image and the image entry itself using the contentfulEntrySchema we created in the previous article.

import { z } from "zod";
import { contentfulEntrySchema } from "./contentfulEntrySchema";

export const contentfulImageFieldsSchema = z.object({
  title: z.string(),
  description: z.string(),
  file: z.object({
    url: z.string(),
    details: z.object({
      size: z.number().positive().int(),
      image: z.object({
        width: z.number().positive().int(),
        height: z.number().positive().int(),
      }),
    }),
    fileName: z.string(),
    contentType: z.string(),
  }),
});

export const contentfulImageField = () =>
  contentfulEntrySchema.extend({
    fields: contentfulImageFieldsSchema,
  });

We’re also going to setup a type for our rich text fields. For now, we’re going to take a shortcut and simply use a typecast with a zod transform and not perform any actual data validation as the shape of Contentful rich text is very complicated.

import { z } from "zod";
import { RichTextContent } from "contentful";

export const contentfulRichTextField = () =>
  z.any().transform((x) => x as RichTextContent);

Providing all custom Contentful fields using the context object

Now is time to reveal what we were intending to do with the context object all along. (Note: the context object can be extended to do much more than only provide custom fields but we’re going to start with this).

The context object will contain a contentfulFields property which will in turn contain both the schemas we defined. The type of the context will be updated to the following.

export type CreateContentfulModelContext = {
  contentfulFields: {
    richText: typeof contentfulRichTextField;
    image: typeof contentfulImageField;
  };
};

Now, in our createContentfulModel we must create the context and provide in to the fieldsSchemaCreator function.

// ... more imports
import { contentfulImageField } from "./contentful-image-field";
import { contentfulRichTextField } from "./contentful-rich-text-field";

// ... types

export function createContentfulModel<TDataIn extends {}, TDataOut>(
    contentType: string,
    fieldsSchemaCreator: FieldsSchemaCreator<TDataIn, TDataOut>
) {

    // Set up context
    const context: CreateContentfulModelContext = {
    contentfulFields: {
      richText: contentfulRichTextField,
      image: contentfulImageField,
    },
  };

    // Provide context to fields schema creator
    const fieldsSchema = fieldsSchemaCreator(context);

    // ... Rest of the function
}

Now all fields schema creator functions have access to the newly created field types. Let’s next see how we can use them.

Using the image and rich text field types

Let’s update our example model to contain an image and rich text using the new fields from the context object.

import { z } from "zod";
import { createContentfulModel } from "./create-contentful-model";

export const exampleModel = createContentfulModel("example", (ctx) => z.object({
    title: z.string(),
    description: z.string().optional(),
    rating: z.number().int().positive(),
    body: ctx.contentfulFields.richText(),
    image: ctx.contentfulFields.image(),
}));

There. That’s all there is to it.

Consuming rich text and images

First let’s create a new rich text component that takes RichTextContent as a prop. For this we’re going to use @contentful/rich-text-react-renderer which you can install with

npm i @contentful/rich-text-react-renderer

The component is simple and shown below and simply uses the documentToReactComponents method wrapped in an <article>. However, customising any rich text can now be done in a single place.

import { documentToReactComponents } from "@contentful/rich-text-react-renderer";
import { RichTextContent } from "contentful"

export interface RichTextProps {
    content?: RichTextContent;
}

export function RichText(props: RichTextProps) {
    return <article>
        {documentToReactComponents(props.content as any)}
    </article>
}

Consuming images is simple as the image itself contains the URL of the file which can be directly used as the src for the image. Similarly it contains a title for the alt.

Let’s update our simple React application to render both the image and the rich text content.

<ul>
        {
            examples.map(example => (
                <li key={example.sys.id}>
                    <img
                        src={example.fields.image.fields.file.url}
                        alt={example.fields.image.fields.title}
                    />
                    <p>{example.fields.title}</p>
                    <p>{example.fields.description}</p>
                    <p>{example.fields.rating} / 5</p>
                    <RichText content={example.fields.body} />
                </li>
            ))
        }
    </ul>

Read this article to optimize and tweak your Contentful images. Replace your src={entry.fields.image.fields.file.url} with the improved src={contentfulImage(entry.fields.image, { format: "webp", quality: 60 })} for example using the methods or package described in the article or directly install contentful-image with

npm i contentful-image

That’s it.

Thank you for taking the time to read this article, hopefully it is of use to you!

How to optimise and customise your Contentful images with TypeScript

Jussi Nevavuori — Fri, 12 Aug 2022 14:16:30 +0000

ImageSrc function for Contentful images with TypeScript

All code provided as an npm package

npm install contentful-image

Or use code provided in the GitHub repo.

Using the Contentful npm package you can access an image stored in a content entry with the following snippet.

<image src={contentEntry.fields.yourImage.fields.file.url} />

However, this method does not support changing image formats, resizing, cropping and many more. This method only allows you to access the base unoptimised image you originally uploaded to Contentful.

But what if you wanted optimized images for your web applications in a modern way? That’s where the Contentful Images API comes to play!

The Contentful Images API allows you to

Change the image format (jpg, png, webp, gif, avif, progressive jpg, 8-bit png)
Resize to specified width and height
Resize with different behaviours (pad, fill, scale, crop, thumb)
Specify a focus area for resizing (a specific position or faces)
Crop rounded corners, circles and ellipsis
Change the quality of the image (between 1 - 100)
Change the background color

All of this is done by appending query parameters to the file url. Let’s see how we can create a contentfulImage function in TypeScript to help us access files and apply these parameters with less manual labour. Our target is to create an easier way to retrieve images with theses options, such as shown below

<image src={contentfulImage(contentEntry.fields.yourImage, {
    quality: 60,
  height: 400,
  format: "webp",
})} />

The TypeScript part: Creating types for the image API

First off let’s create an empty contentfulImage function. Our aim is to take as input a Contentful image and options and return a URL (with the appended query parameters) that can be used as is for example with a <image /> in the src.

function contentfulImage(
    src: ContentfulImageSource,
    options: ContentfulImageOptions = {}
): string {
    return "";
}

Let’s define the type of the ContentfulImageSource as a type that can accept an URL directly or any field (or subfield) in a Contentful image. It can then be used as either contentfulImage(contentEntry.myImageField) or by any subfield such as contentfulImafge(contentEntry.myImageField.fields.file.url).

export type ContentfulImageSource =
  | string
  | { url: string }
  | { file: { url: string } }
  | { fields: { file: { url: string } } };

Next, let’s create types for each option that can be defined via the Contentful Images API. In reality, we only read their API and convert all values from there into types as follows. In addition to this we also create a type for an object which contains all of these properties as optional properties with readable keys.

export type ContentfulImageOptionsFormat =
  | "jpg"
  | "png"
  | "webp"
  | "gif"
  | "avif"
  | "jpg/progressive"
  | "png/png8";
export type ContentfulImageOptionsFit =
  | "pad"
  | "fill"
  | "scale"
  | "crop"
  | "thumb";
export type ContentfulImageOptionsFocusArea =
  | "center"
  | "top"
  | "left"
  | "right"
  | "bottom"
  | "top_right"
  | "bottom_right"
  | "top_left"
  | "bottom_left"
  | "face"
  | "faces";
export type ContentfulImageOptionsHeight = number;
export type ContentfulImageOptionsWidth = number;
export type ContentfulImageOptionsRadius = number | "max";
export type ContentfulImageOptionsQuality = number;
export type ContentfulImageOptionsBackgroundColor = string;

export type ContentfulImageOptions = {
  format?: ContentfulImageOptionsFormat;
  width?: ContentfulImageOptionsWidth;
  height?: ContentfulImageOptionsHeight;
  fit?: ContentfulImageOptionsFit;
  focusArea?: ContentfulImageOptionsFocusArea;
  radius?: ContentfulImageOptionsRadius;
  quality?: ContentfulImageOptionsQuality;
  backgroundColor?: ContentfulImageOptionsBackgroundColor;
};

Getting the base URL from the src object

We write the following function to extract the URL from the given src object no matter how deeply nested it is in there with a ternary that could use some prettying up. We also prepend “https:” if necessary as it is not always provided by Contentful. In addition, if for any reason there is a query string appended to the url, we remove it.

export function getContentfulImageSrcUrl(src: ContentfulImageSource) {
  // Get provided raw URL string
  let url =
    typeof src === "string"
      ? src
      : "fields" in src
      ? src.fields.file.url
      : "file" in src
      ? src.file.url
      : src.url;

  // Prepend https: if necessary
  if (url.startsWith("//")) url = "https:" + url;

  // Remove query
  if (url.includes("?")) url = url.split("?")[0];

  return url;
}

The hard part: Converting the options object into a query string

We can not simply match each option to a query parameter and pass the value as is. We must have support for the following limitations:

Some options may be defined by more than one query parameter (such as 8-bit pngs which are retrieved with two options: fm=png and fl=png8.
We want to apply transformers to some properties before applying them to the query string, such as with background color. The query requires a value such as rgb:9090ff but we want to be able to provide simply 9090ff or #9090ff to our function.

We have already started to implement the first requirement. Our ContentfulImageOptionsFormat defines 8-bit pngs with the type png/png8 and progressive jpgs jpg/progressive. When split at /, these values match the exact values that should be provided to the two required query parameters, fm and fl in that order.

Let’s define a map of all properties that can be specified by the consumer of the API and a list of query parameters each option should define.

const optionQueryKeys: Record<keyof ContentfulImageOptions, string[]> = {
  backgroundColor: ["bg"],
  quality: ["q"],
  radius: ["r"],
  focusArea: ["f"],
  fit: ["fit"],
  height: ["h"],
  width: ["w"],
  format: ["fm", "fl"],
};

There. All other options define a single option, except for the image format. We’ll come back later on how we are to apply this data structure.

While we’re at it, let’s also create a map of transformers. These are functions that take in the value provided by the consumer after being stringified but before any other operations are done to it. For now, only background color will have a transformer that omits the “#” character and prepends the rgb: string required by the api.

const transformers: Partial<
  Record<keyof ContentfulImageOptions, (value: string) => string>
> = {
  backgroundColor: (value) => "rgb:" + value.replace("#", ""),
};

Let’s create a getContentfulImageQuery function which has one purpose. Take in a ContentfulImageOptions object and return a query string if any was constructed.

The function will proceed as follows:

For each entry specified in the options:
- Get list of query keys from the optionQueryKeys object for this option
- Convert values to string, apply transformer function if any exists and split to list of values at "/".
- Match each query key and value in their respective lists by index and if both have a value, append the query key and value to the query string.

A functional implementation of this is as follows.

export function getContentfulImageQuery(options: ContentfulImageOptions) {
  return Object.entries(options)
    .map(([key, value]) => {
      // Get list of all parameter names for current option
      const queryKeys = optionQueryKeys[key as keyof ContentfulImageOptions];

      // Get transformer for preprocessing before applying to query if exists.
      const transformer = transformers[key as keyof ContentfulImageOptions];

      // Convert value to string, apply transformer if exists and split
      // into list of values at "/".
      const values = (
        transformer ? transformer(value.toString()) : value.toString()
      ).split("/");

      // By index, match each parameter name and value to a "{name}={value}"
      // pair. If either the name or value for a pair is falsy, omit it.
      return queryKeys
        .map((name, i) => {
          if (!name || !values[i]) return "";
          return name + "=" + values[i];
        })
        .filter((_) => !!_); // Remove all empty values
    })
    .flat() // Flatten array
    .join("&"); // Join all {name}={value} pairs with "&" to a query string.
}

Combining the src and options

Now that we have getContentfulImageSrcUrl and getContentfulImageQuery, combining them into the final function is practically trivial.

export default function contentfulImage(
  src: ContentfulImageSource,
  options: ContentfulImageOptions = {}
) {
  // Get URL from src and query from options.
  const url = getContentfulImageSrcUrl(src);
  const query = getContentfulImageQuery(options);

  // Append query if one constructed
  return url + (query ? `?${query}` : "");
}

There you have it.

There. Now you can use contentfulImage() anywhere in your code. The links to the GitHub repo and npm package (and its installation instructions) are provided at the start of this article. Feel free to use them as you wish.

How to use Contentful with Next.js and Zod

Jussi Nevavuori — Mon, 01 Aug 2022 12:59:00 +0000

Using headless CMS’ with modern web technologies such as Next.js has long been a popular way to create websites and manage their content. In this article we’re going to explore a typesafe, easily extensible method of accessing your Contentful schemas.

The target of this article is to create an abstraction for each data model which allows for type safe querying. We call this abstraction createContentfulModel, which will take as input the schema for your content and provide you with typed and validated data.

Step 1 - Setup your Contentful workspace and client

In order to setup your Contentful workspace, go to contentful.com, sign up and set up your Contentful workspace. There you can first create your content models and then create content to suit those models.

Returning to the code side of things, we first create a new next project (with TypeScript) and install contentful with npm.

$ npx create-next-app@latest --ts
$ npm i contentful

We set up our Contentful client in contentful/client.ts according to the Contentful documentation.

import { createClient } from "contentful";

export const contentfulClient = createClient({
  space: process.env.NEXT_PUBLIC_CONTENTFUL_SPACE_ID!,
  accessToken: process.env.NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN!,
});

We must also provide the necessary environment variables to set up our client and to connect it to our Contentful workspace. In Contentful, under settings and API keys, create a new API key. We’re going to need its Space ID and Content Delivery API access token. Copy and paste the correct values into your .env.local file as shown below.

NEXT_PUBLIC_CONTENTFUL_SPACE_ID="your-space-id"
NEXT_PUBLIC_CONTENTFUL_ACCESS_TOKEN="your-access-token"

Step 2 - Set up Zod schemas for typesafety

First run npm i zod to install Zod, the arguably best type validation library available for TypeScript.

Before starting to set up the schemas and shapes for our content, we’re going to need Contentful specific types. All Contentful queries return object entries, which contain all content in the fields property, but also contain the metadata and sys properties which include useful metadata about the object, such as it’s ID and timestamps.

We’re first going to set up a contentfulEntrySchema in contentful/contentful-entry-schema.ts which will contain a Zod schema corresponding to an object entry with an empty fields property (which we will later extend).

import { z } from "zod";

export const contentfulEntrySchema = z.object({
  fields: z.object({}), // Extend this later
  metadata: z.object({
    tags: z.array(z.any()),
  }),
  sys: z.object({
    space: z.object({
      sys: z.object({
        type: z.string(),
        linkType: z.string(),
        id: z.string(),
      }),
    }),
    id: z.string(),
    type: z.string(),
    createdAt: z.string(),
    updatedAt: z.string(),
    environment: z.object({
      sys: z.object({
        id: z.string(),
        type: z.string(),
        linkType: z.string(),
      }),
    }),
    revision: z.number(),
    contentType: z
      .object({
        sys: z.object({
          type: z.string(),
          linkType: z.string(),
          id: z.string(),
        }),
      })
      .optional(),
    locale: z.string(),
  }),
});

This allows fully validating all data queried from Contentful and we can easily extend it to suit any content type by overriding the fields property.

Step 3 - Creating createContentfulModel

Now that we have most of our boilerplate set up, we’re going to start working on the createContentfulModel abstraction. Our objective is to create a function that takes as input

contentType, which defines which content we want to target in our Contentful workspace
fieldsSchemaCreator function, which returns a Zod schema for our content type and provides utilities for creating those schemas in a context object (more on it in the next article).

As output, we want the function to provide us an object with the following properties:

The schemas which were created using fieldsSchemaCreator
All data fetching functions (in this example we’re only going to implement getAll) to fetch all data without querying.

Let’s start creating the function in contentful/create-contentful-model.ts

// More in the next article on the create contentful model context
export type CreateContentfulModelContext = {};

export type FieldsSchemaCreator<TDataIn extends {}, TDataOut> = (
    context: CreateContentfulModelContext
) => z.Schema<TDataOut, z.ZodTypeDef, TDataIn>;

export function createContentfulModel<TDataIn extends {}, TDataOut>(
    contentType: string,
    fieldsSchemaCreator: FieldsSchemaCreator<TDataIn, TDataOut>
) {
    ...

    return { ... }
}

We want to be able to use this function as follows:

const exampleModel = createContentfulModel("example", (ctx) => z.object({
    title: z.string(),
    description: z.string().optional(),
    rating: z.number().int().positive(),
}));

exampleModel.getAll().then(examples => {...})

The fields schema creator should return a Zod object which represents the fields of the content type we want to access. Let’s start implementing it.

export function createContentfulModel<...>(...) {

    // Set up an empty context. We'll return to this in the next article.
    const context: CreateContentfulModelContext = {};

    // Run the fieldsSchemaCreator with the context to get the type of
    // the content's fields.
    const fieldsSchema = fieldsSchemaCreator(context);

    // Using the object entry schema we defined earlier, extend its fields
    // property to define this object type's full entry schema
    const entrySchema = contentfulEntrySchema.extend({ fields: fieldsSchema });

    // Return schemas
    return {
        fieldsSchema,
        entrySchema,
    }
}

We now have access to the full schemas. Next we need to create data fetcher functions, which will allow us to fetch data in all ways we need. Note: for this project we will only be implementing the getAll fetcher. Rest (getOneById, getAllWhere, and any others you might need) are left as an exercise to the reader. For small projects with only small amounts of data, especially with SSG getAll might be all you need.

export function createContentfulModel<...>(...) {
    // ...

    // Create the get all fetcher to fetch all items of the current
    // content type.
    const getAll = async () => {
        // Fetch all items of current content type
        const res = await contentfulClient.getEntries({ content_type: contentType });

        // Parse and validate all items using zod
        const parsed = z.array(entrySchema).safeParse(res.items);

        // Handle failures
        if (!parsed.success) {
            console.error(parsed.error);
            return [];
        }

        // Return validated data with correct types
        return parsed.data;
    }

    return {
        fieldsSchema,
        entrySchema,
        getAll,
    }
}

We can now use createContentfulModel to create typed, validated abstractions for each of our content types in our Contentful workspace.

Step 4 - Inferring the types

Let’s further utilise the magic of Zod. Instead of having to type out a type for each of our content models, we can simply infer the types from the schemas we already have. No more need for maintaining the representation of the content model in our code in two separate places. To easily infer the types, we’re going to create types/contentful.d.ts in our project. When using a .d.ts file with only inline imports, we don’t even need to import the types in our project where they are used, we only need to include contentful.d.ts in our tsconfig.json.

To help inferring the types, we’re going to create a utility type ExtractModelType which is provided any model created with createContentfulModel and it will return the type of the content entry.

// types/contentful.d.ts

// Get inner type of Array or Promise
type Inner<T> = T extends Array<infer U1>
  ? U1
  : T extends Promise<infer U2>
  ? U2
  : T;

// Helper type to extract a model's type from the model object
type ExtractModelType<
  Model extends ReturnType<
    typeof import("../contentful/create-contentful-model")["createContentfulModel"]
  >
> = Inner<Inner<ReturnType<Model["getAll"]>>>;

Next we’re going to create an example content model at /contentful/example-model.ts.

export const exampleModel = createContentfulModel("example", (ctx) => z.object({
    title: z.string(),
    description: z.string().optional(),
    rating: z.number().int().positive(),
}));

And infer it in types/contentful.d.ts as follows:

type ExampleModelEntry = ExtractModelType<
  typeof import("../contentful/example-model")["exampleModel"]
>;

type ExampleModelFields = ExampleModelEntry["fields"];

The ExampleModelEntry type represents the full object entry returned by the Contentful in the fetcher functions. It contains all metadata in the sys and metadata fields. The content is contained in the fields property and has the type of ExampleModelFields.

Step 5 - Consuming the models

After a lot of work to set up our Contentful models, we can now start consuming them in our applications. The work we did earlier starts now paying off, as consuming our types is as easy as doing the following getStaticProps (or any other place where you might fetch your data).

import type { GetStaticProps, InferGetStaticPropsType } from 'next'
import { exampleModel } from '../contentful/example-model'

export default function Page({ examples }: InferGetStaticPropsType<typeof getStaticProps>) {
    return <ul>
        {
            examples.map(example => <li key={example.sys.id}>
                <p>{example.fields.title}</p>
                <p>{example.fields.description}</p>
                <p>{example.fields.rating} / 5</p>
            </li>)
        }
    </ul>
}

export const getStaticProps: GetStaticProps<{ examples: ExampleModelEntry[] }> = async () => {
    return {
        props: {
            examples: await exampleModel.getAll(),
        }
    }
}

Conclusion

About abstractions and the work required to create them

By using time to design and create good abstractions, your code will be much easier to maintain, read and extend in the future. The work required to set up createContentfulModel in this article may seem like a lot. But consider the steps required now to add a new content type to your application.

Set up the new content type in your Contentful workspace.
Create a new model with createContentfulModel and only provide the schema for its fields and the content type id.
Add its types to types/contentful.d.ts
You’re ready to consume the data anywhere with the .getAll() method.

In addition to this, abstractions make your code easily extensible. Implementing other fetchers than the getAll fetcher will make them available for all content types by writing the code once. In the next article, we will examine extending this abstraction to work with Contentful images and rich text using the context object teased in this article.

In the next article

Read the next article to examine how we’ll extend this abstraction. We’ll be creating

Support for Contentful images
Support for Rich Text

(Not yet published)

Hosting a static site on an FTP server with Next.js examples

Jussi Nevavuori — Mon, 25 Jul 2022 10:24:35 +0000

When building a statically generated site (SSG site) using Next.js or any other SSG framework, such as Hugo, Gatsby, Jekyll or Nuxt you might find yourself wanting to host the generated static files on an FTP server. Be the reason your own solution or a client requirement, this article will show you how to do it. Our target is to build a script that will enable you to simply run a single npm script to build and deploy the project to a FTP server.

$ npm run deploy

What kind of content can you host?

Using this method, you can host any static sites, which consist of static HTML, JavaScript and CSS files, or other static assets. The static pages may be handwritten from scratch or generated with any SSG framework. Any dynamic content must be either fetched client-side or the site must be regenerated and redeployed when content changes.

In this article I will be using Next.js as an example. If you are not using Next.js, the article will point out those steps which you need to adapt to your own framework.

What is FTP?

You’re going to need an FTP server. FTP stands for File Transfer Protocol, which is essentially sort of like HTTP, but for transmitting files between computers. You can read more about FTP here. You can connect to a remote FTP server directly with a FTP client such as FileZilla or Commander One. Those provide a graphical user interface for manually uploading and downloading files. While you could by all means use an FTP client, our target is to write a script that allows uploading your entire project to the FTP server using one single command: npm run deploy

Step 1: Build your project

Let’s start off by initializing an empty deploy script in our package.json.

{
     ...
    "scripts": {
        ...
        "deploy": ""
    },
    ...
}

The first step for our deployment script is to build the project to static files. Using Next.js we must run two commands: next build and next export. In the case of Next.js it will generate our exported static files into a /out directory by default.

Let’s write those as the first instructions for our deployment script.

"scripts": {
  "deploy": "next build && next export"
}

For other frameworks: Replace next build && next export with any commands that builds your project to static files into some output directory, such as npm run build. For projects where no build step is required (manually writing static files), this step can be omitted.

Step 2: Setup custom JavaScript script for deploying

Create a directory /scripts where we’ll create a file: deploy.js for deploying. (Note: if you encounter problems running the script, attempt changing the filetype to deploy.mjs).

Let’s just initialise it with an empty async main function for now.

async function main() {

    return 0;
}

main().then(code => process.exit(code));

This deployment script will handle all the rest of the deployment procedures after we have built the project so we can hook it up to the npm script to complete it as follows.

"scripts": {
  "deploy": "next build && next export && node ./scripts/deploy.js"
}

Step 3: Setup a .env file with your FTP credentials

You’ll need credentials to connect into an FTP server. Let’s save the FTP host, port, username and password into our .env file for later use. The port 21 is commonly used for FTP.

FTP_USER=your-username-here
FTP_PASS=your-password-here
FTP_HOST=your.hostname.here
FTP_PORT=21

Step 4: Flesh out the deployment script

Let’s start up by installing the dependencies required for the script by running

$ npm i -D dotenv ftp-deploy

And import those at the top of your script

import dotenv from "dotenv";
import FtpDeploy from "ftp-deploy";

dotenv.config({ path: "./.env" });

And let’s fill out the deployment script. Most of the heavy lifting will be done by ftp-deploy. Feel free to customise any settings for the deployment to better suit your needs. This configuration is the one I’ve used for uploading all Next.js build files to the root of an FTP server.

import dotenv from "dotenv";
import FtpDeploy from "ftp-deploy";

dotenv.config({ path: "./.env" });

async function main() {
  try {
        // Replace "/out" with your build directory which contains all generated static files
        const outDir = path.join(process.cwd(), "/out");

        await new FtpDeploy().deploy({
            user: process.env.FTP_USER, // Your credentials
            password: process.env.FTP_PASS, // Your credentials
            host: process.env.FTP_HOST, // Your credentials
            port: process.env.FTP_PORT, // Your credentials

            localRoot: outDir, // Location of build files in project
            remoteRoot: "/", // Upload location on remote, replace with subfolder on FTP-server if required

            include: ["*", "**/*"], // Upload all files from build folder
            exclude: [], // Exclude no files

            deleteRemote: false, // Set to true if you want to delete ALL FILES in the remote root before uploading
            forcePasv: true // Use passive mode
        })

        console.log("Succesfully deployed site")
        return 0;
    } catch (e) {
        console.error("An error occured during deployment:", e);
        return 1;
  }
}

main().then((code) => process.exit(code));

You’re done.

Now running npm run deploy will build your project to static files and automatically upload those static files.

Potential issues

The client wants to update the site by themselves

The client may update some of the content used on the site, which is used at the build step. The site will then show old data and must be redeployed. One, quite manual way of getting over this issue is to enable the client to update the site by themselves using the same update script. It will take some time to properly set up, but may save a lot of time later.

Install git, node and npm on your clients computer.
Add them to the project’s GitHub repository as a collaborator (under settings, then collaborators).
Update the deploy script to include git pull and npm i at the start so it looks like "deploy": "git pull && npm i && next build && next export && node ./scripts/deploy.js". This will ensure the client always has the latest version of the project and correct dependencies installed before deploying.
Clone the repository onto the client’s machine with git clone https://github.com/username/reponame.git.
Add the correct credentials to the .env file at the project.
Write any script file on the client’s computer to an accessible location, name it something clear, such as Update Project.bat. The script file must do two things: 1. navigate to the project root and 2. run npm run deploy.

After this setup your client may freely update any data related to the site, for example on a headless CMS and after updating they can then click Update Project.bat which will (from their point of view) run some magical code and the site is updated. Now all you need to do is ensure that the client doesn’t mess with any of the files in the project directory to make your life easier and only ever to interact with the project by running the update script.

Alternatively, you could provision a cloud computer to do the same thing when invoked via a webhook (that is triggered by any update to your client’s data sources) to automatically update the site without any client interaction. That however would cost you more than the previous $0 alternative.

Old unused files are left on the FTP server

If there are no other files on the FTP server at your remoteRoot, you can use the deleteRemote: true option to wipe all previous files when deploying new files. If you are unable to do that, you must either write custom logic to the script to delete previous files, manually delete unused files periodically or leave them be.

End-to-end Typesafe APIs with TypeScript and shared Zod schemas

Jussi Nevavuori — Mon, 18 Jul 2022 08:07:57 +0000

Validating your data is absolutely necessary. The data could be data fetched from an API, data posted to the API in the request body or any other IO operation. This article will present a method of using TypeScript and Zod to create shared schemas between your frontend and backend. Shared schemas will allow not only achieving the required level of data validation but also provide tooling such as automatically generated shared types that greatly increase productivity!

Let’s create the simplest possible todo app, going through each line of code relevant to data validation.

Follow the code on GitHub, where I have posted a simple example of this app created with Next.js

Why use Zod?

You can use any other validation library, such as the other popular three-letter options, yup or joi. I strongly recommend choosing Zod, as it in my opinion provides a great set of utilities, supports practically every type you could wish to support, has great TypeScript support and a short, easy to remember API.

Especially for people used to TypeScript types, Zod schemas really do their best at making them feel like regular TypeScript schemas. For example, all object properties are required unless explicitly marked as .optional() or .nullable(), similar to how TypeScript types require explicitly declaring a property as optional with ?, | undefined or | null. With other data validation libraries, you might always have to remember to type .string({ required: true }) which just doesn’t feel as natural.

Defining a schema and its auto-generated types

Let’s create a simple Todo app to illustrate how Zod is used both in the backend and the frontend. Let’s first define a schema for a todo item. We declare a Zod object schema with the z.object() method. We can then define each property and its types, each of which can then be refined further with chained methods of those types.

The important part of defining a schema to reach maximum typesafety is to share it between your frontend and backend. This could be done with for example an internal npm package or a monorepo. In some cases, such as with Next.js, you just place the schema for example in a folder such as /lib/schemas and it’s automatically reachable by both your frontend and backend code. Doing this prevents any need for duplicating the schema and maintaining two identical schemas. (Again, an easy source of bugs: “I’ll just quickly change this property to optional…” might be a sentence you hear yourself saying and then forget to change the other copy of the schema).

import { z } from "zod";

export const todoSchema = z.object({
    id: z.string(),
    done: z.boolean(),
    text: z.string().min(1), // min(1) disallows empty strings
    important: z.boolean().optional(), 
    createdAt: z.string(),
    updatedAt: z.string(),
})

// For later purposes, we also define a schema for an array of todos
export const todosSchema = z.array(todoSchema);

Next we define a type for todos. Regularly you might start creating a type that matches the schema with export type Todo = { done: boolean; ... }, however that is not only unnecessary but also unproductive as it requires you maintain two versions of the same schema. Instead you can use Zod to autogenerate the schema by type inference (which Zod happens to be very good at).

// .../schemas/todo.schema.ts
export type Todo = z.TypeOf<typeof todoSchema>;

Protip: Instead of exporting these types, you can optionally declare the following type in your types.d.ts file or any other .d.ts file that is included in your tsconfig.json. Doing this means you don’t ever again need to import your types with import { Todo } from "path/to/todo". However declaring types this way means you have to import all dependencies inline. Little ugly, but useful in the long run in my opinion.

// types.d.ts
type Todo = import("zod").TypeOf<
  typeof import("./lib/schemas/todo.schema")["todoSchema"]
>;

To reflect on the power of shared schemas combined with automatically inferred types: without them, you would have to keep one copy of the both the schema and the interface in your backend and your frontend, which would result in a total of four different schemas defining the exact same thing, each one requiring to be updated when any update is required.

Typesafe fetching with your new schema and types!

Let’s start implementing the API to serve the todos and the frontend functions required to consume them! We create a simple endpoint to serve all todos.

export default async function handler(req: Request, res: Response) {
    if (req.method === "GET") {
        const todos = await getAllTodosFromDatabase();
        res.json(todos);
    }
}

The old way of fetching this data in a typesafe manner would involve typecasting. Some typechecking with if (data !== null) or if (typeof data === "object") or multiple other longwinded ways of attempting to validate your data might be present and should automatically signal to the developer that a better solution is required.

// BAD!
async function fetchTodos(): Promise<Todo[]> {
    const response = await fetch("/api/todos");
    const json = await response.json();
    return json as Todo[];
}

Doing this would be an easy source of bugs. You assume your backend delivers objects of a certain shape. Suddenly the array doesn’t even exist, all the objects within it are null, or some of the objects might have a missing id property. You don’t know and you can’t trust until you validate. This is where the schema comes into play.

Validating your data, without any typecasting and with a lot more confidence in your own code can be achieved with just a few lines of code.

// Good.
async function fetchTodos(): Promise<Todo[]> {
    const response = await fetch("/api/todos");
    const json = await response.json();

    const parsed = todosSchema.safeParse(json);
    if (parsed.success) {
        return parsed.data;
    }

    // Handle errors
    console.error(parsed.error)
    return [];
}

Using the safeParse method, we can easily validate that the data has the correct shape and return it as is, no typecasting necessary - Zod handles typing for you. In case there is an error, parsed.success will be false and the parsed.error property will contain the resulting error. Handling errors is left as an exercise to the reader, however returning an empty array as a default value and logging the error is a start.

There! We now have a simple API to serve data of the correct type and a client function to fetch it with validation. Simple as that!

Updating and creating a todo item

Let’s next tackle the reverse direction: the server validating data received from the client. Again, we can define new shared schemas. This time the schemas define the shape of the object sent as the request body to the API. They can then be used for both validating on the server and defining the correct shape on the frontend. Let’s create schemas for updating and creating todo items (with automatically inferred types).

// lib/schemas/todo.schema.ts

export const todoUpdateSchema = z.object({
  id: z.string(),
  done: z.boolean(),
});

export const todoCreateSchema = z.object({
  text: z.string(),
  important: z.boolean(),
});

export type TodoUpdate = z.TypeOf<typeof todoUpdateSchema>;
export type TodoCreate = z.TypeOf<typeof todoCreateSchema>;

Let’s next define simple handlers in the endpoint for these methods.

// pages/api/todos.ts

export default async function handler(req: Request, res: Response) {
    // ...
  if (req.method === "PATCH") {
    const body = todoUpdateSchema.parse(req.body);
    updateTodoInDatabase(body.id, body.done);
    return res.status(200).end();
  }

  if (req.method === "POST") {
    const body = todoCreateSchema.parse(req.body);
    createTodoInDatabase(body);
    return res.status(200).end();
  }
}

Here instead of using the safeParse() method, we use a more direct method - the parse() method. parse() returns the validated data in its correct shape and throws on invalid data. Sometimes this is preferred, as it results in fewer lines and easier-to-read code but leaves the error handling to be done in a catch-block. For example on a server, where errors may be handled by a common error handler function, this could be a good option (or if you just prefer try { schema.parse(json) } catch (e) { } instead of const parsed = schema.safeParse(json); if (parsed.success) { } else { }!

Consuming these routes on the frontend is as easy as defining the following functions, the types of which are conveniently available already and the exact same types which the backend uses.

async function createTodo(body: TodoCreate) {
    await fetch("/api/todos", {
        body: JSON.stringify(body),
        headers: { "Content-type": "application/json" },
        method: "POST",
    })
}

async function updateTodo(body: TodoUpdate) {
    await fetch("/api/todos", {
        body: JSON.stringify(body),
        headers: { "Content-type": "application/json" },
        method: "PATCH",
    })
}

Let’s review

We’re done now! All that’s left to do is hook up the updateTodo, createTodo and fetchTodos functions to the frontend code and to expand upon this idea.

The steps:

Create a schema with Zod (shared between frontend and backend code)
Get automatic types with Zod’s z.TypeOf<typeof schema> type inference (also shared)
Validate data when fetching data or posting data to the server (use .parse() or .safeParse() according to your liking)

And the results:

Automatically generated types
Shared schemas and types between frontend and backend code
Full confidence in your data’s validity
Complete data validation with just a few lines of code
No maintaining symmetric schemas and types in multiple places

The code shown in this article is obviously the bare minimum code of the simplest possible example, but expanding this to larger applications is not only easy but quite honestly a necessity. No application larger than a todo app created for learning a new JS framework should ever communicate data that has not been validated. Moreover, attempting to validate data without shared Zod schemas is just extra work and can even serve as a potential source of bugs.

Persist your state anywhere with createPersistentItem with React examples

Jussi Nevavuori — Mon, 11 Jul 2022 07:04:33 +0000

Persisting your state can sometimes be difficult. Useful ways to do it are setting the value to localStorage or sessionStorage. But managing manual set and get operations on larger applications will become difficult. And what if you want to store your state on the server and sync it across devices? In that case you need even more hassle with fetch calls, useEffects and more. It becomes a great big hassle.

In this article we are going to discuss a better solution, which will not only scale well but provide us with features that aren’t available to us with just the local storage API, such as typesafety and automatic updates.

Follow the code on GitHub where I have posted all the code shown in this article and more.

Note on TypeScript and React

All the following code (with types removed) is also valid JavaScript and will also work in JavaScript. The implementation is also completely framework agnostic and will work with any framework, from vanilla JavaScript to Vue. The hook and React examples provided at the end of this article are however React-specific, but should be implementable in other frameworks as well to achieve similar results.

The idea

The target is to create an API for working with pieces of data which are stored in persistent stores (localStorage, sessionStorage, a server) which provides us all the following perks:

Abstracts away the implementation of interacting with the store using the strategy pattern and thus allows for implementing other stores as well.
Is typesafe, with all values being validated.
Supports custom serialization and deserialization.
Contains a subscribable which allows for subscribing to all state updates, which will further allow us to create React hooks which automatically update to match the state (or similar constructs in other frameworks).
Provides a simple API for interacting with the data with minimal functions .get(), .set(value), .update(prev => newValue), .clear() and .subscribe(listener).

The solution is an abstraction, a function, createPersistentItem that creates a single centralized object with an API to access any single piece of persistent data, be it a primitive or a complex object.

Moreover, the function should take as an argument a persistence strategy, which handles the actual setting, getting and clearing of the value in any persistent store, such as localStorage or even a custom server.

Let’s start off by tackling persistence strategies

Pesistence strategies are an important part of the solution. They abstract away the implementation of actually storing the data somewhere, be it localStorage, sessionStorage, a database via an API or any other solution.

A persistence strategy should implement three methods: get, set and clear for getting, setting and clearing an item for a given key with a value of a given type.

Additionally, some storage methods are synchronous, such as localStorage and sessionStorage and we might want to get the data synchronously from these stores when possible. To support this functionality, we add another method, getSync which returns the value synchronously and a flag (supportsSync), which tells the user whether the persistence strategy supports synchronous operations. Using getSync for async stores (such as an API) will always return undefined as they can not fetch the data synchronously.

From the above plan, we get the following interface for all persistence strategies.

// src/lib/PersistenceStrategy.ts

export interface IPersistenceStrategy {
  supportsSync?: boolean;
  get<T>(options: PersistenceStrategyGetOptions<T>): Promise<T | undefined>;
  getSync<T>(options: PersistenceStrategyGetOptions<T>): T | undefined;
  set<T>(options: PersistenceStrategySetOptions<T>): Promise<T>;
  clear(key: string): Promise<void>;
}

Additionally, the PersistenceStrategyGetOptions and PersistenceStrategySetOptions are defined below. They include a key to identify where the value is stored. For getting the value, we also provide methods for validating the value and optionally deserializing the value (else we use JSON.parse). For setting the value respectively, we provide the value we want to set and optionally a function to serialize it when JSON.stringify will not do.

// src/lib/PersistenceStrategy.ts

export type PersistenceStrategyGetOptions<T> = {
  key: string;
  validate: (t: any) => t is T;
  deserialize?: (serial: string) => T | undefined;
};

export type PersistenceStrategySetOptions<T> = {
  key: string;
  value: T;
  serialize?: (t: T) => string;
};

Following these guidelines, we can create an example strategy for storing items in localStorage.

// src/lib/LocalStoragePersistenceStrategy.ts

export const LocalStoragePersistenceStrategy: IPersistenceStrategy = {
    // Local storage supports synchronous operations
  supportsSync: true,

  // Local storage synchronous getter
  getSync<T>(opts: PersistenceStrategyGetOptions<T>): T | undefined {
    try {
      // Get serial value from local storage, if not found return undefiend
      const serial = localStorage.getItem(opts.key);
      if (!serial) return undefined;

      // Deserialize with deserializer or JSON.parse if no deserializer,
            // return undefined if serialization fails
      const value = opts.deserialize
        ? opts.deserialize(serial)
        : JSON.parse(serial);
      if (!value) return undefined;

      // Validate, return value or undefined on invalid validation
      if (opts.validate(value)) return value;
      return undefined;
    } catch (e) {
            // On all errors return undefined
            console.error(e);
      return undefined;
    }
  },

  // Async getter simply promisifies the sync getter method
  async get<T>(opts: PersistenceStrategyGetOptions<T>): Promise<T | undefined> {
    return this.getSync(opts);
  },

  async set<T>(opts: PersistenceStrategySetOptions<T>): Promise<T> {
    // Serialize with serializer or JSON.stringify and save to localStorage
    const serial = opts.serialize
      ? opts.serialize(opts.value)
      : JSON.stringify(opts.value);
    localStorage.setItem(opts.key, serial);
    return opts.value;
  },

  // Clear value
  async clear(key: string): Promise<void> {
    localStorage.removeItem(key);
  },
};

Other persistence strategies

The SessionStoragePersistenceStrategy (view code on GitHub) is an exact copy of the LocalStoragePersistenceStrategy, but with localStorage swapper for sessionStorage.
The ServerPersistenceStrategy (view code on GitHub) is an example persistence strategy for interacting with the simplest possible API for storing items on the server. Unlike LocalStoragePersistenceStrategy, it is async only and calling the getSync method will always result in undefined. (View the simplest implementation of an express server which handles the requests from ServerPersistenceStrategy)

Implementing createPersistentItem

Now that we have tackled persistence strategies and our persistent items no longer need to worry about the details of how they will be fetched, updated and cleared, we can continue on with implementing persistent items. The first step is to define an interface for persistent items, which contains three parts.

Data getting methods
- get() for asynchronously getting the value of the item.
- getSync() for synchronously getting the value of the item if the persistence strategy supports synchronous operations (when persistenceStrategy.supportsSync is true).
- subscribe(listener) which subscribes to all state updates and returns an unsubscriber function.
Date updating methods
- set(value) for setting the value. Returns the new value.
- update(updater) for updating the value with an updater function when the next value depends on the previous value. Returns the new value.
- clear() for clearing the value.
Options for the persistent item. These are also the options that are provided when creating a persistent item.
- key for storing the persistent item.
- persistenceStrategy for storing the item in a store.
- validate for validating that a value is a valid value for this item.
- serialize for optionally overriding JSON.stringify serialization.
- deserialize for optionally overriding JSON.parse deserialization.

The final interface will look like the following.

// src/lib/createPersistentItem.ts

export interface IPersistentItem<T> {
  // Interfaces for getting data (sync / async) and subscribing to data updates
  get(): Promise<T | undefined>;
  getSync(): T | undefined;
  subscribe(listener: (t: T | undefined) => void): () => void;

  // Interfaces for updating data (set value, update value with updater function
  // or clear value)
  set(value: T): Promise<T>;
  update(updater: (t: T | undefined) => T): Promise<T>;
  clear(): Promise<void>;

  // Options
  key: string;
  persistenceStrategy: IPersistenceStrategy;
  validate: (t: any) => t is T;
  serialize?: (t: T) => string;
  deserialize?: (string: string) => T | undefined;
}

Let’s start implementing this. First we’ll define the function signature (options and return type). The function will return a IPersistentItem<T> as defined previously and take as options the previously discussed options and directly reveal them in the return value.

// src/lib/createPersistentItem.ts

export function createPersistentItem<T>(options: {
  key: string;
  validate: (t: any) => t is T;
  persistenceStrategy: IPersistenceStrategy;
  serialize?: (t: T) => string;
  deserialize?: (string: string) => T | undefined;
}): IPersistentItem<T> {

    /* ... */

    return {
        // Reveal the options
        ...options,

        /* ... Implement rest of the methods here ... */
    }  
}

Let’s next implement each method. First, the getter methods get and getSync are simple calls to the persistenceStrategy.get and persistenceStrategy.getSync methods respectively.

// src/lib/createPersistentItem.ts

export function createPersistentItem<T>(/* ... */): IPersistentItem<T> {
    /* .. */
    return {
    ...options,
    getSync() {
      return options.persistenceStrategy.getSync({
        key: options.key,
        validate: options.validate,
        deserialize: options.deserialize
      });
    },
    get() {
      return options.persistenceStrategy.get({
        key: options.key,
        validate: options.validate,
        deserialize: options.deserialize
      });
    },
    }
}

Next up lets implement the subscribe method. For that use, we are going to need an internal subscribable, created with a createSubscribable method (see here for implementation). That subscribable is going to receive updates from all data updating methods (set, update and clear) and subscribe is going to only function as a wrapper for subscribable.subscribe. After implementing createSubscribable, the implementation is as easy as below.

// src/lib/createPersistentItem.ts

export function createPersistentItem<T>(/* ... */): IPersistentItem<T> {

    const subscribable = createSubscribable<T | undefined>();

    return {
    ...options,
    getSync() { /* ... */ },
    get() { /* ... */ },
        subscribe: subscribable.subscribe,
    }
}

This allows us to finally implement all data updating methods. Each of the methods is primarily a call to either the persistenceStrategy.set or persistenceStrategy.clear methods. Additionally, the methods handle errors, publish the new value to the subscribable after successfully updating the value and return the new value. In addition, update also fetches the previous value and uses it to call the provided updater function to derive the new value.

// src/lib/createPersistentItem.ts

export function createPersistentItem<T>(/* ... */): IPersistentItem<T> {
    const subscribable = createSubscribable<T | undefined>();
    return {
    ...options,
    getSync() { /* ... */ },
    get() { /* ... */ },
        subscribe: subscribable.subscribe,

        async set(value: T) {
      try {
        await options.persistenceStrategy.set({
          value,
          key: options.key,
          serialize: options.serialize,
        });
        subscribable.publish(value);
      } catch (e) {
        console.error(e);
      } finally {
        return value;
      }
    },

    async update(updater: (prev: T | undefined) => T) {
      const prev = await this.get();
      const value = updater(prev);
      try {
        await options.persistenceStrategy.set({
          value,
          key: options.key,
          serialize: options.serialize,
        });
        subscribable.publish(value);
      } catch (e) {
        console.error(e);
      } finally {
        return value;
      }
    },

    async clear() {
      try {
        await options.persistenceStrategy.clear(options.key);
        subscribable.publish(undefined);
      } catch (e) {
        console.error(e);
      }
    },
    }
}

There we have it! A wrapper for persistent items!

Using persistent items

We can now use the API for example for storing the number of clicks to a button as follows.

const nClicks = createPersistentItem<number>({
    key: "clicks",
    validate: (t: any): t is number => typeof t === "number" && t >= 0,
    persistenceStrategy: LocalStoragePersistenceStrategy
})

// Setting the value to a number from an input
document.querySelector("button#set").addEventListener("click", () => {
    nClicks.set(document.querySelector("input#num").valueAsNumber);
});

// Updating the value
document.querySelector("button#add").addEventListener("click", () => {
    nClicks.update(prev => (prev ?? 0) + 1);
});

// Resetting the value
document.querySelector("button#reset").addEventListener("click", () => {
    nClicks.clear();
});

// Logging each new value to the console
nClicks.subscribe(newValue => console.log(newValue));

Creating a React hook

For easier use with React, we can also create a custom hook for accessing the current value of a persistent item. The hook will allow us to automatically rerender a component whenever the persistent item’s value is updated from anywhere within the app.

The hook contains takes as input a persistent item and contains its value in a useState. The state is initialized with the getSync method, which will automatically be undefined for async items. For async items, another useEffect is fired once which asynchronously initializes the state from undefined. Finally another useEffect is fired which handles subscribing and unsubscribing to state updates.

// src/hooks/usePersistentItem.ts

export function usePersistentItem<T>(item: IPersistentItem<T>) {
  // State for holding current value, automatically updated. Initialize with
  // synchronously gotten value (undefined for async persistence strategies).
  const [value, setValue] = useState<T | undefined>(item.getSync());

  // Initialize value asynchronously for async persistence strategies
  useEffect(() => {
    if (!item.persistenceStrategy.supportsSync) {
      item.get().then((_) => setValue(_));
    }
  }, [setValue, item]);

  // Subscribe to updates and auto-update state
  useEffect(() => item.subscribe((t) => setValue(t)), [setValue, item]);

  // Return current value
  return value;
}

The following snippet demonstrates the usage of the hook. The beautiful thing about this centralized implementation with a subscribable is that clicking one button automatically increments the value in both buttons as they are subscribed to the same item. The value is stored in local storage, but changing it to be stored in session storage, on a server or somewhere else is as easy as changing the persistence strategy.

// src/App.tsx

function Counter(props: { item: IPersistentItem<number>, label: string }) {
    const clicks = usePersistentItem(props.item);

    return <div>
        <p>
            {props.label}
        </p>
        <button onClick={() => props.item.update(current => (current ?? 0) + 1)}>
            Clicked {clicks ?? 0} times
        </button>
        <button onClick={() => props.item.set(5)}>
            Set to 5
        </button>
        <button onClick={() => props.item.clear()}>
            Reset
        </button>
    </div>
}

function App() {
    return (
        <div>
            <Counter item={nClicks} label="Local storage 1" />
            <Counter item={nClicks} label="Local storage 2" />
        </div>
    );
}

const nClicks = createPersistentItem<number>({
    key: "clicks",
    validate: (t: any): t is number => typeof t === "number" && t >= 0,
    persistenceStrategy: LocalStoragePersistenceStrategy
});

Final words

Thank you for reading. You are free to use the pattern provided in this article as well as any code you find here. Please feel free to send me a message if you find this useful or find a way to make this even better.

Ideas on how to make this better

Reducing boilerplate for persistence strategies

Currently writing persistence strategies creates some boilerplate in our code. In each persistence strategy, we must declare error handling, serialization, deserialization and validation manually. However, you could easily create another abstraction (createAsyncPersistenceStrategy and createSyncPersistenceStrategy) which could be used as follows:

// Example API

export const LocalStoragePersistenceStrategy = createSyncPersistenceStrategy({
    get(key: string): string | undefined {
        return localStorage.getItem(key) ?? undefined;
    },
    set(key: string, serial: string): void {
        localStorage.setItem(key, serial);
    },
    clear(key: string): void {
        localStorage.removeItem(key);
    }
});

Here createSyncPersistenceStrategy and createAsyncPersistenceStrategy simply take the implementations of fetching a serialized value, setting a serialized value and clearing the value and wrap them with validation, serialization, deserialization, correct get and getSync and supportsSync implementations and error handling. The implementations can be found in GitHub, together with example usage of them for creating LocalStoragePersistenceStrategy and ServerPersistenceStrategy with the functions.

How To Access Page Props in All Components with Next.js and TypeScript

Jussi Nevavuori — Fri, 01 Jul 2022 11:17:02 +0000

The problem: Lifting page props from getStaticProps to your <Layout/> component, rendered in _app.tsx is a hassle. In fact, Next.js provides no existing solution to that problem and we have to come up with one ourselves. In this article I present the idea of global props as a solution.

When would I ever need to do this?

A simple scenario where I could see this happening is on a site with a selection of products. Each product is fetched in getStaticProps, in /products and the developer wants to display the number of products in the header, next to the link to the /products page.

This means the developer has to send the products prop received by the products page component from getStaticProps all the way to the <Header/> component, rendered by <Layout/> in _app.tsx.

A worse developer might come up with a “quick hack”, a one-off solution to get just this feature working. For example, they might set up a pubsub system, where the header component subscribes to a subscribable, and the /products page component publishes the props it receives. Will work, but runs the risk of becoming unmaintainable and confusing as the data is moving sideways through the component tree via an external subscribable.

Instead, this article demonstrates another way of passing data into the entire application.

Introducing global props

The solution I ended up using on my personal portfolio page, as well as other projects I have worked on is GlobalProps.

We declare certain props as global, which are accessible on all pages. In the above example, that might be a list of products. These could also be projects and blogs on your personal page or any other server-side fetched data that is accessible to the entire application. The essence of the solution goes as follows.

On all pages, fetch the global props (and other page-specific props)
Intercept the global props in _app.tsx using pageProps
Pass the global props to a GlobalPropsContext in _app.tsx
Use the global props in ANY component with a custom hook.

In addition to the solution, I will also provide some utility functions which make these steps easier. Especially step 1, fetching the global props on each page, which could result in a lot of code duplication with a worse implementation.

GitHub

Follow the code on GitHub

Step 1 - Define the global props

First we define what props we want to declare as global. We are going to run with the above example and define products as a global prop we want to be accessible app-wide. Let’s declare it as a type, assuming we have some Product type.

// types/index.d.ts

type Product = { /* ... */ }

type GlobalProps = {
    product: Product[];
};

Step 2 - Fetching the global props

Step 1 was easy. Now we can get on with even more code. Let’s assume we have a productApi, which defines the productApi.getAll(): Promise<Product[]> method for fetching all products.

Let’s first define a utility function which fetches global props.

// features/GlobalProps/lib/fetchGlobalProps.ts

import { productsApi } from "../../../lib/api/productsApi";

export async function fetchGlobalProps(): Promise<GlobalProps> {
  return {
    products: await productsApi.getAll(),
  };
}

We could now use this function on all pages as follows

// pages/index.tsx

import type { GetStaticProps, InferGetStaticPropsType } from 'next'
import { fetchGlobalProps } from '../features/GlobalProps/lib/fetchGlobalProps';

type PageProps = InferGetStaticPropsType<typeof getStaticProps>;

export default function Page(props: PageProps) {
    return (
        <div style={{ padding: "8rem" }}>

            <h1>Home</h1>

        </div>
    )
}

export const getStaticProps: GetStaticProps<GlobalProps> = async () => {
    return {
        props: {
            ...await fetchGlobalProps(),
        }
    }
}

But we can make this even nicer by providing a getStaticProps wrapper that automatically adds global props to any getStaticProps function.

Let’s define getStaticPropsWithGlobalProps for this purpose. It’ll act as a wrapper for the getStaticProps function and can fetch the rest of the data required by the page using the regular getStaticProps API, however it automatically adds the global props to the returned props, with automatic typing.

// features/GlobalProps/lib/getStaticPropsWithGlobalProps.ts

import {
  GetStaticProps,
  GetStaticPropsContext,
  GetStaticPropsResult,
} from "next";
import { fetchGlobalProps } from "./fetchGlobalProps";

export function getStaticPropsWithGlobalProps<T extends {}>(
  getStaticProps: (
    ctx: GetStaticPropsContext,
    globalProps: GlobalProps
  ) => Promise<GetStaticPropsResult<T>>
): GetStaticProps<T & GlobalProps> {

  // Construct getStaticProps function
  return async (ctx: GetStaticPropsContext) => {

    // Fetch global props
    const globalProps = await fetchGlobalProps();

    // Run getStaticProps with user defined getStaticProps, provide context
    // and global props
    const result = await getStaticProps(ctx, globalProps);

    // If redirect or notFound in result, return result as is, in this case
    // no page props will be provided
    if ("redirect" in result || "notFound" in result) {
      return result;
    }

    // Return combined page props and global props as page props
    return {
      props: {
        ...result.props,
        ...globalProps,
      },
      revalidate: result.revalidate,
    };
  };
}

Let’s also quickly define a GlobalProps object which exports all functionality meant for the public API of this feature and export this function as getStaticProps.

// features/GlobalProps/GlobalProps.ts

import { getStaticPropsWithGlobalProps } from "./lib/getStaticPropsWithGlobalProps";

// Defines the public API
export const GlobalProps = {
  getStaticProps: getStaticPropsWithGlobalProps,
};

Now we can use it on our pages as follows.

// pages/products.tsx

// ...

export const getStaticProps = GlobalProps.getStaticProps<{exampleValue: number}>(
    async (ctx) => {
        return { props: { exampleValue: 1 } }
    }
)

The page will now have access to both products, along with all the other components in the app. The page will also have access to someOtherProp, however it will not be accessible to the rest of the app, only the page via page props.

Accessing Global Props in `getStaticProps`

Furthermore, we can access the global props in the getStaticProps implementation as the second argument after ctx, the default getStaticProps context object. This is useful for example on the product page, where the props depend on the global props.

// pages/products/[slug].ts

import { GetStaticPaths, InferGetStaticPropsType } from "next";
import { GlobalProps } from "../../features/GlobalProps/GlobalProps";
import { productsApi } from "../../lib/api/productsApi";

type PageProps = InferGetStaticPropsType<typeof getStaticProps>;

export default function Page(props: PageProps) {
    return <div style={{ padding: "8rem" }}>
        <h1>{props.product.name}</h1>
        <p>{props.product.price} $</p>
    </div>
}

export const getStaticPaths: GetStaticPaths = async () => {
    const products = await productsApi.getAll()
    return {
        paths: products.map(p => ({ params: { slug: p.slug } })),
        fallback: false,
    }
}

export const getStaticProps = GlobalProps.getStaticProps<{ product: Product }>(
    async (ctx, globalProps) => {

        // GetStaticProps has access to the global props as the parameter
        const slug = (ctx.params?.["slug"] ?? "").toString()
        const product = globalProps.products.find(_ => _.slug === slug)

        if (!product) return { notFound: true }

        return { props: { product } }
    }
)

Utility for pages with no static props other than the global props

Instead of having to type out

export const getStaticProps = GlobalProps.getStaticProps(async () => ({ props: { } }))

for every route without props, let’s define GlobalProps.getEmptyStaticProps to do it for us. Then we can simply write

export const getStaticProps = GlobalPrsop.getEmptyStaticProps

// features/GlobalProps/GlobalProps.ts

import {
  GlobalPropsContextProvider,
  useGlobalProps,
} from "./contexts/GlobalPropsContext";
import { extractGlobalProps } from "./lib/extractGlobalProps";
import { getStaticPropsWithGlobalProps } from "./lib/getStaticPropsWithGlobalProps";

// Defines the public API
export const GlobalProps = {
  getStaticProps: getStaticPropsWithGlobalProps,

    // ADD THIS:
  getEmptyStaticProps: getStaticPropsWithGlobalProps(async () => ({
    props: {},
  })),
};

Step 3 - Providing global props via a context

Let’s start by defining a React context for passing the global props to the entire component tree.

// features/GlobalProps/contexts/GlobalPropsContext.tsx

import { createContext, useContext, ReactNode } from "react"

// Default value for global props
export const defaultGlobalPropsContextValue: GlobalProps = {
    products: [],
}

// Global props context
export const GlobalPropsContext = createContext<GlobalProps>(defaultGlobalPropsContextValue)

// Global props context provider props
export interface GlobalPropsContextProviderProps {
    children?: ReactNode,
    globalProps: GlobalProps;
}

// Global props context provider
export function GlobalPropsContextProvider(props: GlobalPropsContextProviderProps) {

    return <GlobalPropsContext.Provider value={props.globalProps}>
        {props.children}
    </GlobalPropsContext.Provider>

}

// Utility hook to access global props
export function useGlobalProps() {
    return useContext(GlobalPropsContext)
}

The context is a regular context which has to be provided the global props which are then passed on. Note the useGlobalProps() hook which is later used to access these global props.

Let’s now also export these to our public API. For shorter syntax, I’m also going to call useGlobalProps() simply use(). This means we can just call GlobalProps.use() from our components to access the props.

// features/GlobalProps/GlobalProps.ts

import {
  GlobalPropsContextProvider,
  useGlobalProps,
} from "./contexts/GlobalPropsContext";
import { extractGlobalProps } from "./lib/extractGlobalProps";
import { getStaticPropsWithGlobalProps } from "./lib/getStaticPropsWithGlobalProps";

// Defines the public API
export const GlobalProps = {
  getStaticProps: getStaticPropsWithGlobalProps,
  getEmptyStaticProps: getStaticPropsWithGlobalProps(async () => ({
    props: {},
  })),
  Provider: GlobalPropsContextProvider,
  use: useGlobalProps,
    extract: extractGlobalProps,
};

Wait a minute - what is extractGlobalProps? In short, _app.tsx will receive a pageProps object of unknown type. We have to take the pageProps object and extract the globalProps from it into an object of type GlobalProps. At the same time we have to handle errors and invalid or missing data and provide default values. The implementation is the following for this use case (assuming a productsApi.isProducts(arg): arg is Product[] function exists.

// features/GlobalProps/lib/extractGlobalProps.ts

import { productsApi } from "../../../lib/api/productsApi";
import { defaultGlobalPropsContextValue } from "../contexts/GlobalPropsContext";

export function extractGlobalProps(data: any): GlobalProps {
  if (!data) return defaultGlobalPropsContextValue;

  // Do it the correct way with type validation and default values
  return {
    products: productsApi.isProducts(data.products) ? data.products : [],
  };

  // Or do it the lazy, error prone way if you trust your pageProps to have
    // the correct shape
    // return data as GlobalProps;
}

Now the last thing to get the props to our entire application is to provide them in _app.tsx. We set the GlobalProps.Provider as the root component in our application in order for all components to have access to GlobalProps and pass the extracted global props as an argument to it.

// pages/_app.tsx

import type { AppProps } from 'next/app'
import { GlobalPropsContextProvider } from '../features/GlobalProps/contexts/GlobalPropsContext'
import { GlobalProps } from '../features/GlobalProps/GlobalProps'
import { Layout } from '../components/Layout/Layout'

function MyApp({ Component, pageProps }: AppProps) {
    return <GlobalPropsContextProvider globalProps={GlobalProps.extract(pageProps)}>
        <Layout>
            <Component {...pageProps} />
        </Layout>
    </GlobalPropsContextProvider>
}

export default MyApp

There! Now our entire application can access the global props. Just as long as we remember to implement fetching on all pages, as shown in the next step.

Step 4 - Fetching on all routes

The above solution will only work as long as every route (including 404.tsx and 500.tsx) fetches the global props. It will not error out else, but will provide the default values for the global props which we do not want.

Luckily, refactoring components is easy.

Refactoring a component with no static props

Refactoring components with no static props is easy. It requires three changes (shown in the code below)

Import GlobalProps
Create an empty getStaticProps function with the GlobalProps.getEmptyStaticProps

// ORIGINAL

export default function Page() {
    return (
        <div style={{ padding: "8rem" }}>
            <h1>Home</h1>
        </div>
    )
}

// REFACTORED

// Step 1 - Import Global Props
import { GlobalProps } from '../features/GlobalProps/GlobalProps';

export default function Page(props: PageProps) {
    return (
        <div style={{ padding: "8rem" }}>
            <h1>Home</h1>
        </div>
    )
}

// Step 2 - Add an empty getStaticProps function
export const getStaticProps = GlobalProps.getEmptyStaticProps

Refactoring a page with static props

The process is as easy for page with static props. Similarly the two steps are:

Import GlobalProps
Wrap the getStaticProps function implementation with GlobalProps.getStaticProps

// pages/with-static-props.ts

// ORIGINAL

import { GetStaticProps, InferGetStaticPropsType } from 'next';

type PageProps = InferGetStaticPropsType<typeof getStaticProps>;

export default function Page(props: PageProps) {
    return (
        <div style={{ padding: "8rem" }}>
            <h1>WithStaticProps</h1>
            <p>Example value = {props.exampleValue}</p>
        </div>
    )
}

export const getStaticProps: GetStaticProps = async (ctx) => {
    return {
        props: {
            exampleValue: 1,
        }
    }
}

// REFACTORED

// Step 1 - Import Global Props
import { InferGetStaticPropsType } from 'next';
import { GlobalProps } from '../features/GlobalProps/GlobalProps';

type PageProps = InferGetStaticPropsType<typeof getStaticProps>;

export default function Page(props: PageProps) {
    return (
        <div style={{ padding: "8rem" }}>
            <h1>WithStaticProps</h1>
            <p>Example value = {props.exampleValue}</p>
        </div>
    )
}

// Step 2 - Wrap getStaticProps in GlobalProps.getStaticProps
export const getStaticProps = GlobalProps.getStaticProps(async () => {
    return { props: { exampleValue: 1 } }
})

Final step - Consume and enjoy!

There you have it. After every route has been given either the GlobalProps.getStaticProps or GlobalProps.getEmptyStaticProps function, we can finally do what we wanted to do in the beginning. Access the products in the header. And it becomes as simple as the following. Just access all global props with the GlobalProps.use() hook.

// components/Header/Header.tsx

import Link from "next/link";
import { GlobalProps } from "../../features/GlobalProps/GlobalProps";

export function Header() {
    const { products } = GlobalProps.use();

    return <header>
        <nav>
            <Link href="/">
                <a>Home</a>
            </Link>
            <Link href="/products">
                <a>Products ({products.length})</a>
            </Link>
        </nav>
    </header>
}

Final words

This provides a useful abstraction for some use cases, where a concept of global props is useful. And I could see it being used on a lot of different cases. I have worked on projects like the above example where I wanted each page to be aware of products. Similarly on my personal page I have blogs and projects to name a few as global props that are used page-wide as global props. And I imagine there are many more use cases for this.

If you use this, please do let me know. Similarly, if you have any improvements to this article, don’t hesitate to send me a message!

Smarter Next.js API routes with a custom createApiRoute function

Jussi Nevavuori — Tue, 28 Jun 2022 08:36:23 +0000

The Next.js API Route API is extremely simple, which is well suited for many cases. However, it leaves the developer to do all the work and problem solving when they require more complicated solutions, such as middleware or a custom request context object that may provide different things depending on the use case, such as database access or more. The API as is also provides no help when it comes to error handling, leaving the developer to do a lot of work for each route.

Note on TypeScript

In this article I’m using TypeScript. All code presented in this article can also be used in JavaScript, just remove the types.

GitHub

Follow the code and each of its steps in this GitHub repo.

Use the provided NPM package

You can also use the provided NPM package and install it with. The package is tested, comes with full TypeScript support and provides you all the features discussed in this article.

npm install create-next-api-route

View create-next-api-route on NPM

Coming up with a solution

The following example (TypeScript added) reads on the Next.js docs for API routes. It’s simple, effective, reasonable. However in reality it starts to become a bit of a hassle to manage all your methods with countless else ifs.

// /pages/api/simple-endpoint.ts

import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === "POST") {
        res.json({ value: "🚀" });
  } else {
        res.json({ value: "❌" });
  }
}

To outsmart this, one of the first things that come to mind is resorting to a switch statement like the following.

// /pages/api/switch-endpoint.ts

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
    switch (req.method) {
        case "POST": {
            // Process a POST request
            return res.status(200).json({ message: "🤝🏻" });
        }
        case "GET": {
            // Process a GET request
            return res.status(200).json({ message: "🚀" });
        }
        default: {
            // All other methods
            return res.status(405).json({ message: "Method not allowed" });
        }
    }
}

It’s definitely an improvement, but a lot of the originally mentioned problems still exist.

Adding middleware

Next up you realise you need your app to support middleware, such as cors , a request logger or other middleware. You might end up starting to type the following in every request handler. The following is even recommended on the API Routes documentation.

// /pages/api/middleware-endpoint.ts

import type { NextApiRequest, NextApiResponse } from "next";
import Cors from "cors";

// From the Next.js API Routes documentation, with added TypeScript
// https://nextjs.org/docs/api-routes/api-middlewares
//
// Helper method to wait for a middleware to execute before continuing
// And to throw an error when an error happens in a middleware
function runMiddleware(
  req: NextApiRequest,
  res: NextApiResponse,
  fn: Function
) {
  return new Promise((resolve, reject) => {
    fn(req, res, (result: any) => {
      if (result instanceof Error) {
        return reject(result);
      }
      return resolve(result);
    });
  });
}

// Create the cors middleware
const cors = Cors({ methods: ["GET", "HEAD", "POST", "OPTIONS"] });

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // Run the cors middleware before any of the event logic
  await runMiddleware(req, res, cors);

  res.json({ value: "🚀" });
}

This solution is ok, however it is extremely verbose and results in a lot of code duplication when the same middleware are required in multiple functions.

This much code already and there is no mention of a context object, error handling or anything else. Clearly, we need a better solution.

The `createApiRoute` abstraction

The solution comes in the form of a createApiRoute(...) function. Our target is to allow the following API for creating an endpoint.

// Example

import createApiRoute from "../utils/createApiRoute";
import requireUser from "../utils/requireUser";
import corsMiddleware from "../middleware/corsMiddleware"

export default createApiRoute({
    async get(req, res, ctx) {
        const user = await requireUser(req); // Throws on unauthenticated
        const todos = await ctx.db.getTodosForUser(user.id);

        res.json(todos);
    },
    async post(req, res, ctx) {
        const user = await requireUser(req); // Throws on unauthenticated
        const data = await todoSchema.parse(req.body); // Throws on invalid
        const todo = await ctx.db.createTodo(data);

        res.status(201).json(todo);
    },
    middleware: [
        corsMiddleware,
    ]
})

That looks great. This abstraction comes with a lot of features:

List of middleware
Custom error handling, just throw from the function or middleware
Custom context object provided for all handlers
Separated functions for each method
Automatic types, no more import { NextApiRequest, NextApiResponse } from "next";

This is just the top of the iceberg. Next up we start creating this abstraction and its full set of features.

Creating the abstraction

Our target is to create a createApiRouteCreator function which returns us with a createApiRoute function, similar to the above example. We create a separate factory function to allow for more customisation and looser coupling. This enables us to do the following:

Global middleware (unlike the previous example, the corsMiddleware function can be raised to be a global middleware function and to automatically run on all routes).
Local middleware (like the previous example, we can have middleware that only runs on a specific endpoint).
Global context object
Custom error handling

The simplest possible version

Let’s start by creating the simplest version of the abstraction. A function that allows us to use the separate handler functions for each HTTP method.

First off we create types to handle all allowed methods.

// /lib/api/allowedMethods.ts

export type AllowedMethod = "get" | "post" | "patch" | "put" | "delete";

export function isAllowedMethod(arg: any): arg is AllowedMethod {
  return (
    arg === "get" ||
    arg === "post" ||
    arg === "patch" ||
    arg === "put" ||
    arg === "delete"
  );
}

Next up we create the createApiRouteCreator function which returns us with the createApiRoute function. For now, the only argument we pass to the createApiRouteCreator function is unimplementedMethod which defines the handler for when the method does not exist.

// /lib/api/createApiRouteCreator.ts

import { NextApiRequest as Req, NextApiResponse as Res } from "next";
import { AllowedMethod, isAllowedMethod } from "./allowedMethods";

type CreateApiRouteCreatorArgs = {
  unimplementedMethod: (req: Req, res: Res) => any;
};

type CreateApiRouteArgs = {
  [method in AllowedMethod]?: (req: Req, res: Res) => any;
};

// The main constructor function which is used to construct our createApiRoute
// function.
export function createApiRouteCreator(args: CreateApiRouteCreatorArgs) {

  // The constructed createApiRoute function, which returns us with a handler
  // function that can be default exported from an API route.
  return function createApiRoute(options: CreateApiRouteArgs) {

    // The route handler
    return async function handler(req: Req, res: Res) {
      // Ensure method is an allowed method and use the correct handler.
      // If no handler
      const _method = req.method?.toLowerCase();

      // Use the correct handler based on the method or use the unimplemented
      // handler, when no handler available for method.
      const handler = isAllowedMethod(_method)
        ? options[_method] ?? args.unimplementedMethod
        : args.unimplementedMethod;

      // Run the handler
      await handler(req, res);
    };
  };
}

Now we can create our instance of the createApiRoute as follows.

// /lib/api/createApiRoute.ts

import { createApiRouteCreator } from "./createApiRouteCreator";

export const createApiRoute = createApiRouteCreator({
  unimplementedMethod(req, res) {
    res.status(405).json({ message: "Unimplemented" });
  },
});

And use it in our endpoint

// /pages/api/example.ts

import { createApiRoute } from "../../lib/api/createApiRoute";

export default createApiRoute({
  async get(req, res) {
    res.json({ value: "🚀" });
  },
  async post(req, res) {
    res.status(201).json({ message: "Thank you!" });
  },
});

It works! We can now use the createApiRoute as a simple abstraction that handles selecting the correct handler for us.

Let’s add a global context object

To add the global context object, we need to add it as an argument for the createApiRouteCreator function. Even better, the context can be different depending on the request, as long as it conforms to its given type.

Let’s start by adjusting the types. This is a great use case for TypeScript generics.

// /lib/api/createApiRouteCreator.ts

// ...

type CreateApiRouteCreatorArgs<Context> = {
  createContext(req: Req, res: Res): Context;
  unimplementedMethod: (req: Req, res: Res, ctx: Context) => any;
};

type CreateApiRouteArgs<Context> = {
  [method in AllowedMethod]?: (req: Req, res: Res, ctx: Context) => any;
};

// ...

Then we add it to the handler

// /lib/api/createApiRouteCreator.ts

// ...

export function createApiRouteCreator<Context>(
  args: CreateApiRouteCreatorArgs<Context>
) {
  return function createApiRoute(options: CreateApiRouteArgs<Context>) {
    return async function handler(req: Req, res: Res) {
      // Create the context object
      const context = args.createContext(req, res);

            // ... get the handler function ...

      // Run the handler with context
      await handler(req, res, context);
    };
  };
}

Next we adjust our created createApiRoute function to include a context object which provides access to a database in this example. The database we use in this example is a quick fake todos database.

// /lib/api/createApiRoute.ts

import { createApiRouteCreator } from "./createApiRouteCreator";
import { fakeDb } from "./fakeDb";

export const createApiRoute = createApiRouteCreator({
  unimplementedMethod(req, res) {
    res.status(405).json({ message: "Unimplemented" });
  },
  createContext() {
    return {
      db: fakeDb,
    };
  },
});

Now we can use it in the route

// /pages/api/todo.ts

import { createApiRoute } from "../../lib/api/createApiRoute";

export default createApiRoute({
  async get(req, res, ctx) {
    const todos = await ctx.db.getTodosForUser("1");
    res.json(todos);
  },
});

Adding middleware, both local and global

Let’s add support for local and global middleware. First off, we define a helper function to use middleware meant for express in our application.

// /lib/api/initMiddleware.ts

import { NextApiRequest as Req, NextApiResponse as Res } from "next";

type Middleware = (req: any, res: any, next: (error?: any) => void) => void;

export default function initMiddleware(
  middleware: Middleware
): (req: Req, res: Res) => Promise<void> {
  return (req: Req, res: Res) =>
    new Promise((resolve, reject) => {
      middleware(req, res, (result) => {
        if (result instanceof Error) {
          return reject(result);
        }
        return resolve(result);
      });
    });
}

Next we add options in the createApiRouteCreator for global middleware and createApiRoute for local middleware.

// /lib/api/createApiRouteCreator.ts

type CreateApiRouteCreatorArgs<Context> = {
    // ...
  middleware?: Array<(req: Req, res: Res) => Promise<void>>;
};

type CreateApiRouteArgs<Context> = {
  [method in AllowedMethod]?: (req: Req, res: Res, ctx: Context) => any;
} & {
  middleware?: Array<(req: Req, res: Res) => Promise<void>>;
};

And call all middleware in the route handler


// /lib/api/createApiRouteCreator.ts

// ...
export function createApiRouteCreator<Context>(
  args: CreateApiRouteCreatorArgs<Context>
) {
  return function createApiRoute(options: CreateApiRouteArgs<Context>) {
    return async function handler(req: Req, res: Res) {
      // Get all global and local middleware
      const middleware = [
        ...(args.middleware ?? []),
        ...(options.middleware ?? []),
      ];

      // Run each middleware in sequence
      for await (const mw of middleware) {
        await mw(req, res);
      }

            // ...
    };
  };
}

We can now apply global middleware as follows, such as enabling cors and a custom logger.

// /lib/api/createApiRoute.ts

import initMiddleware from "./initMiddleware";
import Cors from "cors";
import { NextApiRequest } from "next";

// Define new middleware
const corsMiddleware = initMiddleware(Cors());
const loggerMiddleware = async (req: NextApiRequest) => {
  console.log("Incoming", req.method, "request");
};

export const createApiRoute = createApiRouteCreator({
    // ...
    // Apply global middleware
  middleware: [corsMiddleware, loggerMiddleware],
});

And local middleware

// /lib/api/example.ts

import { createApiRoute } from "../../lib/api/createApiRoute";

export default createApiRoute({
    // ...
    middleware: [
        async (req, res) => {
            console.log("Called local middleware");
        }
    ]
});

Let’s add custom error handling

Let’s also address one of our biggest pain points when creating APIs. Error handling. We tackle the issue by allowing the user to add a custom error handler function as an argument to createApiRouteCreator which handles all errors in a user-defined way.

First we add the option to add an error handler to our createApiRouteCreator function. We then proceed by wrapping our entire handler function body in a try catch block and call the error handler in the catch block. (Note: if no error handler is defined, all errors will go uncaught).

// /lib/api/createApiRouteCreator.ts

type CreateApiRouteCreatorArgs<Context> = {
    // ...
    handleError?: (req: Req, res: Res, error: unknown) => void;
};

// ...
export function createApiRouteCreator<Context>(
  args: CreateApiRouteCreatorArgs<Context>
) {
  return function createApiRoute(options: CreateApiRouteArgs<Context>) {
    return async function handler(req: Req, res: Res) {
      try {
        // ...
      } catch (error: unknown) {
                // If an error handler exists, call it
        args.handleError?.(req, res, error);
      }
    };
  };
}

We can then define our custom error handler as follows

// /lib/api/createApiRoute.ts

export const createApiRoute = createApiRouteCreator({
    // ...
  handleError(req, res, error) {
    if (typeof error === "string") {
      return res.status(400).send({ message: error });
    }

    res.status(400).send({ message: "Something wen't wrong!" });
  },
});

Now we can throw errors in peace from our handlers. In the above example we allow throwing strings. This may not be a good practice, however provides a simple example. Let’s define a helper function to illustrate our example.

// /lib/api/requireUser.ts

import { NextApiRequest } from "next";

export async function requireUser(req: NextApiRequest) {
  const didFindUser = await new Promise<boolean>((r) => r(Math.random() < 0.5));

  if (!didFindUser) {
    throw "Unauthenticated";
  }

  return { id: "1" };
}

We can call this utility function which simply throws an error on unauthenticated, otherwise returns a user. In addition we can throw any custom errors, such as for validation.

// /pages/api/example.ts

// ...
import { requireUser } from "../../lib/api/requireUser";

export default createApiRoute({
  async get(req, res, ctx) {
    const user = await requireUser(req);
    const todos = await ctx.db.getTodosForUser(user.id);

    res.json({ todos });
  },
  async post(req, res) {
    if (typeof req.body !== "string" || req.body === "") {
      throw "Request body not a string or empty string";
    }

    res.status(201).json({ message: "Thank you!" });
  },
    // ...
});

Finishing comments

There we have it. A beautiful API that solves many problems developers face with the simple Next.js API routes. Error handling, middleware, context objects, if-else chains and switch statements.

However, this idea can be expanded upon and more features can easily be added on top of this abstraction. For example hooks that run before and after your request is handled, middleware that is specific to a single method, protected routes that automatically throw errors for unauthenticated errors and provide the user object in the context. The list goes on and depends a lot on the use case.

Already in this form, we have reduced a lot of code duplication and made the code much more expressive and declarative instead of imperative and unDRY.

If you use this abstraction or have any more ideas on how to expand on this, please do feel free to contact me!

Forem: Jussi Nevavuori

How to Deploy Astro on Google Cloud with Bitbucket.

Project repository

Requirements

This guide assumes

This guide does not include

This guide does not support

Step-by-step setup guide

1. Setup Google Cloud Project.

2. Creating your Storage Bucket

2.1. Configuring your Storage Bucket to be public to everyone

2.2. Customize Storage Bucket website configuration

3. Initial file upload

4. Enabling required APIs

5. Set up a Load balancer

5.1. Configure the Load Balancer Frontend

5.2. Configure the Load Balancer Backend

5.3. Finalizing the Load Balancer

5.4. Enabling compression

6. Connect your domain to the Load Balancer

7. Wait, up to 24 hours

8. Set up Bitbucket repository

8.1. Enable Bitbucket pipelines in your repository

9. Set up Google Cloud for Bitbucket pipelines

9.1. Creating a service account for Bitbucket pipelines

9.2. Creating a key for the service account

9.3. Base64 encoding the key

9.4. Uploading the key and other repository variables to Bitbucket

10. Set up Bitbucket pipelines

10.1. Creating the .env.example file

10.2. Uploading environment variables into Bitbucket

10.3. Utility script for pulling environment variables into build

10.4. Creating the pipeline

10.5. Applying the pipeline

11. Deployment options

11.1. Deploy automatically on code changes

11.2. Deploy manually

11.3. Deploy on a schedule

11.4. Deploy programmatically

11.4.1. Create repository access token

11.4.2. Formulating the API call

References and troubleshooting

Rich text and images with Contentful, Next.js and Zod

Read more

Setting up schemas for Contentful images and rich text

Providing all custom Contentful fields using the context object

Using the image and rich text field types

Consuming rich text and images

That’s it.

How to optimise and customise your Contentful images with TypeScript

ImageSrc function for Contentful images with TypeScript

The TypeScript part: Creating types for the image API

Getting the base URL from the src object

The hard part: Converting the options object into a query string

Combining the src and options

There you have it.

How to use Contentful with Next.js and Zod

Step 1 - Setup your Contentful workspace and client

Step 2 - Set up Zod schemas for typesafety

Step 3 - Creating createContentfulModel

Step 4 - Inferring the types

Step 5 - Consuming the models

Conclusion

In the next article

Hosting a static site on an FTP server with Next.js examples

What kind of content can you host?

What is FTP?

Step 1: Build your project

Step 2: Setup custom JavaScript script for deploying

Step 3: Setup a .env file with your FTP credentials

Step 4: Flesh out the deployment script

You’re done.

Potential issues

End-to-end Typesafe APIs with TypeScript and shared Zod schemas

Why use Zod?

Defining a schema and its auto-generated types

Typesafe fetching with your new schema and types!

Updating and creating a todo item

Let’s review

Persist your state anywhere with createPersistentItem with React examples

10.1. Creating the `.env.example` file

Accessing Global Props in `getStaticProps`

The `createApiRoute` abstraction