Deploy Next.js to Cloud Run with ISR support

This is a repository for a scalable web application using Next.js and TailwindCSS along with Jest, Cypress and Storybook preconfigured.

There are some helper scripts and tooling utilities configured in package.json and tools/scripts to test the workspace or add new features.

The project also uses husky commit hooks with cz-git.

Requirements

To setup this project, following dependencies will be needed:

• Linux based operating system (or WSL on Windows)
• Node.js 16

Installation

With the required dependencies setup, simply run:

yarn

For convenience, installing nx globally using npm is recommended:

npm i -g nx

Afterwards, the project is fully manageable using the nx CLI.

NxCloud

Usage of NxCloud and its distributed caching, task execution and code generation is highly recommended.

nx connect

Then add the following cacheable operations to tasksRunnerOptions.default.options.cacheableOperations in nx.json:

{
    "tasksRunnerOptions": {
        "default": {
            "runner": "@nrwl/nx-cloud",
            "options": {
                "cacheableOperations": [
                    "lint",
                    "build",
                    "test",
                    "e2e",
                    "image",
                    "docker",
                    "deploy"
                ],
                "accessToken": "<YOUR_ACCESS_TOKEN>"
            }
        }
    }
}

Running

nx start web # run the web app

Developing

There are two helper scripts which can generate a new component or page in the libs/shared library.

yarn component login-button

This will generate the LoginButton component as libs/shared/src/components/login-button/login-button.tsx along with Jest and Storybook test files and export it from the shared library.

Afterwards, you can use the component in all your apps by importing it with:

import { LoginButton } from '@shared';

Semantic Versioning

When committing, you will get a prompt which will generate conventional commits and lint the commits using commitlint.

Additionally, a target to generate the CHANGELOG.md and calculate a new version based on the conventional commits can be run with:

yarn bump

Testing

The following scripts help to test the workspace and take the amount of cores to use as an optional argument:

yarn format  # format the entire workspace
yarn full 8  # test all targets
yarn ci 8    # test only affected targets
yarn debug 8 # test only failed targets

Storybook

nx start sb # run storybook

Cypress

nx e2e web # run cypress for web app

Deployment

By default, the pipeline only runs a setup job. Uncomment the remaining jobs in .github/workflows/ci.yml to activate it.

The pipeline uses NxCloud Distributed Task Execution, so NxCloud usage is required and highly recommended.

On pull requests, apps get deployed to development projects and after a merge to the main branch, the apps get built and released using semantic versioning and deployed to production.

For the web app, the CI will copy a standalone Next.js server in a Docker image, push the image to Google Artifact Registry and deploy the image with Google Cloud Run.

Google Cloud Storage will be mounted inside the container using gcsfuse and sync the changes generated by the ISR feature of Next.js.

Additonally, a CDN will be setup so the static assets can be served via CDN.

Afterwards, a cleanup job is run which deletes all images except for the most recent image to stay in the free tier usage of the artifact registry.

Prerequisites

• Authorized gcloud CLI
• Docker buildx engine
• Terraform

A repository secret REPO_GITHUB_TOKEN with write permissions to the repository is required for the pipeline.

Setup

To deploy via CI/CD, you need to first create a GCP organization and obtain a domain. The domain needs to be verified in the GCP admin console.

Then, a billing account needs to be created and enabled.

With this configured, the gcloud CLI needs to be installed and configured by running gcloud auth application-default login.

Then, you have to fill in the values of your organization for Terraform.

Update the default values in:

• libs/infra/workload_identity_federation/data/variables.tf
• apps/web/infra/development/variables.tf
• apps/web/infra/productin/variables.tf
• apps/web/scripts/image.sh (add project ids)
• apps/web/scripts/deploy.sh (add project ids)

Then you can run nx deploy to setup workflow identity federation infrastructure.

Running nx setup will also configure isolated Terraform state backends.

If the values for your GCP projects are configured correctly, you will be shown further instructions. The script will tell you which value to set as repository secrets and which DNS entries to add to your domain for the Cloud Run service.

To scale the CI horizontally, simply update the NX_CLOUD_DISTRIBUTED_EXECUTION_AGENT_COUNT environment variable in .github/workflows/ci.yml to the required amount of agents.

If you do not want to deploy the applications, remove the deployment jobs from the workflow and update the cleanup job to depend on the release job instead.