Checkly Config

checkly config

Configure Checkly CLI projects with checkly.config.ts.

Quick start

// checkly.config.ts
import { defineConfig } from 'checkly'

export default defineConfig({
  projectName: 'My App',
  logicalId: 'my-app-monitoring',
  repoUrl: 'https://github.com/acme/my-app',
  checks: {
    frequency: 5,
    locations: ['us-east-1', 'eu-west-1'],
    tags: ['production', 'api'],
    runtimeId: '2025.04',
    checkMatch: '**/__checks__/**/*.check.{js,ts}',
    browserChecks: {
      testMatch: '**/__checks__/**/*.spec.{js,ts}',
    },
  },
  bundle: {
    packages: {
      embed: ['@acme/**', '!@acme/public-*'],
      prune: {
        peerDependencies: ['**', '!@acme/runtime-peer'],
      },
    },
  },
  runner: {
    cache: {
      install: {
        version: '2026-09-04',
      },
    },
    registries: {
      upstreams: {
        npmjs: { url: 'https://registry.npmjs.org/' },
        internal: {
          url: 'https://npm.example.com/',
          auth: { type: 'bearer', token: '${INTERNAL_NPM_TOKEN}' },
        },
      },
      packages: [
        { pattern: '@acme/**', upstreams: ['internal'] },
        { pattern: '**', upstreams: ['npmjs'] },
      ],
    },
  },
})

These top-level package controls apply only to Playwright Check Suites:

• bundle.packages.embed downloads verified package tarballs on the CLI machine and uploads them when runners cannot reach the source registry. Entries apply in order; ! excludes prior selections, * stays within one package-name segment, and ** crosses the / scope separator.
• bundle.packages.prune rewrites only bundled package.json copies, removing dependencies that remote installation does not need. It does not edit workspace files.
• runner.registries overrides registry routing only on Checkly runners. Rules are first-match-wins and must end with an exact ** catch-all. Bearer tokens must be a single ${VAR} reference resolved from Checkly environment variables; never put a literal credential in config.

See checkly-playwright for supported lockfiles, member-scoped pruning, cache effects, validation, and secret-handling details.

Dependency-cache invalidation

Checkly caches installed dependencies for Playwright Check Suites using the workspace's dependency inputs—the lockfile plus every workspace member's package.json and .npmrc, whether or not that member is in the bundle—plus the bundle's own install inputs, including registry configuration and the resolved embedded/pruned package sets. The key can therefore change without a file edit when a different set of workspace members lands in the bundle. To invalidate that cache persistently for deployed and scheduled suites, set runner.cache.install.version to a string or safe integer and change it when dependencies must be reinstalled:

export default defineConfig({
  projectName: 'My App',
  logicalId: 'my-app-monitoring',
  runner: {
    cache: {
      install: {
        version: process.env.DEPENDENCY_CACHE_VERSION,
      },
    },
  },
})

This runner-level setting applies to the one code bundle shared by all Playwright Check Suites. An unset or empty-string value leaves the cache key unchanged, so an optional environment variable is safe. The old caching.dependencyCache.version location is deprecated but still works with a warning. Upgrade every environment that runs the CLI before migrating, then remove the old property and set runner.cache.install.version; declaring both locations is a fatal config error. For one ad-hoc reinstall, use --refresh-cache with checkly test, checkly pw-test, checkly trigger, or checkly checks run instead of changing committed configuration.

Configuration validation diagnostics

Commands that load checkly.config.* collect configuration problems and render them with config-file attribution instead of stopping at the first error. test, pw-test, validate, deploy, and import plan show config diagnostics before project or construct diagnostics; fatal config diagnostics exit with status 1. Read and fix the full set before rerunning rather than addressing only the first line.

checkly trigger also rejects an invalid config instead of silently continuing. A missing or otherwise unloadable config can still be tolerated by trigger-only workflows, so use npx checkly validate when the config itself must be proved valid. Deprecation diagnostics such as the legacy cache-property warning are non-fatal, but should still be migrated after every CLI environment is current. Diagnostics may be rendered on stdout; automation must use the process exit status rather than assuming stderr contains every failure.

Configuration file structure

Required properties

{
  projectName: string,    // Display name in Checkly UI
  logicalId: string,      // Unique project identifier
}

Example:

export default defineConfig({
  projectName: 'E-commerce API',
  logicalId: 'ecommerce-api-prod',
})

Check defaults

Configure defaults that apply to all checks:

{
  checks: {
    frequency: number,              // Minutes between checks (1, 5, 10, 15, 30, 60, etc.)
    locations: string[],            // Checkly datacenter locations
    tags: string[],                 // Tags for organization
    runtimeId: string,              // Runtime version (e.g., '2025.04')
    
    // File discovery
    checkMatch: string | string[],  // Pattern for check files
    ignoreDirectoriesMatch: string[], // Directories to skip
    
    // Alert settings
    alertChannels: AlertChannel[],  // Default alert channels
    
    // Retry configuration
    retryStrategy: RetryStrategy,   // Default retry behavior
  }
}

Example with comprehensive defaults:

import { defineConfig, RetryStrategyBuilder } from 'checkly'

export default defineConfig({
  projectName: 'Production Monitoring',
  logicalId: 'prod-monitoring',
  checks: {
    frequency: 5,
    locations: ['us-east-1', 'us-west-1', 'eu-west-1'],
    tags: ['production', 'critical'],
    runtimeId: '2025.04',
    
    retryStrategy: RetryStrategyBuilder.fixedStrategy({
      baseBackoffSeconds: 60,
      maxAttempts: 2,
      maxDurationSeconds: 600,
      sameRegion: true,
    }),
    
    checkMatch: '**/__checks__/**/*.check.{js,ts}',
    ignoreDirectoriesMatch: ['**/node_modules/**', '**/.git/**'],
  },
})

Browser check configuration

Auto-discover Playwright spec files as browser checks:

{
  checks: {
    browserChecks: {
      testMatch: string | string[],  // Pattern to match spec files
      frequency: number,              // Override default frequency
      locations: string[],            // Override default locations
      tags: string[],                 // Additional tags
    }
  }
}

Example:

export default defineConfig({
  checks: {
    frequency: 10,
    locations: ['us-east-1'],
    
    browserChecks: {
      testMatch: '**/__checks__/**/*.spec.{js,ts}',
      frequency: 5,  // Browser checks run more frequently
      tags: ['e2e', 'browser'],
    },
  },
})

Playwright Check Suite

Configure full Playwright test suite as a single check:

{
  checks: {
    playwrightConfigPath: string,    // Path to playwright.config.ts
    include: string | string[],       // Additional files to bundle
    
    playwrightChecks: [
      {
        name: string,
        frequency: number,
        testCommand: string,          // Command to run tests
        locations: string[],
        tags: string[],
      }
    ],
  }
}

Example:

export default defineConfig({
  checks: {
    playwrightConfigPath: './playwright.config.ts',
    include: ['./fixtures/**/*.json'],
    
    playwrightChecks: [
      {
        name: 'E2E Test Suite',
        frequency: 10,
        testCommand: 'npm run test:e2e',
        locations: ['us-east-1', 'eu-west-1'],
        tags: ['e2e', 'critical'],
      },
    ],
  },
})

CLI configuration

Configure CLI behavior:

{
  cli: {
    runLocation: string,            // Default location for 'npx checkly test'
    privateRunLocation: string,     // Private location slug
    verbose: boolean,               // Show full logs
    reporters: string[],            // Default reporters
    retries: number,                // Test retry attempts (0-3)
  }
}

Example:

export default defineConfig({
  cli: {
    runLocation: 'us-east-1',
    verbose: false,
    reporters: ['list'],
    retries: 1,
  },
})

File discovery patterns

Check discovery

The CLI discovers check files using glob patterns:

Examples:

// Discover checks in specific directory
checks: {
  checkMatch: '**/__checks__/**/*.check.ts',
}

// Multiple patterns
checks: {
  checkMatch: [
    '**/__checks__/**/*.check.ts',
    '**/monitoring/**/*.check.ts',
  ],
}

// Auto-discover browser checks
checks: {
  browserChecks: {
    testMatch: '**/__checks__/**/*.spec.ts',
  },
}

Ignore patterns

Exclude directories from discovery:

checks: {
  ignoreDirectoriesMatch: [
    '**/node_modules/**',
    '**/.git/**',
    '**/dist/**',
    '**/build/**',
  ],
}

Note: node_modules and .git are always ignored by default.

Configuration hierarchy

Configuration values cascade from global to specific:

1. Checkly account defaults (lowest priority)
   ↓
2. checkly.config.ts defaults
   ↓
3. CheckGroup properties
   ↓
4. Individual check properties (highest priority)

Example:

