> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Construct

> Learn how to configure projects with the Checkly CLI.

Use the `defineConfig` to define core settings for your entire Checkly CLI project. This is typically configured in your `checkly.config.ts` file and provides global defaults for all CLI-powered checks and monitors.

```ts Basic Example 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/acme/website',
  checks: {
    activated: true,
    muted: false,
    runtimeId: '2025.04',
    frequency: Frequency.EVERY_5M,
    locations: ['us-east-1', 'eu-west-1'],
    tags: ['website', 'api']
  }
})
```

```ts Advanced Example theme={null}
import { defineConfig } from "checkly"
import { Frequency } from "checkly/constructs"

export default defineConfig({
  projectName: "Production Monitoring Suite",
  logicalId: "prod-monitoring-2025",
  repoUrl: "https://github.com/acme/monitoring",
  checks: {
    activated: true,
    muted: false,
    runtimeId: "2025.04",
    frequency: Frequency.EVERY_10M,
    locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
    tags: ["production", "critical"],
    checkMatch: "**/__checks__/*.check.ts",
    ignoreDirectoriesMatch: ["node_modules/**", "dist/**"],
    playwrightConfig: {
      use: {
        baseURL: "https://app.example.com",
      },
    },
    browserChecks: {
      frequency: Frequency.EVERY_30M,
      testMatch: "**/__tests__/*.spec.ts",
    },
  },
  cli: {
    runLocation: "eu-west-1",
    privateRunLocation: "private-dc1",
    retries: 2,
  },
})
```

## Configuration

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `projectName` | `string` | ✅ | - | Friendly name for your project |
| `logicalId` | `string` | ✅ | - | Unique identifier for this project (should be stable) |
| `repoUrl` | `string` | ❌ | - | Optional URL to a Git repository |
| `checks` | `object` | ❌ | - | Top-level defaults for all checks in this project |
| `cli` | `object` | ❌ | - | Defaults for CLI commands |

### Core Project Options

**projectName** `string` *required*

Friendly name for your project that will be displayed in the Checkly dashboard and used for identification.

**Usage:**

```ts highlight={2} theme={null}
export default defineConfig({
  projectName: 'Website Monitoring',
  /* More options... */
})
```

**Use cases**: Dashboard identification, project organization, team coordination.

**logicalId** `string` *required*

Unique identifier for this project that should remain stable across deployments. Changing this will cause Checkly to treat it as a new project.

**Usage:**

```ts highlight={2} theme={null}
export default defineConfig({
  logicalId: 'website-monitoring-prod',
  /* More options... */
})
```

> [!WARNING]
>
> The `logicalId` should remain stable across deployments. Changing it will cause Checkly to treat it as a new project, losing historical data and configurations.

**Use cases**: Project identification, deployment tracking, configuration persistence.

**repoUrl** `string`

Optional URL to a Git repository for documentation and team collaboration purposes in Checkly UI.

**Usage:**

```ts highlight={2} theme={null}
export default defineConfig({
  repoUrl: 'https://github.com/acme/website',
  /* More options... */
})
```

**Use cases**: Documentation linking, team collaboration, source code reference.

**cli** `object`

Defaults for CLI commands like `checkly test` and `checkly trigger`.

**Usage:**

```ts highlight={4-7} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  cli: {
    runLocation: "us-east-1",
    retries: 2,
  },
})
```

