Dependencies in Playwright Check Suites

Use the Checkly CLI to turn your Playwright tests into globally distributed monitors. Checkly uses your existing package.json dependencies and Playwright configuration.

Playwright Check Suites do not use Checkly runtimes. Browser Checks and Multistep Checks use runtimeId to select a managed runtime with fixed Checkly-provided dependencies. Playwright Check Suites install your project dependencies and use engine to select the JavaScript engine version.

Using JavaScript/Node.js dependencies

Checkly installs dependencies from your package.json and lock files. It works with npm, yarn, pnpm, and bun. By default, Checkly installs all dependencies (both dependencies and devDependencies).

package.json

{
  "dependencies": {
    "axios": "^1.6.0"
  },
  "devDependencies": {
    "@faker-js/faker": "^9.7.0",
    "@playwright/test": "^1.40.0"
  }
}

Checkly detects your package manager from your lock file:

Lock file	Package manager
`package-lock.json`	npm
`pnpm-lock.yaml`	pnpm
`yarn.lock`	yarn
`bun.lock`	bun

Workspace support

Starting from Checkly CLI 7.1., Checkly supports npm and pnpm workspaces in Playwright Check Suites, while Yarn workspaces remain unsupported. If your Playwright tests are stored in a monorepo, Checkly automatically recognizes and manages dependencies based on your workspace configuration. When using workspaces, packages in your workspace can depend on other packages in the same workspace, including those from the root package. See the pnpm workspaces docs or npm workspaces docs to learn how workspaces work. Requirements:

Place your lock file (package-lock.json or pnpm-lock.yaml) at the workspace root
Include both root and workspace package.json files in your project

Example workspace structure:

my-monorepo/
├── package.json              # Root workspace config
├── package-lock.json         # or pnpm-lock.yaml
├── packages/
│   └── e2e-tests/
│       ├── package.json      # Can depend on other workspace packages
│       └── playwright.config.ts

Checkly supports the exports and imports features in package.json. No additional configuration is needed in checkly.config.ts for workspace support.

Private packages

How you use private packages depends on whether Checkly can reach the registry that serves them:

Your registry	What to do
Reachable from the internet with a token, such as the npm registry, GitHub Packages, or a hosted Artifactory	Authenticate with `.npmrc`, as described below
Only reachable from your own network, such as a registry behind your firewall or VPN	See Internal Registries

package.json

{
  "devDependencies": {
    "@your-org/private-package": "^2.3.0"
  }
}

For a registry Checkly can reach, you need to:

Add authentication configuration to your .npmrc file
Store authentication tokens as environment variables in Checkly

Configure authentication to private dependencies

All package managers (npm, yarn, pnpm) use .npmrc files to authenticate with private registries.

Store authentication tokens as Checkly environment variables. Reference them in your .npmrc file using ${VARIABLE_NAME} syntax.

Using private npm packages

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Using JFrog Artifactory

registry=https://yourcompany.jfrog.io/artifactory/api/npm/npm-local/
//yourcompany.jfrog.io/artifactory/api/npm/npm-local/:_authToken=${ARTIFACTORY_TOKEN}

Using GitHub Packages

//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
@your-org:registry=https://npm.pkg.github.com

Using yarn or pnpm with private packages

yarn and pnpm also use .npmrc for authentication (same format as npm examples above).

Include authentication files

When you run npx checkly test or npx checkly deploy, the CLI bundles and uploads your .npmrc files automatically: the one at the workspace root and any next to a workspace member’s package.json. This makes them available when Checkly runs installCommand to install your dependencies.

Because your .npmrc files are uploaded with the code bundle, a token written in plain text is uploaded too. Reference tokens through environment variables, as in the examples above.

Using lifecycle scripts

Some npm packages define lifecycle scripts (such as prepare, postinstall, or preinstall) that run during installation and may require access to files not automatically included in the CLI’s code bundle. If you’re confident your dependencies work without lifecycle scripts, you can use the installCommand property to pass the --ignore-scripts flag to your package manager:

checkly.config.ts

import { defineConfig } from 'checkly'

export default defineConfig({
  checks: {
    playwrightChecks: [
      {
        name: 'My Check Suite',
        logicalId: 'my-check-suite',
        installCommand: 'npm install --ignore-scripts',
      }
    ]
  }
})

