{"id":21815398,"url":"https://github.com/jpal91/checkly-nextjs-example","last_synced_at":"2026-04-07T18:32:51.235Z","repository":{"id":264921287,"uuid":"894659088","full_name":"jpal91/checkly-nextjs-example","owner":"jpal91","description":"A basic example of how to add Checkly browser tests into a repository","archived":false,"fork":false,"pushed_at":"2024-11-29T03:52:58.000Z","size":306,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-03T16:28:13.782Z","etag":null,"topics":["checkly","github-actions","makefile","monitoring","monitoring-automation","terraform"],"latest_commit_sha":null,"homepage":"https://checkly-nextjs-example.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jpal91.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-26T18:45:21.000Z","updated_at":"2024-12-03T16:47:02.000Z","dependencies_parsed_at":"2025-03-21T09:46:07.096Z","dependency_job_id":"174d7bd7-e2d2-4b6d-8290-8eda4ae73352","html_url":"https://github.com/jpal91/checkly-nextjs-example","commit_stats":null,"previous_names":["jpal91/checkly-nextjs-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jpal91/checkly-nextjs-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpal91%2Fcheckly-nextjs-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpal91%2Fcheckly-nextjs-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpal91%2Fcheckly-nextjs-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpal91%2Fcheckly-nextjs-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpal91","download_url":"https://codeload.github.com/jpal91/checkly-nextjs-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpal91%2Fcheckly-nextjs-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31524525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["checkly","github-actions","makefile","monitoring","monitoring-automation","terraform"],"created_at":"2024-11-27T15:18:34.934Z","updated_at":"2026-04-07T18:32:51.201Z","avatar_url":"https://github.com/jpal91.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Checkly Next.js Example\n\n![](https://api.checklyhq.com/v1/badges/checks/64e27fc6-edbc-4799-921e-fd39b1153841?style=flat\u0026theme=dark)\n\n![Picture of repo web page](./assets/webpage-pic.jpg)\n\n## Table of Contents\n\n- [Intro](#intro)\n- [Getting Started](#getting-started)\n  - [Manual Setup](#manual-setup)\n  - [Environment Variables](#environment-variables)\n- [Checks](#checks)\n  - [Configuration](#configuration)\n  - [Browser](#browser)\n- [Alerts](#alerts)\n  - [Try to Fail!](#try-to-fail)\n- [CI/CD](#cicd)\n  - [Make](#make)\n  - [GitHub Actions](#github-actions)\n  - [Terraform](#terraform)\n  - [Other Integrations](#other-integrations)\n- [Special Thanks](#special-thanks)\n\n## Intro\n\nThe purpose of this repository is to show an example application that utilizes [Checkly](https://checklyhq.com) for automated `Monitoring-as-Code`. While Checkly does offer the ability to interact with their service via their website, as an application grows, keeping code together becomes more important.\n\nIn this example, you will see how you can integrate [browser checks](https://www.checklyhq.com/docs/browser-checks/) directly into your code base, how to configure/receive alerts when a check has failed, as well as several examples of how to integrate your checks within a CI pipeline.\n\nThe scope of this project relative to all the possibilities as it comes to checks and integration is small. Hopefully, it opens up some ideas on how to integrate this awesome service into your code base. Don't hesitate to [check the docs](https://www.checklyhq.com/docs/browser-checks/) to learn about other checks, alerts, and CI integrations as well!\n\n## Getting Started\n\nFirst, clone the repo:\n\n```bash\ngit clone https://github.com/jpal91/checkly-nextjs-example\n```\n\nAfter, you need to set up the project with the necessary dependencies.\n\nThis project comes with a `make` file that has several helper commands. If you have `make`, simply run:\n\n```bash\nmake init\n```\n\nIf you don't have `make` installed, navigate down to [Manual Setup](#manual-setup) and go from there.\n\n\u003e [!TIP]\n\u003e\n\u003e Run `make help` to see all commands\n\nThis command will walk you through installing all necessary project dependencies.\n\nOnce everything is installed, run:\n\n```bash\npnpm dev # or npm run dev\n```\n\nThis will start the development server at `localhost:3000`. Navigate to the browser and check it out!\n\nThe website is a simple example of a form with a little validation, and redirect on submit (the data doesn't actually go anywhere, though). Just enough to add some basic tests that we can use for this example.\n\nOnce you're done there, try out testing from the command line:\n\n```bash\nmake test\n# OR\npnpm exec checkly test\n```\n\nThen deploy your tests!\n\n```bash\nmake deploy\n# OR\npnpm exec checkly deploy\n```\n\n### Manual Setup\n\nIf you do not have `make` installed on your local computer, run the following instead:\n\n```bash\ngit remote remove origin\ncp .env.sample .env.local\npnpm install # or npm install if you prefer\npnpm add -g vercel\npnpm exec checkly login # or npx\nvercel login\n```\n\nAll `Next.js` dependencies will be installed which does also include the Checkly CLI as a dev dependency. The `vercel` CLI is added on to simulate manually deploying via the command line.\n\n### Environment Variables\n\nThis repo comes with a [sample .env file](.env.sample) which shows the environment variables used in the project. Depending on what route(s) you take as it comes to testing/CI, you may need some (or maybe none) of these variables set.\n\n\u003e [!NOTE]\n\u003e\n\u003e An included `make` command in this repo, `sync-secrets` can help by adding all set variables in `.env.local` to Checkly.\n\nA few notes on the variables -\n\n1. **CHECKLY_API_KEY** and **CHECKLY_ACCOUNT_ID** - When logged in to Checkly via the command line, these will be included in the environment for you, so you can safely ignore setting them. However, if you want to try out the [Terraform](#terraform) or [GitHub](#github) implementations in this project, you will have to set them, as the building/testing will occur outside of your local environment.\n2. **CHECKLY_ALERT\\_\\***\\* - Any variables with `ALERT` refer to sensitive information that will be included in the environment to reference where to send alerts to (ie email addresses or phone numbers). See [Alerts](#alerts) for more details.\n3. **ENVIRONMENT_URL** - Used by Checkly as the target for testing when running `npx checkly test` from the command line. When using `make vercel-build`, the `ENVIRONMENT_URL` will be automatically updated with the latest preview build's url from `vercel`. If using different means of interacting with this package, you'll want to explicitly state this or it will point to/test for the project's current url [https://checkly-nextjs-example.vercel.app](https://checkly-nextjs-example.vercel.app).\n4. **VERCEL_BYPASS_TOKEN** - By default, Vercel will require a user visiting a page to be authenticated with Vercel. This will prevent CI tools (ie [GitHub Actions](#github-actions)) from being able to run tests on the site. **You can turn this functionality off in the project settings via the Vercel Dashboard**. Learn more about bypass protection [on the Vercel website](https://vercel.com/docs/security/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation).\n\n\u003e [!TIP]\n\u003e\n\u003e Notes have been added at the top of certain sections to provide hints for what env variables may be needed.\n\n## Checks\n\nThe Checkly `playwright` tests and checks for this project reside in the [`__checks__`](./__checks__) directory of the repo. The configuration file can be found at the root, [`checkly.config.ts`](./checkly.config.ts).\n\nHousing the files in `__checks__` is common practice, however, you can specify any place to put your checks by specifying a `glob` pattern in the `checkly.config.ts` like so:\n\n```ts\n// checkly.config.ts\nexport default defineConfig({\n    ...\n    tags: [\"website\", \"api\"],\n    checkMatch: \"**/__checks__/**/*.check.ts\", // checkly cli looks for any checks here (could be browser, api, heartbeat, etc.)\n    ignoreDirectoriesMatch: [\n    ...\n    browserChecks: {\n      frequency: Frequency.EVERY_30M,\n      testMatch: \"**/__checks__/**/*.spec.ts\", // also here for browser playwright tests\n    },\n    ...\n})\n```\n\nAny new checks added to this directory will be automatically included when running Checkly tests/deploys.\n\n### Configuration\n\nIn the configuration file you'll find several default values that will apply to checks unless otherwise specified (see [Browser](#browser) for details).\n\nYou can also add specific `playwright` configurations to the options as well. Not all options are supported though, see the page on [global configuration](https://www.checklyhq.com/docs/browser-checks/playwright-test/#global-configuration) for further details.\n\n```ts\n// checkly.config.ts\nexport default defineConfig({\n\t...\n    playwrightConfig: {\n      use: {\n        baseURL:\n          process.env.ENVIRONMENT_URL! ||\n          \"https://checkly-nextjs-example.vercel.app\",\n      },\n    },\n    browserChecks: {\n      frequency: Frequency.EVERY_30M,\n      testMatch: \"**/__checks__/**/*.spec.ts\",\n    }\n    ...\n })\n```\n\nFor more details on the options you can pass in to the `config` visit the [Project Construct](https://www.checklyhq.com/docs/cli/constructs-reference/#project) page.\n\nHaving this file is **required** for the CLI to run properly, pick up tests within the repo, and deploy them to Checkly.\n\n### Browser\n\nThe main checks for this project are in the [`browser.spec.ts`](./__checks__/browser.spec.ts) file with the check's configuration at [`browser.check.ts`](./__checks__/browser.check.ts).\n\nThe tests in `spec.ts` are relatively simple, just a quick demonstration of some `playwright` tests that would be picked up by the Checkly CLI.\n\nThe configuration in `check.ts` demonstrates how you can override specific variables named in the `checkly.config.ts` file. For example, the main `config` has browser checks running every 30 minutes, while the `browser.check` defines the frequency at every 10 minutes. This will be the final value as it is more targeted.\n\n```ts\n// __checks__/browser.check.ts\nnew BrowserCheck(\"browser-spec-ts\", {\n\t...\n\ttags: [\"website\", \"api\"],\n\tfrequency: Frequency.EVERY_10M,\n\tenvironmentVariables: [],\n  ...\n})\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e `check.ts` files are _not required_ for browser checks, but recommended. If not included for a specific test file, the defaults from `checkly.config.ts` will be used\n\n## Alerts\n\nCheckly has [several methods](https://www.checklyhq.com/docs/alerting-and-retries/alert-channels/) of sending alerts when something goes wrong. These can also be configured via JavaScript/TypeScript directly in your configuration. These alerts can also be defined on a global or per check basis as well.\n\nNavigating to [`fail.check.ts`](./__checks__/fail/fail.check.ts), you can see an example of how alerts can be configured on a specific check:\n\n```ts\n// __checks__/fail/fail.check.ts\nconst sendDefaults = {\n  sendFailure: true,\n  sendRecovery: true,\n  sendDegraded: false,\n};\n...\nnew BrowserCheck(\"fail-spec-ts\", {\n  ...\n  code: {\n    entrypoint: \"./fail.spec.ts\",\n  },\n  retryStrategy: RetryStrategyBuilder.noRetries(),\n  alertChannels: [\n    new SmsAlertChannel(\"sms-alert-1\", {\n      phoneNumber: process.env.CHECKLY_ALERT_PHONE_NUMBER!,\n      ...sendDefaults,\n    }),\n  ],\n});\n```\n\nNow because the global `checkly.config.ts` has `alertChannels` set for email and the `fail` check has channels set for SMS, which will a user receive? The answer is **JUST** a text message as that was the only one specified in the check. If you want to add emails on, you need to add the email construct to the check as well. However, if nothing was specified in the `fail.check.ts` for `alertChannels`, you would receive an email as that is the stated default from the `config`.\n\n\u003e [!NOTE]\n\u003e\n\u003e The [Construct Reference](https://www.checklyhq.com/docs/cli/constructs-reference/) guide can show you the specific arguments to pass into each check when writing the checks via JavaScript/TypeScript.\n\n### Try to Fail!\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e This section assumes you are logged in to Checkly and Vercel via the command line. You can do this manually through the dashboard as well by copying the `spec` code into a new check.\n\u003e\n\u003e Required env variables:\n\u003e\n\u003e 1. CHECKLY_ALERT_PHONE_NUMBER\n\u003e 2. CHECKLY_ALERT_EMAIL\n\nHow often do you get to break things on purpose? Well today you can!\n\nIf you're curious about what would happen if a test failed, you can deploy this check that will absolutely fail and you're guaranteed[^1] to receive alert.\n[^1]: Well you should...\n\nFirst a small change in `checkly.config.ts`:\n\n```ts\nexport default defineConfig({\n\t...\n\tcheckMatch: \"**/__checks__/**/*.check.ts\",\n\tignoreDirectoriesMatch: [\n\t\t// Comment this next line out\n\t\t// \"**/__checks__/fail/*,\n\t],\n\t...\n})\n```\n\nThis will make sure the `config` picks up this directory when deploying. Then run:\n\n```bash\nmake trigger-fail\n\n# OR\n\npnpm exec checkly deploy --force\n# Wait about 10 seconds or so\nsleep 10\n# Clean up\npnpm exec checkly destroy --force\n```\n\nWhile `sleep` is running, you should notice that familiar buzz in your pocket. Try out some of the other options as well!\n\nFinally, **remember to undo the comments!**\n\n## CI/CD\n\nThis project features a few different examples and ways you can integrate Checkly directly from the command line. This goes from the simple(er) setup of using a command line tool like `make`, to integrating your app with third party providers like GitHub, and even adding `terraform`!\n\n\u003e [!NOTE]\n\u003e\n\u003e Keep in mind, the examples you see within are just that. These have not been heavily tested in a production environment and should serve more as _guides_ rather than production ready code.\n\n### Make\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e This section assumes you're logged in to Checkly and Vercel via CLI and won't work otherwise.\n\u003e Other than the [VERCEL_BYPASS_TOKEN](#environment-variables) (if applicable), all other variables are optional.\n\nThe [`Makefile`](./Makefile) in this repo shows an example of how you could run a basic CI process right from your local computer:\n\n```makefile\n# make vercel-deploy\nvercel-deploy: vercel-build-prev vercel-deploy-prev\n\t@echo \"\\n---Running Checkly Tests---\\n\"\n\t$(call pm_exec,checkly test -r github --record -e ENVIRONMENT_URL=$(shell cat deployment-url.txt)) || exit 1\n\tvercel promote\n\t@echo \"\\n---Deploying to production---\\n\"\n\t$(call pm_exec,checkly deploy --force)\n\n\n# Which expands to...\n\necho \"\\n---Building Preview---\\n\"\nvercel build\necho \"\\n---Deploying to Vercel---\\n\"\nvercel deploy --prebuilt \u003e deployment-url.txt\necho \"\\n---Running Checkly Tests---\\n\"\npnpm exec checkly test -r github --record -e ENVIRONMENT_URL=** || exit 1\nvercel promote\necho \"\\n---Deploying to production---\\n\"\npnpm exec checkly deploy --force\n```\n\n#### Steps\n\n1. A preview build is initiated via `vercel build`.\n2. The preview is deployed and the output value is the new preview's url that we will use as the `ENVIRONMENT_URL` to test with Checkly.\n3. We initiate the check, adding the new `ENVIRONMENT_URL` as an argument.\n4. If the test fails, we stop immediately. Since this is just a preview build, we don't have to worry about rolling anything back.\n5. If successful, we promote the build to production, and deploy our checks to Checkly.\n\n### GitHub Actions\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e Required (in GitHub secrets):\n\u003e\n\u003e 1. CHECKLY_API_KEY\n\u003e 2. CHECKLY_ACCOUNT_ID\n\u003e 3. VERCEL_BYPASS_TOKEN (if applicable)\n\nUsing GitHub Actions you can automate you process so you won't have to run any other commands other than pushing your commits to your GitHub repo. The example included in this repo [`checkly.yml`](./.github/workflows/checkly.yml) follows the [example guide](https://www.checklyhq.com/docs/cicd/github-actions/) on the Checkly website fairly closely. So please feel free to check that page for additional reference.\n\nA few things to note:\n\n```yml\nname: \"checkly\"\non: [deployment_status]\n```\n\nThis action is making the assumption that your deployment is handled automatically by the [Vercel/GitHub Deployment](https://vercel.com/docs/deployments/git/vercel-for-github#configuring-for-github) integration, which is the recommended way to deploy a Vercel project.\n\n\u003e **Set Up Vercel Integration**\n\u003e\n\u003e Navigate to your [Vercel](https://vercel.com) account dashboard. You should see a button `Add New` near the top right.\n\u003e\n\u003e ![Vercel Add New Button](./assets/vercel-add-new.jpg)\n\u003e\n\u003e Follow the instructions given to link your GitHub account with Vercel and select your repo from the given list.\n\u003e\n\u003e With this integration, every time you commit, Vercel will deploy a new build. By default, production builds on `main`, and preview builds on other branches.\n\nWhen Vercel deploys, it sends a `deployment_status` event which will trigger this workflow. This allows us to check the deployment against our tests, and to deploy our checks if everything passes and if we're in production (ie pushing to `main`):\n\n```yml\n- name: Deploy checks # if the test run was successful and we are on Production, deploy the checks\n  id: deploy-checks\n  if: steps.run-checks.outcome == 'success' \u0026\u0026 github.event.deployment_status.environment == 'Production'\n  run: pnpm exec checkly deploy --force\n```\n\n### Terraform\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e Required:\n\u003e\n\u003e 1. CHECKLY_API_KEY\n\u003e 2. CHECKLY_ACCOUNT_ID\n\u003e 3. VERCEL_BYPASS_TOKEN (if applicable)\n\nAlthough Terraform isn't strictly a `CI` tool, it can be used in conjunction with other tools to maintain the architecture of your application.\n\nIn [`main.tf`](./main.tf) you'll find an example of what this could look like with the Checkly Terraform integration:\n\n```hcl\n\nresource \"checkly_check\" \"browser-check\" {\n  name      = \"Checkly Next.js Example Browser Check\"\n  type      = \"BROWSER\"\n  activated = true\n  frequency = 10\n  locations = [\n    \"us-east-1\",\n    \"eu-west-1\"\n  ]\n\n  alert_settings {\n    escalation_type = \"RUN_BASED\"\n\n    run_based_escalation {\n      failed_run_threshold = 1\n    }\n  }\n\n  alert_channel_subscription {\n    channel_id = checkly_alert_channel.email_alert_1\n    activated  = true\n  }\n\n  script = data.local_file.test_script.content\n}\n```\n\nDefining checks in this way replaces the need for most of the `config` and check files in your repo. You could actually replace all of the `__checks__` folder by writing the script directly into the `tf` doc. Depending on how your project is set up, this could be beneficial as you could define your checks as a part of your infrastructure along with needed cloud services, web app servers, etc.\n\nA simple `cli` example of how you could build and deploy all on the command line:\n\n```bash\n# Build and test\nvercel build\nurl=\"${vercel deploy --prebuilt}\"\npnpm exec checkly test -e ENVIRONMENT_URL=${url}\n\n# Run terraform commands\nterraform init\nterraform plan\nterraform apply\n\n# Promote to production\nvercel promote\n```\n\n### Other Integrations\n\nSince Checkly can be interacted with via [API](https://developers.checklyhq.com/reference/), the possibilities are endless as it comes to CI options. Other examples that are not included in this repo are:\n\n- [GitLab CI](https://www.checklyhq.com/docs/cicd/gitlabci/)\n- [Jenkins](https://www.checklyhq.com/docs/cicd/jenkins/)\n- [Vercel](https://www.checklyhq.com/docs/cicd/vercel/) (not cli)\n- [GitHub Deployments](https://www.checklyhq.com/docs/cicd/github/)\n\n## Special Thanks\n\n- The team at [Checkly](https://checklyhq.com) for providing the service/documentation to make this repo possible.\n- [StackEdit](https://stackedit.io/) for their awesome in-browser Markdown editor.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpal91%2Fcheckly-nextjs-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpal91%2Fcheckly-nextjs-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpal91%2Fcheckly-nextjs-example/lists"}