**Properties:**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `runLocation` | `string` | ❌ | - | Default location for `checkly test` and `checkly trigger` |
| `privateRunLocation` | `string` | ❌ | - | Default private location for CLI commands |
| `retries` | `number` | ❌ | `0` | Default retry count for failing checks (max 3) |
| `maxFailures` | `number` | ❌ | - | Stop `checkly test` and `checkly trigger` once this many checks have failed. The `--max-failures` flag overrides it. See [`checkly test`](https://www.checklyhq.com/docs/cli/checkly-test) |

**Use cases**: Local testing defaults, CI/CD configuration, development workflow.

### Check and Monitor Configuration

The `checks` property allows you to set global defaults for all checks and monitors in your project. Individual checks and groups can override these settings.

**checks** `object`

Top-level defaults for all checks in this project. Individual checks and groups can override these settings.

**Usage:**

```ts highlight={5-13} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  repoUrl: "https://github.com/acme/website",
  checks: {
    activated: true,
    muted: false,
    runtimeId: "2025.04",
    frequency: Frequency.EVERY_5M,
    locations: ["us-east-1", "eu-west-1"],
    tags: ["website", "api"],
    /* More options... */
  },
})
```

**Properties:**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `activated` | `boolean` | ❌ | `true` | Whether checks are enabled by default |
| `alertChannels` | `Array<AlertChannel \| AlertChannelRef>` | ❌ | `[]` | Default alert channels for all checks |
| `checkMatch` | `string` | ❌ | - | Glob pattern to find check construct files |
| `environmentVariables` | `EnvironmentVariable[]` | ❌ | `[]` | Default environment variables for all checks |
| `frequency` | `Frequency` | ❌ | - | Default frequency for all checks |
| `ignoreDirectoriesMatch` | `string[]` | - | - | Glob patterns for directories to ignore |
| `locations` | `string[]` | ❌ | `[]` | Default public locations for all checks |
| `muted` | `boolean` | ❌ | `false` | Whether alert notifications are muted by default |
| `playwrightConfig` | `object` | ❌ | - | Subset of Playwright configuration options |
| `playwrightConfigPath` | `string` | ❌ | - | Path to the Playwright configuration file |
| `privateLocations` | `string[]` | ❌ | `[]` | Default private locations for all checks |
| `retryStrategy` | `object` | ❌ | - | Control the retry behavior for failed checks |
| `runtimeId` | `string` | ❌ | - | Default runtime ID for all checks |
| `shouldFail` | `boolean` | ❌ | `false` | Whether the behavior of when a check/alert is considered to fail is inverted. Only applies to API checks, URL monitors and TCP monitors. |
| `tags` | `string[]` | ❌ | `[]` | Default tags applied to all checks |
| `browserChecks` | `object` | ❌ | - | Default settings for browser checks |
| `multiStepChecks` | `object` | ❌ | - | Default settings for multi-step checks |
| `playwrightChecks` | `object` | ❌ | - | Default settings for Playwright Check Suites |

### General Settings for All Check and Monitor Types

Define global defaults for all checks and monitors in this project. Individual checks and groups can override these settings.

**checks.activated** `boolean` (default: true)

Whether the checks and monitors are enabled and will run according to its schedule.

**Usage:**

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    activated: true,
  },
})
```

**checks.alertChannels** `AlertChannel[]`

Default alert channels for all checks and monitors.

**Usage:**

```ts highlight={9} theme={null}
const smsAlertChannel = new SmsAlertChannel("sms-alert-channel", {
  phoneNumber: "+1234567890",
})

export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    alertChannels: [smsAlertChannel],
  },
})
```

**checks.checkMatch** `string`

Glob pattern where the CLI looks for files containing Check constructs, i.e. all `.check.ts` files.

**Usage:**

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    checkMatch: ["**/*.check.ts"],
  },
})
```

> [!TIP]
>
> We recommend to establish a clear file convention like `*.check.ts` to easily identify files containing Checkly constructs.

**checks.environmentVariables** `object[]`

Environment variables available to the check script and monitors.

**Usage:**

```ts highlight={5-10} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    environmentVariables: [
      {
        key: "BASE_URL",
        value: "https://example.com",
      },
    ],
  },
})
```

**checks.frequency** `Frequency`

Default frequency at which the checks and monitors are executed.