If a dependency does require its install hooks to function correctly, use the include option to add any required files to the code bundle:

checkly.config.ts

import { defineConfig } from 'checkly'

export default defineConfig({
  checks: {
    include: ['scripts/**/*', 'config/**/*'],
    playwrightChecks: [
      // ...
    ]
  }
})

Learn more about customizing install commands.

Dependency Caching

Checkly caches installed packages between check runs to speed up execution and reduce installation time. Dependencies are installed once and reused for subsequent runs until the files that define your dependencies change, such as your lock file and your package.json and .npmrc files, or until your installCommand, your working directory, or your engine change. Changes to embedded or pruned packages and registry routing also invalidate the cache.

How caching works

When dependency caching is enabled:

On the first run, Checkly installs all packages from your lock file and stores them in cache
On subsequent runs, Checkly checks whether any of the inputs described above have changed
If unchanged, Checkly uses the cached packages, skipping the installation step
If changed, Checkly installs packages again and updates the cache

Caching significantly reduces check execution time, especially for projects with many or large dependencies. When the cache can’t be used, the install takes longer the more packages your project declares; see Speed up installs. The dependency cache uses a least-recently-used (LRU) policy. Active Playwright Check Suites automatically refresh their cache entry, so caches only expire for check suites that have not run in the last 30 days.

Force a reinstall

To make Checkly reinstall dependencies without changing any of these files, set runner.cache.install.version at the top level of your checkly.config.ts and change its value whenever you want a fresh install. Deployed checks pick up the new value on the next npx checkly deploy.

checkly.config.ts

import { defineConfig } from 'checkly'

export default defineConfig({
  projectName: 'Acme Website',
  logicalId: 'acme-website',
  runner: {
    cache: {
      install: {
        version: 'v2',
      },
    },
  },
})

The value can be a string or an integer. An unset or empty value leaves the cache untouched, so a value read from an environment variable, such as version: process.env.DEPENDENCY_CACHE_VERSION, is safe when the variable isn’t set. For a one-off fresh install, pass --refresh-cache to checkly test, checkly pw-test, checkly trigger, or checkly checks run instead.

Automatic retries

Checkly automatically retries transient failures during setup steps. Cache downloads retry up to 3 times with exponential backoff. If all attempts fail, the run falls back to a clean install.

Dependency Cache behavior by location type

Public Locations: Dependency caching is Always ON. Private Locations: Dependency caching is OFF by default. To enable caching and speed up check runs, set DEPENDENCY_CACHE=CHECKLY_S3 in your agent configuration.

Speed up installs

The runner installs your dependencies whenever the dependency cache can’t be used: on the first run, after your dependencies change, and on every run in Private Locations that don’t have dependency caching turned on. Every package it installs adds to that time, so removing packages your checks never load from the install makes those runs start faster. In a monorepo, lockfile pruning already leaves out the dependencies of workspace members outside the bundle. To go further, remove the development tooling that your package.json declares but your tests don’t need, such as linters, formatters, and component workshops, with bundle.packages.prune:

checkly.config.ts

import { defineConfig } from 'checkly'

export default defineConfig({
  projectName: 'Acme Website',
  logicalId: 'acme-website',
  bundle: {
    packages: {
      prune: {
        devDependencies: [
          'eslint*',
          '@eslint/*',
          '@typescript-eslint/*',
          'prettier',
          'storybook',
          '@storybook/*',
        ],
      },
    },
  },
  checks: {
    playwrightConfigPath: './playwright.config.ts',
    playwrightChecks: [
      { name: 'Acme E2E', logicalId: 'acme-e2e' },
    ],
  },
})

This config removes ESLint and its plugins, Prettier, and Storybook from the devDependencies of the bundled package.json files. The CLI then regenerates the bundled lockfile, so everything those tools depend on drops out too, and the runner installs only what remains. Your local package.json is unchanged, so linting and Storybook keep working on your machine. Pruning works the same way in a single-package project as in a monorepo. Only remove packages that neither your tests nor the install use: keep build tools such as typescript when an install script needs them. The CLI doesn’t check this for you. See Prune manifest dependencies for the full syntax, including entries scoped to one workspace member, and its requirements and caveats.

