Custom Dependencies in Playwright Check Suites

Use private packages, custom registries, and additional dependencies in your 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.

Runtime Environment: Playwright Check Suites run in a Node.js runtime containing your custom dependencies. See the runtime specification for further details.

Using JavaScript/Node.js dependencies

Checkly installs dependencies from your package.json and lock files. It works with npm, yarn, and pnpm.

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

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. Check out pnpm workspaces docs(https://pnpm.io/workspaces) or npm workspaces docs to get an overview on workspaces.

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.

Using private dependencies

Checkly supports private packages. To authenticate with your private registry, configure your credentials in Checkly.

package.json

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

You need to:

1. Add authentication configuration to your .npmrc file
2. Include the .npmrc file in your checkly.config.ts
3. 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

# Using an environment variable (recommended)
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

# Hard-coded token (not recommended)
//registry.npmjs.org/:_authToken=npm_abc...

Using JFrog Artifactory

# Using an environment variable (recommended)
registry=https://yourcompany.jfrog.io/artifactory/api/npm/npm-local/:_authToken=${ARTIFACTORY_TOKEN}

# Hard-coded token (not recommended)
registry=https://yourcompany.jfrog.io/artifactory/api/npm/npm-local/:_authToken=abc...

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

Add your .npmrc file to the checks.include property in your checkly.config.ts.

When you run npx checkly test or npx checkly deploy, the CLI bundles and uploads these files. This makes them available when Checkly runs installCommand to install your dependencies.

checkly.config.ts

import { defineConfig } from 'checkly'

export default defineConfig({
  checks: {
    playwrightConfigPath: './playwright.config.ts',
    // Include .npmrc for authentication with private registries
    // Works with npm, yarn, and pnpm
    include: ['.npmrc'],
    playwrightChecks: [
      // ...
    ]
  }
})

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 your lock files (package-lock.json, pnpm-lock.yaml, or yarn.lock), your installCommand or your working directory change.

How caching works

When dependency caching is enabled:

1. On the first run, Checkly installs all packages from your lock file and stores them in cache
2. On subsequent runs, Checkly checks if your lock file, installCommand or working directory have changed
3. If unchanged, Checkly uses the cached packages, skipping the installation step
4. If changed, Checkly installs packages again and updates the cache

Caching significantly reduces check execution time, especially for projects with many or large dependencies.

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.

Troubleshooting

Package not found

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

• Verify your .npmrc file is included in checks.include
• 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, or pnpm-lock.json)
• 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
• 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
• 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