**Usage:**

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    frequency: Frequency.EVERY_5M,
  },
})
```

**Available frequencies**: `EVERY_1M`, `EVERY_2M`, `EVERY_5M`, `EVERY_10M`, `EVERY_15M`, `EVERY_30M`, `EVERY_1H`, `EVERY_2H`, `EVERY_3H`, `EVERY_6H`, `EVERY_12H`, `EVERY_24H`

> [!TIP]
>
> Use [`UrlMonitor`](https://www.checklyhq.com/docs/constructs/url-monitor) or [`TcpMonitor`](https://www.checklyhq.com/docs/constructs/tcp-monitor) construct for high-frequency checks running up to every ten seconds.

**checks.ignoreDirectoriesMatch** `string[]`

Directories to ignore when looking for check files.

**Usage:**

```ts highlight={6} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    checkMatch: ["**/**/*.check.ts"],
    ignoreDirectoriesMatch: ["api/**"],
  },
})
```

**checks.locations** `string[]` (default: \[])

Array of public location codes where the URL monitor should run from. Multiple locations provide geographic coverage.

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    locations: ["us-east-1", "eu-west-1"],
  },
})
```

> [!TIP]
>
> Find a list of [all public locations in the general documentation](https://www.checklyhq.com/docs/concepts/locations.md).

> [!NOTE]
>
> Give every check a location: set `locations` or `privateLocations` on the check or its group, or set a default with `checks.locations` or `checks.privateLocations`. A check without any location runs in a location chosen by Checkly, and since CLI version 10, `checkly deploy` and `checkly validate` warn about it. Heartbeat monitors and test-only checks don't need a location.

**checks.muted** `boolean` (default: false)

Determine if any notifications will be sent out when a check fails and/or recovers. Muting checks is useful for temporarily silencing alerts during maintenance.

**Usage:**

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    muted: true,
  },
})
```

**checks.playwrightConfig** `object`

Global configuration options for the Playwright Test Runner use in [Browser Checks](https://www.checklyhq.com/docs/detect/synthetic-monitoring/browser-checks/overview.md) and [MultiStep Checks](https://www.checklyhq.com/docs/detect/synthetic-monitoring/multistep-checks/overview.md). This allows you to configure your Playwright-powered checks in a single place, instead of having to repeat the same configuration for each test file.

**Usage:**

```ts highlight={5-16} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    playwrightConfig: {
      timeout: 1234,
      use: {
        baseURL: 'https://www.checklyhq.com',
        isMobile: true,
      },
      expect: {
        toHaveScreenshot: {
          maxDiffPixels: 10,
        }
      }
    },
  },
})
```

> [!TIP]
>
> Learn more about the supported Playwright configuration options in [the Browser Check Playwright documentation](https://www.checklyhq.com/docs/detect/synthetic-monitoring/browser-checks/playwright-support.md).

> [!WARNING]
>
> Browser Checks don't support the `projects`, `globalSetup`, `globalTeardown` and `storageState` options. Check [Playwright Check Suites](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/overview.md) for full Playwright support.

**checks.playwrightConfigPath** `string`

Playwright config path to be used during [Playwright Check Suite](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/overview.md) bundling and config parsing.

**Usage:**

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    playwrightConfigPath: "./playwright.config.ts",
  },
})
```

**checks.privateLocations** `PrivateLocation`

Private Locations to run your monitors and checks from.

**Usage:**

```ts highlight={12} theme={null}
const datacenterLocation = new PrivateLocation("datacenter-east-1", {
  name: "East Coast Datacenter",
  icon: "building",
  slugName: "datacenter-east-1",
  proxyUrl: "http://proxy.datacenter.local:8080",
})

export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    privateLocations: [datacenterLocation],
  },
})
```