Playwright browser caching

Checkly caches Playwright browsers so that runs don’t download them every time. How caching works depends on which location your checks run.

Browser caching on Public Locations

Checkly caches Playwright browsers across all public regions to reduce startup time. When a new Playwright version is available, runs download browsers until Checkly updates the shared cache.

Browser caching on Private Locations

Checkly caches Playwright browsers on each Private Location agent, grouped by Playwright version. When a matching version exists in cache, Checkly skips the download — reducing startup time and making runs more reliable.

Browser caching requires Private Location agent v8.2.0 or later.

Troubleshooting Dependency Installation

Package not found

If you see errors like 404 Not Found or Package '@your-org/package' not found:

Verify your .npmrc file is at the workspace root or next to the package.json that needs it
If the registry is only reachable from your own network, see Internal Registries
Check that the registry URL is correct
Ensure your package name matches exactly (including scope)

Authentication failed

If you see 401 Unauthorized or 403 Forbidden errors:

Verify the environment secret is set in Checkly (see environment variables)
Ensure the variable name in your .npmrc file matches exactly (e.g., ${NPM_TOKEN})
Confirm that your token has the necessary permissions to access the package

Wrong package manager detected

If Checkly uses the wrong package manager:

Verify the correct lock file is present (package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lock)
Remove any conflicting lock files
Override with a custom installCommand if needed (see customize install commands)

Installation timeout

If package installation exceeds time limits:

Check for large dependencies that can be optimized
Remove dependencies your checks don’t use from the code bundle with bundle.packages.prune
Consider using a custom installCommand to install only required packages

Memory usage exceeded

If you see errors indicating that memory limits were exceeded during installation:

Optimize your dependencies to reduce memory consumption
Remove dependencies your checks don’t use from the code bundle with bundle.packages.prune
Consider using a custom installCommand to install only necessary packages

General installation failures

If you encounter general installation errors:

Review the full error logs for specific issues
Ensure all dependencies are compatible with the Node.js version used by Checkly
Consider using a custom installCommand to handle complex installations

Getting Started

Detect

Communicate

Resolve

AI

Integrations

Dependencies in Playwright Check Suites

Using JavaScript/Node.js dependencies

Workspace support

Private packages

Configure authentication to private dependencies

Using private npm packages

Using JFrog Artifactory

Using GitHub Packages

Using yarn or pnpm with private packages

Include authentication files

Using lifecycle scripts

Dependency Caching

How caching works

Force a reinstall

Automatic retries

Dependency Cache behavior by location type

Speed up installs

Playwright browser caching

Browser caching on Public Locations

Browser caching on Private Locations

Troubleshooting Dependency Installation

Package not found

Authentication failed

Wrong package manager detected

Installation timeout

Memory usage exceeded

General installation failures

​Using JavaScript/Node.js dependencies

​Workspace support

​Private packages

​Configure authentication to private dependencies

​Using private npm packages

​Using JFrog Artifactory

​Using GitHub Packages

​Using yarn or pnpm with private packages

​Include authentication files

​Using lifecycle scripts

​Dependency Caching

​How caching works

​Force a reinstall

​Automatic retries

​Dependency Cache behavior by location type

​Speed up installs

​Playwright browser caching

​Browser caching on Public Locations

​Browser caching on Private Locations

​Troubleshooting Dependency Installation

​Package not found

​Authentication failed

​Wrong package manager detected

​Installation timeout

​Memory usage exceeded

​General installation failures

Using JavaScript/Node.js dependencies

Workspace support

Private packages

Configure authentication to private dependencies

Using private npm packages

Using JFrog Artifactory

Using GitHub Packages

Using yarn or pnpm with private packages

Include authentication files

Using lifecycle scripts

Dependency Caching

How caching works

Force a reinstall

Automatic retries

Dependency Cache behavior by location type

Speed up installs

Playwright browser caching

Browser caching on Public Locations

Browser caching on Private Locations

Troubleshooting Dependency Installation

Package not found

Authentication failed

Wrong package manager detected

Installation timeout

Memory usage exceeded

General installation failures