Using Constructs

Build monitoring infrastructure with reusable TypeScript classes

Every resource you create using the Checkly CLI is represented by a “construct”: it’s a class you import from checkly/constructs, for instance an ApiCheck or EmailAlertChannel. A construct is the “as-code” representation of the eventual resource created / deleted / updated on the Checkly cloud once you run npx checkly deploy.

api.check.ts

TypeScript

import { ApiCheck, AssertionBuilder } from 'checkly/constructs'

new ApiCheck('api-health-check', {
  name: 'API Health Check',
  request: {
    url: 'https://danube-web.shop/api/books',
    method: 'GET',
    assertions: [
      AssertionBuilder.statusCode().equals(200),
    ],
  },
})

The Checkly CLI supports JavaScript and TypeScript. The documentation focuses on TypeScript, because we recommend using TypeScript for a better developer experience.

Test this API check with npx checkly test and transform it to production monitoring with npx checkly deploy.

Project Structure

• checkly.config.ts - Mandatory global project and CLI configuration. We recommend using TypeScript.
• src/__checks__/* - TS/JS files defining your checks and other resources.
• package.json - Standard NPM project manifest.

Here is an example directory tree of what that would look like:

.
|-- checkly.config.ts
|-- package.json
`-- src
    `-- __checks__
      |-- alert-channels.ts
      |-- api-check.check.ts
      `-- homepage.spec.ts

The checkly.config.ts at the root of your project defines a range of defaults for all your checks.

Project Configuration

As your project grows, you will want to override these defaults for specific checks or check groups. The recommended way to tackle this is using a mix of global and local configuration.

Global Configuration

As mentioned, your global checkly.config.ts holds a set of defaults for your project, checks, and some CLI commands. Use defineConfig to configure your Checkly project.

checkly.config.ts

TypeScript

import { defineConfig } from "checkly"
import { Frequency } from "checkly/constructs"

export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  repoUrl: "https://github.com/you/your-project",
  checks: {
    activated: true,
    muted: false,
    runtimeId: "2025.04",
    frequency: Frequency.EVERY_5M,
    locations: ["us-east-1", "eu-west-1"],
    tags: ["website", "api"],
    checkMatch: "**/*.check.ts",
    browserChecks: {
      frequency: Frequency.EVERY_10M,
      testMatch: "browsers/**/*.spec.ts",
    },
    multiStepChecks: {
      testMatch: "multistep/**/*.spec.ts",
    },
  },
  cli: {
    runLocation: "eu-west-1",
  },
})

Find a full reference of all project properties in the Project construct section.

Local Configuration

Override any of the checks global configuration settings at the individual check level.

__checks__/api.check.ts

TypeScript

import { ApiCheck, AssertionBuilder, Frequency } from 'checkly/constructs'

new ApiCheck('books-api', {
  name: 'Books API',
  locations: ['ap-south-1'], // overrides the locations property
  frequency: Frequency.EVERY_30M, // overrides the frequency property
  request: {
    method: 'GET',
    url: 'https://danube-web.shop/api/books',
    assertions: [AssertionBuilder.statusCode().equals(200)],
  },
})

Find a full reference of all check properties in the ApiCheck construct or BrowserCheck construct section.

Logical IDs

Assigning a logicalId is crucial when creating a construct. Remember the following rules when creating and updating constructs:

1. Every construct needs to have a logicalId. This is the first argument when instantiating a class, i.e.

const check  = new ApiCheck('my-logical-id', { name: 'My API check' })

2. Every logicalId needs to be unique within the scope of a Project.
3. A Project also has a logicalId. This needs to be unique within the scope of the Checkly account.
4. A logicalId can be any string up to 255 characters in length.
5. There is no hard limit on the amount of Projects you can have in your Checkly account.

Behind the scenes, we use the logicalId to create a graph of your resources so we know what to persist, update and remove from our database. Changing the logicalId on an existing resource in your code base will tell the Checkly backend that a resource was removed and a new resource was created.

When using the Checkly CLI to manage multiple projects and repositories, each project’s logicalId should be unique within the Checkly account. The project’s logicalId is used during the Checkly CLI commands to detect exactly which project is being used. If multiple projects are using the same project logicalId, deploying one project will delete the checks that were deployed by another project. The project logicalId can be configured in the project’s global configuration.

When changing the logical ID of a project you will keep all resources on your Checkly account, unless you run npx checkly destroy to remove the old project.

Programming with Constructs

All resources you can create and manage using the Checkly CLI are derived from “constructs”. These constructs are just TypeScript classes.

You can use standard JS/TS programming to use these constructs to create the monitoring setup of your choice. Loops, variables, if-statements, file imports, extensions etc. Here are some examples.