> [!TIP]
>
> Learn more about [Private Locations in the general documentation](https://www.checklyhq.com/docs/platform/private-locations/overview.md).

**checks.retryStrategy**

Set a retry policy for your checks and monitors. [Use `RetryStrategyBuilder`](https://www.checklyhq.com/docs/constructs/retry-strategy) to create a retry policy. Without one, each check, monitor and group uses the [default for its type](https://www.checklyhq.com/docs/constructs/retry-strategy.md#default-retry-strategy).

**Usage:**

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    retryStrategy: RetryStrategyBuilder.linearStrategy({
      baseBackoffSeconds: 30,
      maxRetries: 4,
      sameRegion: false,
    }),
  },
})
```

> [!TIP]
>
> Learn more about [alerting and retries in the general documentation](https://www.checklyhq.com/docs/communicate/alerts/retries.md).

**checks.runtimeId** `string`

The runtime version used to execute checks and monitors.

**Usage:**

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    runtimeId: '2025.04',
  },
})
```

> [!TIP]
>
> Learn more about [Checkly runtimes in the general documentation](https://www.checklyhq.com/docs/platform/runtimes/overview.md).

**checks.tags** `string[]`

The tags assigned to the checks and monitors.

**Usage:**

```ts highlight={5} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    tags: ["website", "frontend"],
  },
})
```

### Default Settings for Complex Check Types

**checks.browserChecks** `object`

If your project doesn't require specific configuration and you want to quickly transform your Playwright end-to-end tests into Browser Checks, use the `browserChecks.testMatch` property.

**Properties:**

| Parameter | Type | Required | Default | Description | |
| - | - | - | - | - | - |
| `testMatch` | `string` | `string[]` | ❌ | - | Glob pattern for Playwright tests uses as Browser Checks |

**Example:**

```ts highlight={6} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    browserChecks: {
      testMatch: ["**/*.spec.ts"],
    },
  },
})
```

> [!TIP]
>
> The `checks.browserChecks` property gives your monitoring setup a head start by turning your existing end-to-end tests into monitors. For more advanced use cases and individual configuration use [the `BrowserCheck` construct](https://www.checklyhq.com/docs/constructs/browser-check).

**checks.multiStepChecks** `object`

If your project doesn't require specific configuration and you want to quickly transform your Playwright API tests into Multistep Checks, use the `multiStepChecks.testMatch` property.

**Properties:**

| Parameter | Type | Required | Default | Description | |
| - | - | - | - | - | - |
| `testMatch` | `string` | `string[]` | ❌ | - | Glob pattern for Playwright tests uses as Browser Checks |

**Example:**

```ts highlight={6} theme={null}
export default defineConfig({
  projectName: "API Monitoring",
  logicalId: "api-monitoring-1",
  checks: {
    multiStepChecks: {
      testMatch: ["**/*.spec.ts"],
    },
  },
})
```

> [!TIP]
>
> The `checks.multiStepChecks` property gives your monitoring setup a head start by turning your existing API tests into monitors. For more advanced use cases and individual configuration use [the `MultistepCheck` construct](https://www.checklyhq.com/docs/constructs/multistep-check).

**checks.playwrightChecks** `object[]`

**Usage:**

```ts highlight={5-14} theme={null}
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    playwrightChecks: [
      {
        name: "critical-tagged",
        logicalId: "critical-tagged",
        pwTags: "critical",
        pwProjects: "chromium",
        frequency: Frequency.EVERY_1M,
        locations: ["us-east-1", "eu-west-1"],
      },
    ],
  },
})
```

**Parameters:**

**Playwright Check Suite**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `playwrightConfigPath` | `string` | ✅ | - | Path to the Playwright configuration file |
| `installCommand` | `string` | ❌ | - | Command to install dependencies before running tests |
| `testCommand` | `string` | ❌ | - | Command to execute Playwright tests |
| `pwProjects` | `string` \| `string[]` | ❌ | - | Projects to run from your configuration |
| `pwTags` | `string` \| `string[]` | ❌ | - | Tags to filter tests using Playwright's grep functionality |
| `include` | `string` \| `string[]` | ❌ | - | File patterns to include when bundling the test project |
| `group` | `CheckGroup` | ❌ | - | The CheckGroup this check suite belongs to |

> [!NOTE]
>
> Checkly CLI version 10 and later no longer include the deprecated `groupName` option. Set `group` to the `CheckGroup` instead.

**General Options**

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | `string` | ✅ | - | Friendly name for your check |
| `logicalId` | `string` | ✅ | - | Unique identifier for your check suite |
| `activated` | `boolean` | ❌ | `true` | Whether the check suite is enabled |
| `alertChannels` | `AlertChannel[]` | ❌ | `[]` | Array of AlertChannel objects for notifications |
| `alertEscalationPolicy` | `AlertEscalationPolicy` | ❌ | - | Advanced alert settings |
| `environmentVariables` | `object[]` | ❌ | `[]` | Check-level environment variables |
| `frequency` | `Frequency` | ❌ | - | How often to run your check suite |
| `locations` | `string[]` | ❌ | `[]` | Array of public location codes |
| `muted` | `boolean` | ❌ | `false` | Whether alert notifications are muted |
| `privateLocations` | `string[]` | ❌ | `[]` | Array of Private Location slugs |
| `retryStrategy` | `RetryStrategy` | ❌ | - | Strategy for configuring retries |
| `runParallel` | `boolean` | ❌ | `false` | Run check suites in parallel or round-robin |
| `tags` | `string[]` | ❌ | `[]` | Array of tags to organize check suites |

> [!TIP]
>
> The `checks.playwrightChecks` property gives your monitoring setup a head start by turning your existing Playwright test suite into synthetic monitoring. For more advanced use cases and individual configuration use [the `PlaywrightCheck` construct](https://www.checklyhq.com/docs/constructs/playwright-check).

## Examples

**Simple Website Monitoring**

```ts theme={null}
export default defineConfig({
  projectName: "Acme Website",
  logicalId: "acme-website-prod",
  repoUrl: "https://github.com/acme/website",
  checks: {
    activated: true,
    frequency: Frequency.EVERY_5M,
    locations: ["us-east-1", "eu-west-1"],
    tags: ["website"],
    checkMatch: "monitoring/**/*.check.ts",
  },
})
```

**Complex Application**

```ts theme={null}
import { defineConfig } from 'checkly'
import { Frequency } from 'checkly/constructs'

export default defineConfig({
  projectName: "E-commerce Platform Monitoring",
  logicalId: "ecommerce-platform-2025",
  repoUrl: "https://github.com/acme/ecommerce",
  checks: {
    activated: true,
    muted: false,
    runtimeId: "2025.04",
    frequency: Frequency.EVERY_10M,
    locations: ["us-east-1", "eu-west-1"],
    tags: ["ecommerce", "critical"],
    checkMatch: "**/*.check.ts",
    ignoreDirectoriesMatch: ["dist/**", "coverage/**"],
    playwrightConfig: {
      use: {
        baseURL: "https://shop.acme.com",
      },
    },
    browserChecks: {
      frequency: Frequency.EVERY_30M,
      testMatch: "e2e/**/*.spec.ts",
    },
  },
  cli: {
    runLocation: "us-east-1",
    retries: 2,
  },
})
```

**API-First Project**

```ts theme={null}
import { defineConfig } from 'checkly'
import { Frequency } from 'checkly/constructs'

export default defineConfig({
  projectName: "API Monitoring Suite",
  logicalId: "api-monitoring-v2",
  repoUrl: "https://github.com/acme/api-monitoring",
  checks: {
    activated: true,
    muted: false,
    runtimeId: "2025.04",
    frequency: Frequency.EVERY_2M,
    locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
    tags: ["api", "microservices"],
    checkMatch: "checks/**/*.api.check.ts",
    ignoreDirectoriesMatch: ["tests/**", "docs/**"],
  },
  cli: {
    runLocation: "us-east-1",
    retries: 3,
  },
})
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.