Next.js & Checkly Starter Template

This repo showcases a simple Next.js app, hosted on Vercel, that uses Checkly to run checks before and after deployment in CI. It includes the following features:

1. A Next.js app that fetches data from the /api/greetings endpoint and displays it on the landing page.
2. Checkly checks in the __checks__ directory verify if the page loads and if the API responds correctly.
3. The necessary Checkly CLI and GitHub Actions configuration to run these checks in CI.

Quickstart

1. Fork this repo or click the "Use this template" button in the top right corner.

2. Clone the repo and run npm install.

   git clone https://github.com/checkly/nextjs-checkly-starter-template.git
   cd nextjs-checkly-starter-template
   npm i

3. Deploy the app to Vercel. You should now have a stable, production Vercel URL for your app similar to https://nextjs-checkly-starter-template-checkly.vercel.app/

4. Copy and paste that URL into the .env file as the PRODUCTION_URL value, e.g.

   PRODUCTION_URL="YOUR VERCEL PRODUCTION URL"
   

   Now we know where to aim our production checks.

5. Make sure you have a Checkly account. Just run this command and follow the instructions:

   npx checkly login

6. Run your checks in the Checkly cloud with the following commands:

   npx checkly test --env-file "./.env" --record

   This will run the checks in the __checks__ directory and record them in your Checkly account as test session. You can now see them in the Checkly test sessions dashboard.

7. To deploy your checks as monitors, run the following commands:

   npx checkly env add "PRODUCTION_URL" "<YOUR VERCEL PRODUCTION URL>"

   This command persists the PRODUCTION_URL to the Checkly cloud.

   npx checkly deploy

   This command deploys the checks in the __checks__ directory as monitors in your Checkly account. You can now see them in the Checkly home dashboard.

2. Running Checks before & after Deployment in CI

You can run your Checkly checks right after any Vercel Preview Deployment and then deploy your checks as monitors on Checkly. This is a powerful strategy to make sure your never ship critical breaking errors to Production, while at the same time surfacing any outages in your Production Deployments.

2.1 Bypassing Vercel Preview Deployment Protection

By default, Vercel Preview Deployments are protected and only accessible by logged-in users. However, we want to access any Preview Deployment with our Playwright-powered Checkly checks. To do this, we need to bypass the protection.

For the sake of this example repo, you can just disable this protection in the Settings / Deployment Protection section in your Vercel project.

In a real-world scenario, you would create a Vercel protection bypass token and use that in your Checkly scripts to authenticate against the Preview Deployment.

2.2 Setting up GithHub Actions

This example uses GitHub Actions. Check out the workflow in .github/workflows/checkly.yml but you can any other CI platform. We have example configs for Jenkins and GitLab CI in our docs.

1. Create an API key in the API keys section of your Checkly account
2. Take a note of your Checkly Account ID in the General section of your Checkly account
3. Save your API key and Account ID as CHECKLY_API_KEY and CHECKLY_ACCOUNT_ID as secrets in your GitHub Actions configuration.

Now, on every deployment webhook that GitHub receives from Vercel, the GitHub Actions workflow will run the checks in the __checks__ directory.

• A markdown formatted report will be posted as a comment in the GitHub Actions summary.
• Preview Deployments are tested against the generated preview deployment URL and recorded as test sessions in Checkly.
• Production Deployments are tested against the production URL and deployed as monitors in Checkly if all checks pass.

Links:

• Checkly docs on Test Sessions
• Checkly docs on GitHub Actions integration
• Vercel docs on running tests

Notes

This is a Next.js project bootstrapped with create-next-app and edited where needed.