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. 
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']
  }
})

​
Configuration

ParameterTypeRequiredDefaultDescription
projectNamestring✅-Friendly name for your project
logicalIdstring✅-Unique identifier for this project (should be stable)
repoUrlstring❌-Optional URL to a Git repository
checksobject❌-Top-level defaults for all checks in this project
cliobject❌-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:
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:
export default defineConfig({
  logicalId: 'website-monitoring-prod',
  /* More options... */
})
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:
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:
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  cli: {
    runLocation: "us-east-1",
    retries: 2,
  },
})
Properties:
ParameterTypeRequiredDefaultDescription
runLocationstring❌-Default location for checkly test and checkly trigger
privateRunLocationstring❌-Default private location for CLI commands
retriesnumber❌0Default retry count for failing checks (max 3)
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:
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:
ParameterTypeRequiredDefaultDescription
activatedboolean❌trueWhether checks are enabled by default
alertChannelsArray<AlertChannel | AlertChannelRef>❌[]Default alert channels for all checks
checkMatchstring❌-Glob pattern to find check construct files
environmentVariablesEnvironmentVariable[]❌[]Default environment variables for all checks
frequencyFrequency❌-Default frequency for all checks
ignoreDirectoriesMatchstring[]--Glob patterns for directories to ignore
locationsstring[]❌[]Default public locations for all checks
mutedboolean❌falseWhether alert notifications are muted by default
playwrightConfigobject❌-Subset of Playwright configuration options
playwrightConfigPathstring❌-Path to the Playwright configuration file
privateLocationsstring[]❌[]Default private locations for all checks
retryStrategyobject❌-Control the retry behavior for failed checks
runtimeIdstring❌-Default runtime ID for all checks
shouldFailboolean❌falseWhether the behavior of when a check/alert is considered to fail is inverted.
tagsstring[]❌[]Default tags applied to all checks
browserChecksobject❌-Default settings for browser checks
multiStepChecksobject❌-Default settings for multi-step checks
playwrightChecksobject❌-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:
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:
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:
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    checkMatch: ["**/*.check.ts"],
  },
})
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:
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:
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
Use UrlMonitor or TcpMonitor construct for high-frequency checks running up to every ten seconds.
​
checks.ignoreDirectoriesMatch
string[]
Directories to ignore when looking for check files.Usage:
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.
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    locations: ["us-east-1", "eu-west-1"],
  },
})
Find a list of all public locations in the general documentation.
​
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:
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 and MultiStep Checks. 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:
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,
        }
      }
    },
  },
})
Learn more about the supported Playwright configuration options in the Browser Check Playwright documentation.
Browser Checks don’t support the projects, globalSetup, globalTeardown and storageState options. Check Playwright Check Suites for full Playwright support.
​
checks.playwrightConfigPath
string
Playwright config path to be used during Playwright Check Suite bundling and config parsing.Usage:
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:
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],
  },
})
Learn more about Private Locations in the general documentation.
​
checks.retryStrategy
Set a retry policy for your checks and monitors. Use RetryStrategyBuilder to create a retry policy.Usage:
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    retryStrategy: RetryStrategyBuilder.linearStrategy({
      baseBackoffSeconds: 30,
      maxRetries: 4,
      sameRegion: false,
    }),
  },
})
Learn more about alerting and retries in the general documentation.
​
checks.runtimeId
string
The runtime version used to execute checks and monitors.Usage:
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    runtimeId: '2025.04',
  },
})
Learn more about Checkly runtimes in the general documentation.
​
checks.tags
string[]
The tags assigned to the checks and monitors.Usage:
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:
ParameterTypeRequiredDefaultDescription
testMatchstringstring[]❌-Glob pattern for Playwright tests uses as Browser Checks
Example:
export default defineConfig({
  projectName: "Website Monitoring",
  logicalId: "website-monitoring-1",
  checks: {
    browserChecks: {
      testMatch: ["**/*.spec.ts"],
    },
  },
})
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.
​
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:
ParameterTypeRequiredDefaultDescription
testMatchstringstring[]❌-Glob pattern for Playwright tests uses as Browser Checks
Example:
export default defineConfig({
  projectName: "API Monitoring",
  logicalId: "api-monitoring-1",
  checks: {
    multiStepChecks: {
      testMatch: ["**/*.spec.ts"],
    },
  },
})
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.
​
checks.playwrightChecks
object[]
Usage:
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:
ParameterTypeRequiredDefaultDescription
playwrightConfigPathstring✅-Path to the Playwright configuration file
installCommandstring❌-Command to install dependencies before running tests
testCommandstring❌-Command to execute Playwright tests
pwProjectsstring | string[]❌-Projects to run from your configuration
pwTagsstring | string[]❌-Tags to filter tests using Playwright’s grep functionality
includestring | string[]❌-File patterns to include when bundling the test project
groupNamestring❌-Name of the check group to assign this check to
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.

​
Examples

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",
  },
})