Using Constructs

Build monitoring infrastructure with reusable TypeScript classes

Constructs are JavaScript/TypeScript classes that represent your all monitoring resources. Import them from checkly/constructs to create checks, alert channels, and other resources in code.

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

Configure your Checkly project by creating and editing the checkly.config.ts. The configuration file enables you to set default settings like monitoring locations, configure alert settings and organize your Checkly files to match your project requirements.

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

We recommend separating your monitoring resources from your application code using the __checks__ path convention. However, it’s up to you to define where your monitoring setup will be configured.

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

Your global checkly.config holds a set of defaults for your 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 configuration section.

Local Configuration

Override any of the checkly.config 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

Every construct requires a unique logicalId as its first parameter. This ID tracks resources across deployments and updates.

Key rules:

• IDs must be unique within your project
• Changing an ID creates a new resource and removes the old one
• IDs can be any string up to 255 characters

api-check.ts

// Good: descriptive, unique IDs
new ApiCheck('homepage-api-check', { /* ... */ })
new ApiCheck('user-auth-check', { /* ... */ })

// Bad: duplicate IDs will cause errors
new ApiCheck('check-1', { /* ... */ })
new ApiCheck('check-1', { /* ... */ }) // ❌ Duplicate ID

Programming with Constructs

Constructs are JavaScript/TypeScript classes that you can initialize programmatically. Use standard programming patterns:

api-check.ts

// Share alert channels across checks
const alertChannel = new EmailAlertChannel("team-alerts", {
  address: "[e-mail]",
})

// Define your endpoints
const endpoints = ["/api/books", "/api/books/22"]

// Create a new check for each endpoint
endpoints.forEach(
  (endpoint) =>
    new ApiCheck(`${endpoint.replace("/", "-")}-check`, {
      name: `${endpoint} Check`,
      request: {
        method: "GET",
        url: `https://danube-web.shop/${endpoint}`,
      },
      alertChannels: [alertChannel],
    })
)

Next Steps

Each construct has detailed documentation with examples, configuration options, and best practices. Start with the construct type you need, and start configuring your monitoring infrastructure in code.