> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-paula-tree-202-entitlements-group-troubles.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup dropdown>
  ```ts api.check.ts theme={null}
  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),
      ],
    },
  })
  ```

  ```js api.check.js theme={null}
  const { ApiCheck, AssertionBuilder } = require("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),
      ],
    },
  })
  ```
</CodeGroup>

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

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.

<Tabs>
  <Tab title="Global Configuration">
    Your global `checkly.config` holds a set of defaults for your project.

    <CodeGroup dropdown>
      ```ts checkly.config.ts theme={null}
      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",
        },
      })
      ```

      ```js checkly.config.js theme={null}
      const { defineConfig } = require("checkly")
      const { Frequency } = require("checkly/constructs")

      module.exports = 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.js",
          browserChecks: {
            frequency: Frequency.EVERY_10M,
            testMatch: "browsers/**/*.spec.js",
          },
          multiStepChecks: {
            testMatch: "multistep/**/*.spec.js",
          },
        },
        cli: {
          runLocation: "eu-west-1",
        },
      })
      ```
    </CodeGroup>

    Find a full reference of all project properties in [the `Project` configuration section](/constructs/project).
  </Tab>

  <Tab title="Local Configuration">
    Override any of the `checkly.config` settings at the individual check level.

    <CodeGroup dropdown>
      ```ts __checks__/api.check.ts theme={null}
      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)],
        },
      })
      ```

      ```js __checks__/api.check.js theme={null}
      const { ApiCheck, AssertionBuilder, Frequency } = require("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)],
        },
      })
      ```
    </CodeGroup>

    Find a full reference of all check properties in [the `ApiCheck` construct](/cli/constructs-reference/#apicheck) or [`BrowserCheck` construct section](/cli/constructs-reference/#browsercheck).
  </Tab>
</Tabs>

## 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

```ts api-check.ts theme={null}
// 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:

```ts api-check.ts theme={null}
// Share alert channels across checks
const alertChannel = new EmailAlertChannel("team-alerts", {
  address: "team@example.com",
})

// 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.