// checkly.config.ts - global defaults
export default defineConfig({
  checks: {
    frequency: 10,
    locations: ['us-east-1'],
  },
})

// check-group.ts - group overrides
const criticalChecks = new CheckGroup('critical-checks', {
  frequency: 5,  // More frequent than default
})

// api-check.ts - check-level override
new ApiCheck('auth-api', {
  name: 'Auth API',
  frequency: 1,  // Most frequent - overrides group and global
  group: criticalChecks,
  // locations inherited from config (us-east-1)
})

Location configuration

Available locations

Common Checkly datacenter locations:

Example:

checks: {
  locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
}

Private locations

For on-premise or private network monitoring:

checks: {
  privateLocations: ['my-vpc-location'],
}

cli: {
  privateRunLocation: 'my-vpc-location',  // For testing
}

Runtime configuration

Runtime versions

Specify Node.js runtime and available npm packages:

checks: {
  runtimeId: '2025.04',  // Latest runtime
}

Runtime version format: YYYY.MM

To check available runtimes:

# Runtime info shown during test/deploy
npx checkly test

Environment variables

Set environment variables for all checks:

import { defineConfig } from 'checkly'

export default defineConfig({
  checks: {
    environmentVariables: [
      { key: 'API_BASE_URL', value: 'https://api.example.com' },
      { key: 'API_KEY', value: process.env.API_KEY!, locked: true },
    ],
  },
})

Environment variable hierarchy:

1. Check-level variables (highest priority)
2. Group-level variables
3. Global account variables (set in Checkly UI)

Workflows

Initial project setup

1. Create project with scaffolding:

   npm create checkly@latest
   cd my-checkly-project
   

2. Edit checkly.config.ts:

   export default defineConfig({
     projectName: 'My Production Monitoring',
     logicalId: 'prod-monitoring',
     repoUrl: 'https://github.com/myorg/myapp',
     checks: {
       frequency: 5,
       locations: ['us-east-1', 'eu-west-1'],
       tags: ['production'],
       runtimeId: '2025.04',
     },
   })
   

3. Test configuration:

   npx checkly validate
   

Migrating from auto-generated config

If CLI generates config automatically (when playwright.config.ts exists):

1. Review generated config:

   cat checkly.config.ts
   

2. Customize settings:

   export default defineConfig({
     projectName: 'Your Project Name',  // Update this
     logicalId: 'your-project-id',      // Update this
     checks: {
       frequency: 10,
       locations: ['us-east-1'],
       playwrightConfigPath: './playwright.config.ts',
     },
   })
   

3. Validate:

   npx checkly validate
   

Adding browser check auto-discovery

Enable auto-discovery for Playwright specs:

1. Update checkly.config.ts:

   export default defineConfig({
     checks: {
       browserChecks: {
         testMatch: '**/__checks__/**/*.spec.ts',
       },
     },
   })
   

2. Create checks directory:

   mkdir -p __checks__
   

3. Add Playwright specs:

   # Specs are automatically discovered and deployed
   ls __checks__/*.spec.ts
   

4. Test discovery:

   npx checkly test
   # Should show auto-discovered checks
   

Troubleshooting

"No checks found"

Cause: checkMatch pattern doesn't match your files

Solution:

1. Verify file paths:

   find . -name "*.check.ts"
   

2. Update pattern in checkly.config.ts:

   checks: {
     checkMatch: '**/your-directory/**/*.check.ts',
   }
   

3. Test:

   npx checkly validate --verbose
   

"Cannot find module 'checkly'"

Cause: Missing checkly package

Solution:

npm install --save-dev checkly

"Duplicate logical ID"

Cause: Two resources have the same logical ID

Solution:

1. Ensure logicalId in checkly.config.ts is unique across your account
2. Check for duplicate check IDs in your code
3. Use descriptive, unique IDs: 'my-app-homepage-check' not 'check-1'

Configuration not applying

Cause: More specific configuration overriding defaults

Solution:

1. Check configuration hierarchy (check > group > config > account)
2. Verify check isn't part of a group with different settings
3. Use --verbose flag to see resolved configuration:

   npx checkly test --verbose
   

Related Skills

Getting started:

• See checkly-auth for authentication before using config
• See checkly-test to validate your configuration
• See checkly-deploy to deploy configured checks

Check creation:

• See checkly-checks for creating API and browser checks
• See checkly-playwright for Playwright test suite configuration
• See checkly-groups for organizing checks with groups