Checkly CLI

Common errors

• Error: TypeScript loader is missing

  cause The Checkly CLI could not find a suitable TypeScript loader to transpile your `.ts` check files, often due to missing 'jiti' or 'typescript' packages, or incorrect `tsconfig.json` configuration.
  fix Ensure `jiti` and `typescript` are installed as `devDependencies` (`npm install --save-dev jiti typescript`) and that your `tsconfig.json` is correctly set up. Using `npm create checkly@latest` is recommended for initial setup.

• Error: Cannot find module 'jiti'

  cause The `jiti` peer dependency, required by Checkly CLI for runtime transpilation, is missing from your project's `node_modules`.
  fix Install `jiti` explicitly: `npm install jiti` or `npm install --save-dev jiti`.

• Node.js version not supported

  cause Your current Node.js version does not meet the minimum requirements (`^18.19.0 || >=20.5.0`) specified by the `checkly` package's engine field.
  fix Upgrade your Node.js environment to a supported version using a tool like `nvm` (e.g., `nvm install 20 && nvm use 20`).

Warnings

• breaking The Checkly CLI requires Node.js version 18.19.0 or greater, or 20.5.0 or greater. Older Node.js versions are not supported and will prevent the CLI from running correctly. Ensure your environment meets these engine requirements.
  Fix: Upgrade your Node.js environment to a supported version (e.g., using `nvm install 20 && nvm use 20` or similar version manager).
• gotcha When defining checks in TypeScript, the CLI relies on a TypeScript loader (like 'jiti'). If you install the CLI manually (`npm install checkly`) instead of using `npm create checkly@latest`, you might need to ensure 'jiti' and 'typescript' are correctly installed and configured as peer dependencies.
  Fix: For an easy setup, use `npm create checkly@latest`. If installing manually, ensure `npm install --save-dev jiti typescript` is run to satisfy peer dependencies and allow TypeScript transpilation.
• gotcha Browser checks are written using `@playwright/test`. This package needs to be installed as a dev dependency in your project for browser checks to function correctly, even though Checkly CLI orchestrates their execution.
  Fix: Install Playwright: `npm install --save-dev @playwright/test`.
• gotcha The Checkly CLI supports AI Agent capabilities, which can be extended by installing 'skills'. This functionality, introduced in v7.7.0, requires an additional `npx skills add checkly/checkly-cli` command to provide AI coding assistants with full context.
  Fix: Run `npx skills add checkly/checkly-cli` to enable enhanced AI coding assistant features for Checkly CLI within supported AI environments.

Install

• npm install checkly npm
• yarn add checkly yarn
• pnpm add checkly pnpm

Imports

• ApiCheck, AssertionBuilder
  wrong:

  const { ApiCheck, AssertionBuilder } = require('checkly/constructs')

  correct:

  import { ApiCheck, AssertionBuilder } from 'checkly/constructs'

  These symbols are used to define API monitoring checks programmatically. CommonJS 'require' syntax is not supported for these ESM-first constructs.
• test, expect
  wrong:

  import { test, expect } from 'checkly'

  correct:

  import { test, expect } from '@playwright/test'

  For browser checks, Checkly CLI leverages Playwright. 'test' and 'expect' are imported directly from '@playwright/test', which should be installed as a dev dependency in your project.
• (CLI Commands)
  wrong:

  import { deploy } from 'checkly'

  correct:

  npx checkly <command>

  The Checkly CLI is primarily interacted with via the `npx checkly` command-line interface. Direct programmatic import of CLI commands from the 'checkly' package for execution is not the intended usage for end-users.

Quickstart

This code defines a simple API check and a Playwright-based browser check for a webshop, demonstrating how to write monitoring as code. It includes instructions for local testing and deployment to the Checkly cloud via the CLI.

import { ApiCheck, AssertionBuilder } from 'checkly/constructs';
import { test, expect } from '@playwright/test';
import * as path from 'path';

// --- API Check Example (api.check.ts) ---
// Define an API check for a public endpoint.
new ApiCheck('books-api-check-1', {
  name: 'Books API Status',
  request: {
    url: 'https://danube-web.shop/api/books',
    method: 'GET',
    assertions: [
      AssertionBuilder.statusCode().equals(200),
      AssertionBuilder.jsonBody('$[0].id').isNotNull(),
    ],
  },
});

// --- Browser Check Example (homepage.spec.ts) ---
// Define a Playwright-based browser check for a homepage.
test('webshop homepage loads and has title', async ({ page }) => {
  const response = await page.goto('https://danube-web.shop');
  expect(response?.status()).toBeLessThan(400); // Expect a successful HTTP status code
  await expect(page).toHaveTitle(/Danube WebShop/);

  // Optionally take a screenshot upon successful load
  const screenshotPath = path.join(process.cwd(), 'homepage.jpg');
  await page.screenshot({ path: screenshotPath });
  console.log(`Screenshot saved to: ${screenshotPath}`);
});

// To run these checks after saving them in your project (e.g., in `__checks__` directory):
// 1. Install Checkly CLI and Playwright: `npm install --save-dev checkly @playwright/test`
// 2. Log in to your Checkly account: `npx checkly login` (Requires a Checkly account)
// 3. Run tests locally: `npx checkly test`
// 4. Deploy checks to the Checkly cloud: `npx checkly deploy`