# Dependencies in Playwright Check Suites - Checkly Docs

> How Checkly installs the dependencies of your Playwright Check Suites, including private packages, and how to make installs faster.

Source: https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/dependencies/

---

Back to top
- 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

Playwright Check Suites

# Dependencies in Playwright Check Suites

How Checkly installs the dependencies of your Playwright Check Suites, including private packages, and how to make installs faster.

Use the [Checkly CLI](https://www.checklyhq.com/docs/cli/overview) 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](https://www.npmjs.com/), [yarn](https://yarnpkg.com/), [pnpm](https://pnpm.io/), and [bun](https://bun.sh/).
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.](https://github.com/checkly/checkly-cli/releases/tag/7.1.0), 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](https://pnpm.io/workspaces) or [npm workspaces docs](https://docs.npmjs.com/cli/v8/using-npm/workspaces) 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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/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](https://www.checklyhq.com/docs/platform/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](https://www.checklyhq.com/docs/platform/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`](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/configuration#customize-install-and-test-commands) 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`](https://www.checklyhq.com/docs/constructs/playwright-check#param-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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/configuration#customize-install-and-test-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`](https://www.checklyhq.com/docs/constructs/playwright-check#param-engine) change. Changes to [embedded or pruned packages and registry routing](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries) 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`](https://www.checklyhq.com/docs/cli/checkly-test), [`checkly pw-test`](https://www.checklyhq.com/docs/cli/checkly-pw-test), [`checkly trigger`](https://www.checklyhq.com/docs/cli/checkly-trigger), or [`checkly checks run`](https://www.checklyhq.com/docs/cli/checkly-checks) 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](https://www.checklyhq.com/docs/platform/private-locations/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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries#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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries#prune-manifest-dependencies) for the full syntax, including entries scoped to one workspace member, and its [requirements and caveats](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries#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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/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](https://www.checklyhq.com/docs/platform/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](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/configuration#customize-install-and-test-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

Was this page helpful?

[Suggest edits](https://github.com/checkly/docs/edit/main/detect/synthetic-monitoring/playwright-checks/dependencies.mdx)[Raise issue](https://github.com/checkly/docs/issues/new?title=Issue%20on%20docs&body=Path:%20/detect/synthetic-monitoring/playwright-checks/dependencies)

[Adding Playwright Check Suites to Groups Previous](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/add-to-group)[Packages from Internal Registries in Playwright Check Suites Next](https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries)

[x](https://x.com/checklyhq)[github](https://github.com/checkly)[linkedin](https://linkedin.com/company/checkly)

[Powered by This documentation is built and hosted on Mintlify, a developer documentation platform](https://www.mintlify.com/?utm_campaign=poweredBy&utm_medium=referral&utm_source=checkly-422f444a)