From 4f78f1d9c19fe49f684df6c3f56883f379bf769f Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 14:36:55 +0900 Subject: [PATCH 01/17] docs: document embedding and pruning for private packages in Playwright Check Suites (RED-1310) Add a page covering bundle.packages.embed, automatic lockfile pruning (CHECKLY_LOCKFILE_PRUNE, CHECKLY_LOCKFILE_PRUNE_TIMEOUT), bundle.packages.prune and runner.registries, framed around private packages from internal registries Checkly cannot reach. Link it from Custom Dependencies and the project config reference. Co-Authored-By: Claude Opus 5.5 --- constructs/project.mdx | 2 + .../playwright-checks/custom-dependencies.mdx | 4 + .../playwright-checks/internal-registries.mdx | 275 ++++++++++++++++++ docs.json | 1 + sitemap.xml | 3 + 5 files changed, 285 insertions(+) create mode 100644 detect/synthetic-monitoring/playwright-checks/internal-registries.mdx diff --git a/constructs/project.mdx b/constructs/project.mdx index 121230b7..eaa42897 100644 --- a/constructs/project.mdx +++ b/constructs/project.mdx @@ -74,6 +74,8 @@ export default defineConfig({ | `repoUrl` | `string` | ❌ | - | Optional URL to a Git repository | | `checks` | `object` | ❌ | - | Top-level defaults for all checks in this project | | `cli` | `object` | ❌ | - | Defaults for CLI commands | +| `bundle` | `object` | ❌ | - | Dependency embedding and pruning for Playwright Check Suite code bundles. See [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) | +| `runner` | `object` | ❌ | - | Settings applied on Checkly runners, such as registry routing for Playwright Check Suite installs. See [Route runner installs](/detect/synthetic-monitoring/playwright-checks/internal-registries#route-runner-installs-to-other-registries) | ### Core Project Options diff --git a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx index 31c61aff..ab02d521 100644 --- a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx +++ b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx @@ -82,6 +82,10 @@ You need to: 2. Include the `.npmrc` file in your `checkly.config.ts` 3. Store authentication tokens as [environment variables](/platform/variables) in Checkly + +If your private packages come from an internal registry that Checkly can't reach, such as a registry behind your firewall or VPN, see [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) to embed them in the code bundle instead. + + ### Configure authentication to private dependencies All package managers (npm, yarn, pnpm) use `.npmrc` files to authenticate with private registries. diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx new file mode 100644 index 00000000..38e56536 --- /dev/null +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -0,0 +1,275 @@ +--- +title: 'Private Packages and Internal Registries in Playwright Check Suites' +description: 'Run Playwright Check Suites that depend on private packages from internal registries Checkly cannot reach, by embedding and pruning dependencies in the code bundle.' +sidebarTitle: 'Internal Registries' +canonical: 'https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries/' +--- + +When you run `npx checkly test` or `npx checkly deploy`, the CLI packs your Playwright tests into a code bundle together with the files your package manager needs: `package.json` files, the lockfile, and `.npmrc`. Before each run, Checkly installs your dependencies from that bundle, fetching packages from the registries your project uses. + +That install fails when your project depends on private packages from an internal registry that Checkly can't reach, such as an Artifactory, Nexus, or Verdaccio instance behind your firewall or VPN, or an intranet-only mirror of the public npm registry. This page covers the CLI options for those setups. + + +If your private registry is reachable from the internet and only needs a token, such as GitHub Packages or a hosted npm organization, you don't need this page. Configure your `.npmrc` as described in [Using private dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#using-private-dependencies). + + +Choose the option that matches your setup: + +| Situation | Option | +|-----------|--------| +| Your private packages are only available from an internal registry Checkly can't reach | [Embed the packages](#embed-private-packages) with `bundle.packages.embed` | +| Your `.npmrc` points at an internal mirror, but the packages are also available from registries Checkly can reach | [Route runner installs](#route-runner-installs-to-other-registries) with `runner.registries` | +| Your monorepo has internal packages that your checks don't use, in workspace members outside the code bundle | [Lockfile pruning](#lockfile-pruning) leaves them out automatically | +| The install still pulls in internal packages your checks don't use, such as unused peer dependencies | [Prune manifest dependencies](#prune-manifest-dependencies) with `bundle.packages.prune` | + +All of these options apply to Playwright Check Suites only, not to Browser Checks or Multistep Checks. You configure them at the top level of `checkly.config.ts`, not per check. + +## Embed private packages + +Available since CLI version 8.22.0. `!` exclusions and `**` patterns that match across the `/` in scoped names require CLI version 8.23.0. + +If some of your dependencies come from a private registry that Checkly's infrastructure can't reach, list them in `bundle.packages.embed`. The CLI downloads those packages on the machine where you run it, verifies each tarball against the integrity hash in your lockfile, and ships them inside the code bundle. The runner then installs them without contacting your registry. + +```typescript checkly.config.ts highlight={6-10} +import { defineConfig } from 'checkly' + +export default defineConfig({ + projectName: 'Acme Website', + logicalId: 'acme-website', + bundle: { + packages: { + embed: ['@acme/*', '!@acme/public-sdk', 'legacy-private-pkg@2.1.0'], + }, + }, + checks: { + playwrightConfigPath: './playwright.config.ts', + playwrightChecks: [ + // ... + ], + }, +}) +``` + +Each entry is one of: + +- A package name, such as `'@acme/private-utils'`. Embeds every version of the package found in the lockfile. +- An exact version pin, such as `'legacy-private-pkg@2.1.0'`. +- A name [pattern](#package-name-patterns), such as `'@acme/*'`, optionally prefixed with `!` to exclude packages that earlier entries selected. + +List every package the runner can't fetch, including private packages that are only transitive dependencies of other private packages. Dependencies of listed packages are not embedded automatically. + +### Supported lockfiles + +The CLI resolves entries against the lockfile at the workspace root: + +| Lockfile | Supported | +|----------|-----------| +| `pnpm-lock.yaml` | ✅ | +| `package-lock.json` | ✅ | +| `bun.lock` (text format) | ✅ | +| `yarn.lock` (Yarn Berry, v2 and later) | ✅ | +| `yarn.lock` (Yarn Classic, v1) | ❌ | +| `bun.lockb` (binary format) | ❌ Run `bun install --save-text-lockfile` to create a `bun.lock` | + +Yarn Berry lockfiles don't record npm tarball hashes, so for Yarn Berry the CLI fetches them from your registry's package metadata on every deploy. + +### Validation + +The CLI validates the list before deploying: + +- An entry that matches no package in the lockfile fails validation and blocks the deploy. Only list packages your project actually uses. +- An entry whose only matches can't be embedded also fails validation. Packages installed from git, a local path, or a URL, and lockfile entries without an integrity hash, can't be embedded; the runner must fetch them itself. +- A `!` exclusion that matches nothing is ignored. +- A list that ends up selecting no packages at all only prints a warning. + +### Registry credentials + +Embedded packages are downloaded on the machine running the CLI, so your registry credentials must work there, not only in Checkly. The CLI reads credentials from: + +- The project, workspace root, and user `.npmrc` files +- `npm_config_*` environment variables +- pnpm's global `auth.ini`, where `pnpm login` stores tokens on pnpm 11 and later + +Scope tokens to the registry (`//registry.example.com/:_authToken=${NPM_TOKEN}`) rather than setting a bare `_authToken`. Because `.npmrc` is uploaded with the code bundle, reference tokens through environment variables instead of writing them in plain text, and make sure those variables are set wherever you run `checkly test` or `checkly deploy`. + +If you use bun or Yarn Berry and your credentials only live in `bunfig.toml` or `.yarnrc.yml`, copy them into `.npmrc` or set them as `npm_config_*` variables; the CLI doesn't read those files. bun projects must also keep their registry URLs in `.npmrc`. + +If a download fails to authenticate, the error names the credential source the CLI used. + +## Pruning + +Pruning reduces what the runner installs to what your code bundle needs. This keeps internal packages your checks never use out of the install, so you don't have to embed them or make their registry reachable. The CLI never modifies the files on disk; it only rewrites the copies in the code bundle. + +### Lockfile pruning + +Available since CLI version 8.23.0. `CHECKLY_LOCKFILE_PRUNE_TIMEOUT` requires CLI version 9.2.0. + +In a monorepo, your code bundle often contains only some of the workspace members. Installing from the full lockfile would make the runner fetch dependencies of members that aren't in the bundle, and fail if any of those come from a registry it can't reach. The CLI therefore prunes the bundled lockfile to the bundle's contents automatically. You don't need to configure anything. + +Lockfile pruning supports the same lockfiles as [embedding](#supported-lockfiles), and requires your package manager to be installed on the machine running the CLI. pnpm and npm reuse their local caches and only contact your registry for packages they haven't cached; Yarn Berry and bun prune offline. + +If pruning is needed but can't run or can't verify its result, the CLI ships the original lockfile unchanged and prints a note explaining why. Embedding follows the pruned lockfile: a package that only workspace members outside the bundle depend on is not embedded, even if an entry matches it, because the runner never installs it. + +Control lockfile pruning with these environment variables: + +| Variable | Description | +|----------|-------------| +| `CHECKLY_LOCKFILE_PRUNE` | Set to `0` or `false` to turn lockfile pruning off. This also turns off [`bundle.packages.prune`](#prune-manifest-dependencies) when a lockfile is bundled. | +| `CHECKLY_LOCKFILE_PRUNE_TIMEOUT` | Time budget for pruning, in seconds. Defaults to `30`. Raise it if pruning times out, for example `CHECKLY_LOCKFILE_PRUNE_TIMEOUT=120`. Set to `0` to turn the timeout off. | + +If a package you need stops being embedded after pruning, the workspace member that depends on it is probably not part of the bundle. Import that member from your test code instead of turning pruning off. + +### Prune manifest dependencies + +Available since CLI version 8.23.0. Member-scoped entries require CLI version 8.23.1. + +Use `bundle.packages.prune` to remove dependencies from the `package.json` files in the code bundle: the workspace root's and every bundled workspace member's. The CLI rewrites the manifests before it prunes the lockfile, so the removed packages drop out of the bundled lockfile too. + +The most common use is unused peer dependencies. With pnpm's `auto-install-peers` setting, which is on by default, a member's peer dependencies end up in the lockfile even when your tests never import them. If those peers come from a registry Checkly can't reach, the install fails: + +```typescript checkly.config.ts highlight={6-10} +import { defineConfig } from 'checkly' + +export default defineConfig({ + projectName: 'Acme Website', + logicalId: 'acme-website', + bundle: { + packages: { + prune: { peerDependencies: true }, + }, + }, +}) +``` + +`prune` accepts two forms: + + + + +An array of package name [patterns](#package-name-patterns). Matching packages are removed from every dependency class of every bundled `package.json`: + +```typescript checkly.config.ts +bundle: { + packages: { + // Remove the @acme scope, except @acme/runtime + prune: ['@acme/*', '!@acme/runtime', 'storybook'], + }, +}, +``` + + + + +An object keyed by dependency class: `dependencies`, `devDependencies`, `peerDependencies`, or `optionalDependencies`. Each value is `true` to remove the whole class, or a pattern list to remove only matching packages from that class: + +```typescript checkly.config.ts +bundle: { + packages: { + prune: { + peerDependencies: true, + devDependencies: ['@storybook/**', 'eslint*'], + }, + }, +}, +``` + +`true` can't be combined with `!` exclusions. To remove a whole class except some packages, use `['**', '!package-to-keep']`. + + + + +Unlike `embed`, prune patterns don't accept version pins. A pattern that matches nothing is ignored. Removing a peer dependency also removes its `peerDependenciesMeta` entry. + +#### Target specific workspace members + +To prune only some workspace members, use member-scoped entries in the array form. `member` is a pattern list matched against each manifest's `name`; use `'.'` for the workspace root. Each entry has exactly one of `remove` or `keep`, which take a pattern list or a per-class object: + +```typescript checkly.config.ts +bundle: { + packages: { + prune: [ + // Remove packages from matching members only + { member: ['@acme/web'], remove: { peerDependencies: true } }, + // Declare the member's complete dependency set; everything else is removed + { member: ['@acme/e2e'], keep: { dependencies: ['@acme/test-utils'] } }, + ], + }, +}, +``` + +- `remove` works like the global patterns, but only for the matched members. Entries apply in the order you list them. +- `keep` declares a member's entire remaining dependency set. Anything it doesn't select is removed, classes a per-class `keep` doesn't mention are emptied, and no other entry can remove a kept package. `keep: []` removes every dependency. + +Prefer exact member names with `keep`, since a wildcard can match a member you add later. The CLI warns when a `member` selector matches no workspace member, or when a `keep` pattern keeps nothing in a bundled member. + +#### Requirements and caveats + +- When the bundle contains a lockfile, `prune` only takes effect if lockfile pruning succeeds in the same run, so the manifests and lockfile stay in sync. Otherwise the original `package.json` files ship unchanged and the CLI prints a warning. A bundle without a lockfile always ships the pruned manifests. +- The CLI doesn't check your code against the pruned dependencies. Don't remove anything your tests need at runtime. + +## Route runner installs to other registries + +Available since CLI version 8.23.0. + +If your `.npmrc` points at a registry URL that only works on your network, such as a VPN-only mirror, but the same packages are available to Checkly from other registries, use `runner.registries` instead of embedding. It tells the runner which registries to install from, replacing the registries named in the bundled configuration files: + +```typescript checkly.config.ts highlight={6-20} +import { defineConfig } from 'checkly' + +export default defineConfig({ + projectName: 'Acme Website', + logicalId: 'acme-website', + runner: { + registries: { + upstreams: { + acme: { + url: 'https://npm.acme.example.com/', + auth: { type: 'bearer', token: '${ACME_NPM_TOKEN}' }, + }, + npmjs: { url: 'https://registry.npmjs.org/' }, + }, + packages: [ + { pattern: '@acme/*', upstreams: ['acme'] }, + { pattern: '**', upstreams: ['npmjs'] }, + ], + }, + }, +}) +``` + +- `upstreams` names the registries the runner may use. A `token` must be a single `${VARIABLE}` reference to a Checkly [environment variable](/platform/variables), which the runner resolves at install time. Literal tokens are rejected. +- `packages` routes package names to upstreams. The first rule whose [pattern](#package-name-patterns) matches wins. The runner tries the rule's upstreams in order, but never falls through to a later rule, so private package names aren't sent to a broader registry. The last rule must be `{ pattern: '**', ... }`. +- Routing patterns don't accept `!` exclusions or version pins. +- [Embedded packages](#embed-private-packages) always take priority over routing rules. + +`runner.registries` only affects the install on Checkly. Embedding and lockfile pruning still run on your machine and use your `.npmrc` credentials. + +## Package name patterns + +`bundle.packages.embed`, `bundle.packages.prune`, and `runner.registries` share the same pattern syntax: + +| Pattern | Matches | +|---------|---------| +| `@acme/utils` | Exactly `@acme/utils` | +| `@acme/*` | Every package in the `@acme` scope | +| `acme-*` | Unscoped packages starting with `acme-` | +| `*` | Every unscoped package. A single `*` never crosses the `/` in a scoped name. | +| `**` | Every package, scoped or not | +| `**/utils` | `utils` and `utils` in any scope, such as `@acme/utils` | +| `!@acme/legacy` | Excludes `@acme/legacy` from what earlier entries selected (`embed` and `prune` only) | + +Exclusions only remove packages selected by entries before them, so order matters: `['@acme/*', '!@acme/legacy']` selects the scope except `@acme/legacy`, while `['!@acme/legacy', '@acme/*']` selects the whole scope. + +## Troubleshooting + +### See what was embedded or pruned + +Run the CLI with debug logging to see which packages each `embed` entry matched, and why lockfile pruning was skipped: + +```bash Terminal +DEBUG='checkly:cli:services:embedded-packages,checkly:cli:services:check-parser:*' npx checkly test +``` + +### Dependencies are reinstalled after a change + +Changing the set of embedded packages, the pruned manifests, or `runner.registries` invalidates the runner's [dependency cache](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#dependency-caching). The next run installs dependencies from scratch. diff --git a/docs.json b/docs.json index 9a7bccc7..30b44cac 100644 --- a/docs.json +++ b/docs.json @@ -259,6 +259,7 @@ "detect/synthetic-monitoring/playwright-checks/performance-metrics", "detect/synthetic-monitoring/playwright-checks/add-to-group", "detect/synthetic-monitoring/playwright-checks/custom-dependencies", + "detect/synthetic-monitoring/playwright-checks/internal-registries", "detect/synthetic-monitoring/playwright-checks/environment-variables", "detect/synthetic-monitoring/playwright-checks/timeouts" ] diff --git a/sitemap.xml b/sitemap.xml index 10811eeb..3faab70a 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -1191,6 +1191,9 @@ https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/environment-variables/ + + https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries/ + https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/overview/ From f7301a5f430e453d21bc2a4953c247fad13a0554 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 14:42:47 +0900 Subject: [PATCH 02/17] docs: explain how embedding and pruning treat dependencies of dependencies (RED-1310) Co-Authored-By: Claude Opus 5.5 --- .../playwright-checks/internal-registries.mdx | 31 +++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 38e56536..577f7b34 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -56,7 +56,7 @@ Each entry is one of: - An exact version pin, such as `'legacy-private-pkg@2.1.0'`. - A name [pattern](#package-name-patterns), such as `'@acme/*'`, optionally prefixed with `!` to exclude packages that earlier entries selected. -List every package the runner can't fetch, including private packages that are only transitive dependencies of other private packages. Dependencies of listed packages are not embedded automatically. +List every package the runner can't fetch, including private packages that are only dependencies of other private packages. Embedding a package doesn't embed its dependencies; see [Dependencies of dependencies](#dependencies-of-dependencies). ### Supported lockfiles @@ -178,7 +178,7 @@ bundle: { -Unlike `embed`, prune patterns don't accept version pins. A pattern that matches nothing is ignored. Removing a peer dependency also removes its `peerDependenciesMeta` entry. +Unlike `embed`, prune patterns don't accept version pins. A pattern that matches nothing is ignored. Removing a peer dependency also removes its `peerDependenciesMeta` entry. Patterns only match dependencies declared in `package.json` files; see [Dependencies of dependencies](#dependencies-of-dependencies). #### Target specific workspace members @@ -244,6 +244,33 @@ export default defineConfig({ `runner.registries` only affects the install on Checkly. Embedding and lockfile pruning still run on your machine and use your `.npmrc` credentials. +## Dependencies of dependencies + +Your lockfile records every package the install needs, including dependencies of your dependencies (transitive dependencies). Each option handles them differently: + +| Option | Dependencies of dependencies | +|--------|------------------------------| +| `bundle.packages.embed` | Entries match packages at any depth in the lockfile, so you can embed a transitive dependency by name. Embedding a package doesn't embed its dependencies. | +| Lockfile pruning | Removes the dependencies of workspace members outside the bundle at every depth, except packages that something in the bundle still needs. | +| `bundle.packages.prune` | Patterns only match dependencies declared in `package.json` files; a pattern that names a package that is only a transitive dependency has no effect. Removing a declared dependency also removes the transitive dependencies that only it needed from the bundled lockfile. | +| `runner.registries` | Routing rules apply to every package the runner installs, at any depth. | + +### Embed private dependency chains + +The runner installs the dependencies of an embedded package like any other package, from the registries your project uses. That works for public dependencies, but if an embedded package depends on other private packages from the same unreachable registry, you must embed those too. The CLI doesn't detect a missing one; the install on Checkly fails when it can't fetch it. + +For example, if `@acme/ui` depends on the private `@acme/tokens` and the public `react`, embed both private packages and let the runner fetch `react` from npm: + +```typescript checkly.config.ts +bundle: { + packages: { + embed: ['@acme/ui', '@acme/tokens'], + }, +}, +``` + +If your private packages share a scope, a wildcard such as `@acme/*` embeds the whole scope at every depth, including private packages you only depend on indirectly. + ## Package name patterns `bundle.packages.embed`, `bundle.packages.prune`, and `runner.registries` share the same pattern syntax: From efdf62e26693176d7b90e8aa5437c82e852d03b9 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 14:45:24 +0900 Subject: [PATCH 03/17] docs: update Custom Dependencies for automatic .npmrc bundling, bun and the cache version (RED-1310) The CLI bundles .npmrc files automatically since CLI version 8.15.0, so the checks.include step now only applies to older versions. Add bun to the supported package managers, list the current dependency cache inputs, and document runner.cache.install.version and --refresh-cache for forcing a reinstall. Co-Authored-By: Claude Opus 5.5 --- constructs/project.mdx | 2 +- .../playwright-checks/custom-dependencies.mdx | 45 +++++++++++++++---- 2 files changed, 38 insertions(+), 9 deletions(-) diff --git a/constructs/project.mdx b/constructs/project.mdx index eaa42897..0293fc6c 100644 --- a/constructs/project.mdx +++ b/constructs/project.mdx @@ -75,7 +75,7 @@ export default defineConfig({ | `checks` | `object` | ❌ | - | Top-level defaults for all checks in this project | | `cli` | `object` | ❌ | - | Defaults for CLI commands | | `bundle` | `object` | ❌ | - | Dependency embedding and pruning for Playwright Check Suite code bundles. See [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) | -| `runner` | `object` | ❌ | - | Settings applied on Checkly runners, such as registry routing for Playwright Check Suite installs. See [Route runner installs](/detect/synthetic-monitoring/playwright-checks/internal-registries#route-runner-installs-to-other-registries) | +| `runner` | `object` | ❌ | - | Settings applied on Checkly runners for Playwright Check Suite installs: [registry routing](/detect/synthetic-monitoring/playwright-checks/internal-registries#route-runner-installs-to-other-registries) and the [dependency cache version](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#force-a-reinstall) | ### Core Project Options diff --git a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx index ab02d521..453c212f 100644 --- a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx +++ b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx @@ -13,7 +13,7 @@ Playwright Check Suites do not use Checkly runtimes. Browser Checks and Multiste ## 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/), and [pnpm](https://pnpm.io/). +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`). @@ -36,6 +36,7 @@ Checkly detects your package manager from your lock file: | `package-lock.json` | npm | | `pnpm-lock.yaml` | pnpm | | `yarn.lock` | yarn | +| `bun.lock` | bun | ### Workspace support @@ -79,8 +80,7 @@ Checkly supports private packages. To authenticate with your private registry, c 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](/platform/variables) in Checkly +2. Store authentication tokens as [environment variables](/platform/variables) in Checkly If your private packages come from an internal registry that Checkly can't reach, such as a registry behind your firewall or VPN, see [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) to embed them in the code bundle instead. @@ -127,9 +127,9 @@ registry=https://yourcompany.jfrog.io/artifactory/api/npm/npm-local/:_authToken= ### 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 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. -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. +On CLI versions before 8.15.0, add your `.npmrc` file to the `checks.include` property in your `checkly.config.ts` instead: ```typescript checkly.config.ts highlight={6} import { defineConfig } from 'checkly' @@ -190,7 +190,7 @@ Learn more about [customizing install commands](/detect/synthetic-monitoring/pla ## 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`, your working directory, or your [`engine`](/constructs/playwright-check#param-engine) change. +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 file, the `package.json` or `.npmrc` files in your workspace, a pnpm `.pnpmfile.cjs` or `.pnpmfile.mjs` at the workspace root, your `installCommand`, your working directory, or your [`engine`](/constructs/playwright-check#param-engine) change. Changes to [embedded or pruned packages and registry routing](/detect/synthetic-monitoring/playwright-checks/internal-registries) also invalidate the cache. ### How caching works @@ -205,6 +205,34 @@ Caching significantly reduces check execution time, especially for projects with 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`. + +```typescript checkly.config.ts highlight={6-12} +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. + + +`runner.cache.install.version` is available since CLI version 9.1.0. CLI versions 8.20.0 to 9.x also accept the older `caching.dependencyCache.version`, which CLI version 10 no longer supports. + + +For a one-off fresh install, pass `--refresh-cache` to [`checkly test`](/cli/checkly-test), [`checkly pw-test`](/cli/checkly-pw-test), [`checkly trigger`](/cli/checkly-trigger), or [`checkly checks run`](/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. @@ -238,7 +266,8 @@ Browser caching requires Private Location agent v8.2.0 or later. If you see errors like `404 Not Found` or `Package '@your-org/package' not found`: -- Verify your `.npmrc` file is included in `checks.include` +- Verify your `.npmrc` file is at the workspace root or next to the `package.json` that needs it (on CLI versions before 8.15.0, that it's included in `checks.include`) +- If the registry is only reachable from your own network, see [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) - Check that the registry URL is correct - Ensure your package name matches exactly (including scope) @@ -254,7 +283,7 @@ If you see `401 Unauthorized` or `403 Forbidden` errors: If Checkly uses the wrong package manager: -- Verify the correct lock file is present (`package-lock.json`, `yarn.lock`, or `pnpm-lock.json`) +- 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](/detect/synthetic-monitoring/playwright-checks/configuration#customize-install-and-test-commands)) From 2c509aa4622d41609889e3d1e9c4b8cc446253b3 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 14:51:19 +0900 Subject: [PATCH 04/17] docs: add explained config examples for internal registries (RED-1310) Explain what each embed, prune and runner.registries snippet does, fix the member-scoped keep example to target a library member instead of the test member, and add complete examples for a pnpm monorepo with an internal registry and for a private scope behind a VPN-only mirror. Co-Authored-By: Claude Opus 5.5 --- .../playwright-checks/internal-registries.mdx | 131 +++++++++++++++++- 1 file changed, 126 insertions(+), 5 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 577f7b34..65e48af4 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -30,7 +30,7 @@ All of these options apply to Playwright Check Suites only, not to Browser Check If some of your dependencies come from a private registry that Checkly's infrastructure can't reach, list them in `bundle.packages.embed`. The CLI downloads those packages on the machine where you run it, verifies each tarball against the integrity hash in your lockfile, and ships them inside the code bundle. The runner then installs them without contacting your registry. -```typescript checkly.config.ts highlight={6-10} +```typescript checkly.config.ts highlight={6-14} import { defineConfig } from 'checkly' export default defineConfig({ @@ -38,7 +38,11 @@ export default defineConfig({ logicalId: 'acme-website', bundle: { packages: { - embed: ['@acme/*', '!@acme/public-sdk', 'legacy-private-pkg@2.1.0'], + embed: [ + '@acme/*', + '!@acme/public-sdk', + 'legacy-private-pkg@2.1.0', + ], }, }, checks: { @@ -50,6 +54,8 @@ export default defineConfig({ }) ``` +This config embeds every package in the `@acme` scope that your lockfile contains, except `@acme/public-sdk`, which the runner must then fetch itself. If your `.npmrc` sends the whole `@acme` scope to your internal registry, route `@acme/public-sdk` to a registry the runner can reach with [`runner.registries`](#route-runner-installs-to-other-registries). It also embeds version 2.1.0 of the unscoped `legacy-private-pkg`. Every other package installs from its usual registry. + Each entry is one of: - A package name, such as `'@acme/private-utils'`. Embeds every version of the package found in the lockfile. @@ -79,6 +85,7 @@ The CLI validates the list before deploying: - An entry that matches no package in the lockfile fails validation and blocks the deploy. Only list packages your project actually uses. - An entry whose only matches can't be embedded also fails validation. Packages installed from git, a local path, or a URL, and lockfile entries without an integrity hash, can't be embedded; the runner must fetch them itself. +- In a pnpm workspace, an entry that also matches a workspace member that another member depends on prints a warning on every run, because workspace members are bundled as source code rather than embedded. Exclude those members with `!`, for example `['@acme/*', '!@acme/design-system']`. - A `!` exclusion that matches nothing is ignored. - A list that ends up selecting no packages at all only prints a warning. @@ -141,6 +148,8 @@ export default defineConfig({ }) ``` +This config removes every entry under `peerDependencies` from the workspace root's and each bundled member's `package.json`. When the CLI then prunes the lockfile, the peers that were only installed to satisfy those entries drop out, so the runner doesn't try to fetch them. + `prune` accepts two forms: @@ -157,6 +166,8 @@ bundle: { }, ``` +This removes every `@acme` package except `@acme/runtime`, plus `storybook`, from `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies`. + @@ -173,6 +184,8 @@ bundle: { }, ``` +This removes all peer dependencies, and removes the `@storybook` scope and unscoped packages starting with `eslint` from `devDependencies` only. `dependencies` and `optionalDependencies` are left as they are. + `true` can't be combined with `!` exclusions. To remove a whole class except some packages, use `['**', '!package-to-keep']`. @@ -189,14 +202,22 @@ bundle: { packages: { prune: [ // Remove packages from matching members only - { member: ['@acme/web'], remove: { peerDependencies: true } }, - // Declare the member's complete dependency set; everything else is removed - { member: ['@acme/e2e'], keep: { dependencies: ['@acme/test-utils'] } }, + { + member: ['@acme/web'], + remove: { peerDependencies: true }, + }, + // Declare the member's complete dependency set + { + member: ['@acme/design-system'], + keep: { dependencies: ['@acme/tokens'] }, + }, ], }, }, ``` +The first entry removes the peer dependencies of `@acme/web` and leaves every other member's peers in place. The second entry reduces `@acme/design-system` to a single dependency, `@acme/tokens`: its other `dependencies` and all of its `devDependencies`, `peerDependencies`, and `optionalDependencies` are removed. + - `remove` works like the global patterns, but only for the matched members. Entries apply in the order you list them. - `keep` declares a member's entire remaining dependency set. Anything it doesn't select is removed, classes a per-class `keep` doesn't mention are emptied, and no other entry can remove a kept package. `keep: []` removes every dependency. @@ -237,6 +258,8 @@ export default defineConfig({ }) ``` +With this config, the runner installs `@acme` packages only from `https://npm.acme.example.com/`, authenticating with the `ACME_NPM_TOKEN` environment variable, and every other package from the public npm registry. If an `@acme` package is missing from the Acme registry, the install fails instead of asking the public registry for it. + - `upstreams` names the registries the runner may use. A `token` must be a single `${VARIABLE}` reference to a Checkly [environment variable](/platform/variables), which the runner resolves at install time. Literal tokens are rejected. - `packages` routes package names to upstreams. The first rule whose [pattern](#package-name-patterns) matches wins. The runner tries the rule's upstreams in order, but never falls through to a later rule, so private package names aren't sent to a broader registry. The last rule must be `{ pattern: '**', ... }`. - Routing patterns don't accept `!` exclusions or version pins. @@ -271,6 +294,104 @@ bundle: { If your private packages share a scope, a wildcard such as `@acme/*` embeds the whole scope at every depth, including private packages you only depend on indirectly. +## Examples + +### Monorepo with an internal registry + +Your tests live in one member of a pnpm workspace, and your `.npmrc` points the `@acme` scope at a registry that's only reachable from your network: + +```text +acme/ +├── .npmrc # Points @acme at the internal registry +├── package.json +├── pnpm-lock.yaml +└── packages/ + ├── e2e/ # Tests and checkly.config.ts + ├── design-system/ # Imported by the tests + └── admin/ # Not used by the tests +``` + +`design-system` depends on the private `@acme/tokens` and declares the private `@acme/analytics` as a peer dependency, which the tests don't use. `admin` depends on the private `@acme/billing-sdk`. + +```typescript packages/e2e/checkly.config.ts +import { defineConfig } from 'checkly' + +export default defineConfig({ + projectName: 'Acme Website', + logicalId: 'acme-website', + bundle: { + packages: { + embed: [ + '@acme/*', + '!@acme/design-system', // Workspace member, bundled as source + ], + prune: [ + { + member: ['@acme/design-system'], + remove: { peerDependencies: ['@acme/analytics'] }, + }, + ], + }, + }, + checks: { + playwrightConfigPath: './playwright.config.ts', + playwrightChecks: [ + { name: 'Acme E2E', logicalId: 'acme-e2e' }, + ], + }, +}) +``` + +When you run `npx checkly deploy`, the CLI: + +1. Bundles `e2e` and `design-system`, because the tests import `design-system`. `admin` is left out. +2. Removes `@acme/analytics` from the bundled copy of `design-system`'s `package.json`. +3. Prunes the bundled lockfile to the bundle's contents. `@acme/billing-sdk` drops out because only `admin` needs it, and `@acme/analytics` drops out because nothing declares it anymore. +4. Embeds the `@acme` packages that remain in the pruned lockfile, here `@acme/tokens`, downloading them through your `.npmrc`. The `!@acme/design-system` exclusion keeps the pattern away from the workspace member, which is bundled as source code and can't be embedded. + +On Checkly, the runner installs `@acme/tokens` from the bundle and all public packages from npm. It never contacts your internal registry. + +The `prune` entry isn't required for the install to work: without it, `@acme/*` would also embed `@acme/analytics`. Pruning the unused peer saves downloading and shipping a package the tests never load. It becomes required when the runner can neither install the peer from the bundle nor fetch it itself, for example a peer installed from an internal Git server. + +### Private scope behind a VPN-only mirror + +Your `.npmrc` sends every install through a mirror that's only reachable on your VPN. The mirror proxies the public npm registry and also hosts your `@acme` packages: + +```text .npmrc +registry=https://npm-mirror.vpn.acme.example.com/ +``` + +```typescript checkly.config.ts +import { defineConfig } from 'checkly' + +export default defineConfig({ + projectName: 'Acme Website', + logicalId: 'acme-website', + bundle: { + packages: { + embed: ['@acme/*'], + }, + }, + runner: { + registries: { + upstreams: { + npmjs: { url: 'https://registry.npmjs.org/' }, + }, + packages: [ + { pattern: '**', upstreams: ['npmjs'] }, + ], + }, + }, +}) +``` + +The two options split the work: + +- `embed` downloads the `@acme` packages through the mirror on your machine, where the VPN is available, and ships them in the code bundle. +- `runner.registries` sends every other package to the public npm registry instead of the mirror. Embedded packages take priority over routing rules, so the `@acme` packages never reach the `**` rule. + +Run `checkly test` and `checkly deploy` with the VPN connected, so the CLI can download the embedded packages. + ## Package name patterns `bundle.packages.embed`, `bundle.packages.prune`, and `runner.registries` share the same pattern syntax: From f3bec581c6e4bd6a09471d68ce6abfda65bbe297 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 15:10:41 +0900 Subject: [PATCH 05/17] docs: describe pruning as a way to speed up dependency installs (RED-1310) Add a section with an example that prunes development tooling from the bundled package.json files, and link to it from the Custom Dependencies caching and troubleshooting sections. Co-Authored-By: Claude Opus 5.5 --- .../playwright-checks/custom-dependencies.mdx | 4 ++ .../playwright-checks/internal-registries.mdx | 51 +++++++++++++++++-- 2 files changed, 51 insertions(+), 4 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx index 453c212f..2d8e3d4d 100644 --- a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx +++ b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx @@ -203,6 +203,8 @@ When dependency caching is enabled: 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. To make those installs faster, remove dependencies your checks don't use, such as linters or Storybook, from the code bundle with [`bundle.packages.prune`](/detect/synthetic-monitoring/playwright-checks/internal-registries#speed-up-dependency-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 @@ -292,6 +294,7 @@ If Checkly uses the wrong package manager: 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`](/detect/synthetic-monitoring/playwright-checks/internal-registries#speed-up-dependency-installs) - Consider using a custom `installCommand` to install only required packages ### Memory usage exceeded @@ -299,6 +302,7 @@ If package installation exceeds time limits: 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`](/detect/synthetic-monitoring/playwright-checks/internal-registries#speed-up-dependency-installs) - Consider using a custom `installCommand` to install only necessary packages ### General installation failures diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 65e48af4..3716af3e 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -1,16 +1,16 @@ --- title: 'Private Packages and Internal Registries in Playwright Check Suites' -description: 'Run Playwright Check Suites that depend on private packages from internal registries Checkly cannot reach, by embedding and pruning dependencies in the code bundle.' +description: 'Run Playwright Check Suites that depend on private packages from internal registries Checkly cannot reach, and speed up dependency installs, by embedding and pruning dependencies in the code bundle.' sidebarTitle: 'Internal Registries' canonical: 'https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries/' --- When you run `npx checkly test` or `npx checkly deploy`, the CLI packs your Playwright tests into a code bundle together with the files your package manager needs: `package.json` files, the lockfile, and `.npmrc`. Before each run, Checkly installs your dependencies from that bundle, fetching packages from the registries your project uses. -That install fails when your project depends on private packages from an internal registry that Checkly can't reach, such as an Artifactory, Nexus, or Verdaccio instance behind your firewall or VPN, or an intranet-only mirror of the public npm registry. This page covers the CLI options for those setups. +That install fails when your project depends on private packages from an internal registry that Checkly can't reach, such as an Artifactory, Nexus, or Verdaccio instance behind your firewall or VPN, or an intranet-only mirror of the public npm registry. This page covers the CLI options for those setups. The pruning options also [speed up dependency installs](#speed-up-dependency-installs) in any project, because the runner installs fewer packages. -If your private registry is reachable from the internet and only needs a token, such as GitHub Packages or a hosted npm organization, you don't need this page. Configure your `.npmrc` as described in [Using private dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#using-private-dependencies). +If your private registry is reachable from the internet and only needs a token, such as GitHub Packages or a hosted npm organization, you don't need to embed or route packages. Configure your `.npmrc` as described in [Using private dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#using-private-dependencies). Choose the option that matches your setup: @@ -21,6 +21,7 @@ Choose the option that matches your setup: | Your `.npmrc` points at an internal mirror, but the packages are also available from registries Checkly can reach | [Route runner installs](#route-runner-installs-to-other-registries) with `runner.registries` | | Your monorepo has internal packages that your checks don't use, in workspace members outside the code bundle | [Lockfile pruning](#lockfile-pruning) leaves them out automatically | | The install still pulls in internal packages your checks don't use, such as unused peer dependencies | [Prune manifest dependencies](#prune-manifest-dependencies) with `bundle.packages.prune` | +| Dependency installs are slow because your `package.json` declares tooling your checks don't use, such as linters | [Speed up dependency installs](#speed-up-dependency-installs) with `bundle.packages.prune` | All of these options apply to Playwright Check Suites only, not to Browser Checks or Multistep Checks. You configure them at the top level of `checkly.config.ts`, not per check. @@ -105,7 +106,7 @@ If a download fails to authenticate, the error names the credential source the C ## Pruning -Pruning reduces what the runner installs to what your code bundle needs. This keeps internal packages your checks never use out of the install, so you don't have to embed them or make their registry reachable. The CLI never modifies the files on disk; it only rewrites the copies in the code bundle. +Pruning reduces what the runner installs to what your code bundle needs. This keeps internal packages your checks never use out of the install, so you don't have to embed them or make their registry reachable, and it makes the install faster. The CLI never modifies the files on disk; it only rewrites the copies in the code bundle. ### Lockfile pruning @@ -228,6 +229,48 @@ Prefer exact member names with `keep`, since a wildcard can match a member you a - When the bundle contains a lockfile, `prune` only takes effect if lockfile pruning succeeds in the same run, so the manifests and lockfile stay in sync. Otherwise the original `package.json` files ship unchanged and the CLI prints a warning. A bundle without a lockfile always ships the pruned manifests. - The CLI doesn't check your code against the pruned dependencies. Don't remove anything your tests need at runtime. +### Speed up dependency installs + +The runner installs your dependencies whenever the [dependency cache](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#dependency-caching) 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 pruning packages your checks never load makes those runs start faster. + +In a monorepo, [lockfile pruning](#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: + +```typescript checkly.config.ts highlight={6-19} +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. Keep these points in mind: + +- Only remove packages your tests don't import or run. The CLI doesn't check this for you. +- A prune change that alters the bundled `package.json` files or lockfile invalidates the dependency cache once, so the next run does a full install. Patterns that match nothing leave the cache untouched. + ## Route runner installs to other registries Available since CLI version 8.23.0. From 627355756d4cc9e3ef27854f1aba83d523b7ae16 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 15:14:15 +0900 Subject: [PATCH 06/17] docs: describe only the latest CLI in the dependency pages (RED-1310) Drop the "Available since" CLI version callouts and the instructions for older CLI versions. Co-Authored-By: Claude Opus 5.5 --- .../playwright-checks/custom-dependencies.mdx | 24 +------------------ .../playwright-checks/internal-registries.mdx | 8 ------- 2 files changed, 1 insertion(+), 31 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx index 2d8e3d4d..dc4446ef 100644 --- a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx +++ b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx @@ -129,24 +129,6 @@ registry=https://yourcompany.jfrog.io/artifactory/api/npm/npm-local/:_authToken= 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. -On CLI versions before 8.15.0, add your `.npmrc` file to the `checks.include` property in your `checkly.config.ts` instead: - -```typescript checkly.config.ts highlight={6} -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. @@ -229,10 +211,6 @@ export default defineConfig({ 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. - -`runner.cache.install.version` is available since CLI version 9.1.0. CLI versions 8.20.0 to 9.x also accept the older `caching.dependencyCache.version`, which CLI version 10 no longer supports. - - For a one-off fresh install, pass `--refresh-cache` to [`checkly test`](/cli/checkly-test), [`checkly pw-test`](/cli/checkly-pw-test), [`checkly trigger`](/cli/checkly-trigger), or [`checkly checks run`](/cli/checkly-checks) instead. ### Automatic retries @@ -268,7 +246,7 @@ Browser caching requires Private Location agent v8.2.0 or later. 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 (on CLI versions before 8.15.0, that it's included in `checks.include`) +- 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 [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) - Check that the registry URL is correct - Ensure your package name matches exactly (including scope) diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 3716af3e..121f86e5 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -27,8 +27,6 @@ All of these options apply to Playwright Check Suites only, not to Browser Check ## Embed private packages -Available since CLI version 8.22.0. `!` exclusions and `**` patterns that match across the `/` in scoped names require CLI version 8.23.0. - If some of your dependencies come from a private registry that Checkly's infrastructure can't reach, list them in `bundle.packages.embed`. The CLI downloads those packages on the machine where you run it, verifies each tarball against the integrity hash in your lockfile, and ships them inside the code bundle. The runner then installs them without contacting your registry. ```typescript checkly.config.ts highlight={6-14} @@ -110,8 +108,6 @@ Pruning reduces what the runner installs to what your code bundle needs. This ke ### Lockfile pruning -Available since CLI version 8.23.0. `CHECKLY_LOCKFILE_PRUNE_TIMEOUT` requires CLI version 9.2.0. - In a monorepo, your code bundle often contains only some of the workspace members. Installing from the full lockfile would make the runner fetch dependencies of members that aren't in the bundle, and fail if any of those come from a registry it can't reach. The CLI therefore prunes the bundled lockfile to the bundle's contents automatically. You don't need to configure anything. Lockfile pruning supports the same lockfiles as [embedding](#supported-lockfiles), and requires your package manager to be installed on the machine running the CLI. pnpm and npm reuse their local caches and only contact your registry for packages they haven't cached; Yarn Berry and bun prune offline. @@ -129,8 +125,6 @@ Control lockfile pruning with these environment variables: ### Prune manifest dependencies -Available since CLI version 8.23.0. Member-scoped entries require CLI version 8.23.1. - Use `bundle.packages.prune` to remove dependencies from the `package.json` files in the code bundle: the workspace root's and every bundled workspace member's. The CLI rewrites the manifests before it prunes the lockfile, so the removed packages drop out of the bundled lockfile too. The most common use is unused peer dependencies. With pnpm's `auto-install-peers` setting, which is on by default, a member's peer dependencies end up in the lockfile even when your tests never import them. If those peers come from a registry Checkly can't reach, the install fails: @@ -273,8 +267,6 @@ Pruning works the same way in a single-package project as in a monorepo. Keep th ## Route runner installs to other registries -Available since CLI version 8.23.0. - If your `.npmrc` points at a registry URL that only works on your network, such as a VPN-only mirror, but the same packages are available to Checkly from other registries, use `runner.registries` instead of embedding. It tells the runner which registries to install from, replacing the registries named in the bundled configuration files: ```typescript checkly.config.ts highlight={6-20} From 921602aca6140bd5d4e557566bdeaf24341f3341 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 15:20:37 +0900 Subject: [PATCH 07/17] docs: clarify that embedded packages need no registry credentials in Checkly (RED-1310) Co-Authored-By: Claude Opus 5.5 --- .../playwright-checks/internal-registries.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 121f86e5..8a52e417 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -90,13 +90,13 @@ The CLI validates the list before deploying: ### Registry credentials -Embedded packages are downloaded on the machine running the CLI, so your registry credentials must work there, not only in Checkly. The CLI reads credentials from: +Embedded packages need registry credentials only on the machine running the CLI, which downloads them. The runner installs them from the code bundle and never contacts your registry for them, so you don't need to store your registry token in Checkly; a token reference in the bundled `.npmrc` whose variable isn't set in Checkly doesn't break the install. The CLI reads credentials from: - The project, workspace root, and user `.npmrc` files - `npm_config_*` environment variables - pnpm's global `auth.ini`, where `pnpm login` stores tokens on pnpm 11 and later -Scope tokens to the registry (`//registry.example.com/:_authToken=${NPM_TOKEN}`) rather than setting a bare `_authToken`. Because `.npmrc` is uploaded with the code bundle, reference tokens through environment variables instead of writing them in plain text, and make sure those variables are set wherever you run `checkly test` or `checkly deploy`. +Scope tokens to the registry (`//registry.example.com/:_authToken=${NPM_TOKEN}`) rather than setting a bare `_authToken`. Because `.npmrc` is uploaded with the code bundle, reference tokens through environment variables instead of writing them in plain text, and set those variables wherever you run `checkly test` or `checkly deploy`. Only packages the runner fetches itself need their token stored in Checkly, as described in [Using private dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#using-private-dependencies). If you use bun or Yarn Berry and your credentials only live in `bunfig.toml` or `.yarnrc.yml`, copy them into `.npmrc` or set them as `npm_config_*` variables; the CLI doesn't read those files. bun projects must also keep their registry URLs in `.npmrc`. From 9f5fe316e1001d719c298e3ef42122822e7435ca Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 16:06:40 +0900 Subject: [PATCH 08/17] docs: tighten the options table and the Yarn Berry metadata note (RED-1310) Describe the lockfile-pruning case by the shared lockfile, merge the two bundle.packages.prune rows, and say the Yarn Berry metadata lookup runs whenever checks are bundled while tarball downloads stay cached. Co-Authored-By: Claude Opus 5.5 --- .../playwright-checks/internal-registries.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 8a52e417..85e3279e 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -19,9 +19,8 @@ Choose the option that matches your setup: |-----------|--------| | Your private packages are only available from an internal registry Checkly can't reach | [Embed the packages](#embed-private-packages) with `bundle.packages.embed` | | Your `.npmrc` points at an internal mirror, but the packages are also available from registries Checkly can reach | [Route runner installs](#route-runner-installs-to-other-registries) with `runner.registries` | -| Your monorepo has internal packages that your checks don't use, in workspace members outside the code bundle | [Lockfile pruning](#lockfile-pruning) leaves them out automatically | -| The install still pulls in internal packages your checks don't use, such as unused peer dependencies | [Prune manifest dependencies](#prune-manifest-dependencies) with `bundle.packages.prune` | -| Dependency installs are slow because your `package.json` declares tooling your checks don't use, such as linters | [Speed up dependency installs](#speed-up-dependency-installs) with `bundle.packages.prune` | +| Your monorepo's lockfile includes dependencies of workspace members your checks don't import | [Lockfile pruning](#lockfile-pruning) leaves them out automatically | +| The install pulls in packages your checks don't use, such as unused peer dependencies from your internal registry, or linters that slow the install down | [Prune manifest dependencies](#prune-manifest-dependencies) with `bundle.packages.prune` | All of these options apply to Playwright Check Suites only, not to Browser Checks or Multistep Checks. You configure them at the top level of `checkly.config.ts`, not per check. @@ -76,7 +75,7 @@ The CLI resolves entries against the lockfile at the workspace root: | `yarn.lock` (Yarn Classic, v1) | ❌ | | `bun.lockb` (binary format) | ❌ Run `bun install --save-text-lockfile` to create a `bun.lock` | -Yarn Berry lockfiles don't record npm tarball hashes, so for Yarn Berry the CLI fetches them from your registry's package metadata on every deploy. +Yarn Berry lockfiles don't record npm tarball hashes, so for Yarn Berry the CLI looks them up in your registry's package metadata each time it bundles your checks. Downloaded tarballs are still cached. ### Validation @@ -125,7 +124,7 @@ Control lockfile pruning with these environment variables: ### Prune manifest dependencies -Use `bundle.packages.prune` to remove dependencies from the `package.json` files in the code bundle: the workspace root's and every bundled workspace member's. The CLI rewrites the manifests before it prunes the lockfile, so the removed packages drop out of the bundled lockfile too. +Use `bundle.packages.prune` to remove dependencies from the `package.json` files in the code bundle: the workspace root's and every bundled workspace member's. The CLI rewrites the manifests before it prunes the lockfile, so the removed packages drop out of the bundled lockfile too. Besides the peer dependency case below, you can use it to [speed up dependency installs](#speed-up-dependency-installs). The most common use is unused peer dependencies. With pnpm's `auto-install-peers` setting, which is on by default, a member's peer dependencies end up in the lockfile even when your tests never import them. If those peers come from a registry Checkly can't reach, the install fails: From 3530f1da313cabc0097046501458a5774e26135c Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 21:40:45 +0900 Subject: [PATCH 09/17] docs: fix review findings across the dependency pages (RED-1310) - Validation: workspace members matched by an embed pattern are skipped, and an entry matching only members fails validation - runner.registries ignores bundled credentials and TLS settings; tokens go in its auth entries - Cache notes: only prune patterns and ! exclusions that match nothing leave the cache untouched; the cache-input list is non-exhaustive - Custom Dependencies: warn that .npmrc tokens are uploaded, drop the hard-coded token examples, split the Artifactory example so the token isn't part of the registry URL, and align "How caching works" - Yarn Berry, like bun, needs its registry URLs in .npmrc - PlaywrightCheck examples no longer include .npmrc explicitly Co-Authored-By: Claude Opus 5.5 --- constructs/playwright-check.mdx | 4 ++-- .../playwright-checks/custom-dependencies.mdx | 19 ++++++++----------- .../playwright-checks/internal-registries.mdx | 16 +++++++--------- 3 files changed, 17 insertions(+), 22 deletions(-) diff --git a/constructs/playwright-check.mdx b/constructs/playwright-check.mdx index 332ccc78..be29b8d6 100644 --- a/constructs/playwright-check.mdx +++ b/constructs/playwright-check.mdx @@ -44,7 +44,7 @@ import { Engine, PlaywrightCheck } from "checkly/constructs" new PlaywrightCheck("critical-e2e-monitor", { name: "Critical E2E Monitor", description: "Runs the **critical path** e2e suite against production.", - include: [".npmrc", "test-files/**"], + include: ["test-files/**"], playwrightConfigPath: "./playwright.config.ts", engine: Engine.node("24"), // Optional: override the auto-detected engine. installCommand: "npm ci", @@ -227,7 +227,7 @@ Defines the glob patterns for files and directories that should be included when new PlaywrightCheck("critical-e2e-monitor", { name: "Critical E2E Monitor", playwrightConfigPath: "../playwright.config.ts", - include: [".npmrc", "test-files/**"], + include: ["test-files/**"], }) ``` diff --git a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx index dc4446ef..93dca7dd 100644 --- a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx +++ b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx @@ -97,21 +97,14 @@ Store authentication tokens as Checkly [environment variables](/platform/variabl #### Using private npm packages ```txt -# 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 ```txt -# 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... +registry=https://yourcompany.jfrog.io/artifactory/api/npm/npm-local/ +//yourcompany.jfrog.io/artifactory/api/npm/npm-local/:_authToken=${ARTIFACTORY_TOKEN} ``` #### Using GitHub Packages @@ -129,6 +122,10 @@ registry=https://yourcompany.jfrog.io/artifactory/api/npm/npm-local/:_authToken= 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. @@ -172,14 +169,14 @@ Learn more about [customizing install commands](/detect/synthetic-monitoring/pla ## 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 file, the `package.json` or `.npmrc` files in your workspace, a pnpm `.pnpmfile.cjs` or `.pnpmfile.mjs` at the workspace root, your `installCommand`, your working directory, or your [`engine`](/constructs/playwright-check#param-engine) change. Changes to [embedded or pruned packages and registry routing](/detect/synthetic-monitoring/playwright-checks/internal-registries) also invalidate the cache. +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`](/constructs/playwright-check#param-engine) change. Changes to [embedded or pruned packages and registry routing](/detect/synthetic-monitoring/playwright-checks/internal-registries) also invalidate the cache. ### 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, `package.json` files, `installCommand`, working directory, or `engine` have changed +2. On subsequent runs, Checkly checks whether any of the inputs described above 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 diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 85e3279e..108f2d33 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -83,7 +83,7 @@ The CLI validates the list before deploying: - An entry that matches no package in the lockfile fails validation and blocks the deploy. Only list packages your project actually uses. - An entry whose only matches can't be embedded also fails validation. Packages installed from git, a local path, or a URL, and lockfile entries without an integrity hash, can't be embedded; the runner must fetch them itself. -- In a pnpm workspace, an entry that also matches a workspace member that another member depends on prints a warning on every run, because workspace members are bundled as source code rather than embedded. Exclude those members with `!`, for example `['@acme/*', '!@acme/design-system']`. +- Workspace members that a pattern matches are skipped, because they're bundled as source code rather than embedded. An entry that matches only workspace members fails validation. In a pnpm workspace, a member that another member depends on can also appear in a warning saying it can't be embedded; exclude it with `!` to silence the warning, for example `['@acme/*', '!@acme/design-system']`. - A `!` exclusion that matches nothing is ignored. - A list that ends up selecting no packages at all only prints a warning. @@ -95,9 +95,9 @@ Embedded packages need registry credentials only on the machine running the CLI, - `npm_config_*` environment variables - pnpm's global `auth.ini`, where `pnpm login` stores tokens on pnpm 11 and later -Scope tokens to the registry (`//registry.example.com/:_authToken=${NPM_TOKEN}`) rather than setting a bare `_authToken`. Because `.npmrc` is uploaded with the code bundle, reference tokens through environment variables instead of writing them in plain text, and set those variables wherever you run `checkly test` or `checkly deploy`. Only packages the runner fetches itself need their token stored in Checkly, as described in [Using private dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#using-private-dependencies). +Scope tokens to the registry (`//registry.example.com/:_authToken=${NPM_TOKEN}`) rather than setting a bare `_authToken`. Because `.npmrc` is uploaded with the code bundle, reference tokens through environment variables instead of writing them in plain text, and set those variables wherever you run `checkly test` or `checkly deploy`. Only packages the runner fetches itself need their token stored in Checkly, as described in [Using private dependencies](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#using-private-dependencies). If you use [`runner.registries`](#route-runner-installs-to-other-registries), set those tokens in its `auth` entries instead. -If you use bun or Yarn Berry and your credentials only live in `bunfig.toml` or `.yarnrc.yml`, copy them into `.npmrc` or set them as `npm_config_*` variables; the CLI doesn't read those files. bun projects must also keep their registry URLs in `.npmrc`. +If you use bun or Yarn Berry and your credentials only live in `bunfig.toml` or `.yarnrc.yml`, copy them into `.npmrc` or set them as `npm_config_*` variables; the CLI doesn't read those files. bun and Yarn Berry projects must also keep their registry URLs, including scoped registries, in `.npmrc`. If a download fails to authenticate, the error names the credential source the CLI used. @@ -259,10 +259,7 @@ export default defineConfig({ 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. Keep these points in mind: - -- Only remove packages your tests don't import or run. The CLI doesn't check this for you. -- A prune change that alters the bundled `package.json` files or lockfile invalidates the dependency cache once, so the next run does a full install. Patterns that match nothing leave the cache untouched. +Pruning works the same way in a single-package project as in a monorepo. Only remove packages your tests don't import or run; the CLI doesn't check this for you. ## Route runner installs to other registries @@ -295,6 +292,7 @@ export default defineConfig({ With this config, the runner installs `@acme` packages only from `https://npm.acme.example.com/`, authenticating with the `ACME_NPM_TOKEN` environment variable, and every other package from the public npm registry. If an `@acme` package is missing from the Acme registry, the install fails instead of asking the public registry for it. - `upstreams` names the registries the runner may use. A `token` must be a single `${VARIABLE}` reference to a Checkly [environment variable](/platform/variables), which the runner resolves at install time. Literal tokens are rejected. +- Once `runner.registries` is set, the runner ignores the registry credentials and TLS settings, such as `strict-ssl` and `cafile`, in your bundled `.npmrc`, `pnpm-workspace.yaml`, and `.yarnrc.yml`. Give every upstream that needs authentication its own `auth` entry. - `packages` routes package names to upstreams. The first rule whose [pattern](#package-name-patterns) matches wins. The runner tries the rule's upstreams in order, but never falls through to a later rule, so private package names aren't sent to a broader registry. The last rule must be `{ pattern: '**', ... }`. - Routing patterns don't accept `!` exclusions or version pins. - [Embedded packages](#embed-private-packages) always take priority over routing rules. @@ -381,7 +379,7 @@ When you run `npx checkly deploy`, the CLI: 1. Bundles `e2e` and `design-system`, because the tests import `design-system`. `admin` is left out. 2. Removes `@acme/analytics` from the bundled copy of `design-system`'s `package.json`. 3. Prunes the bundled lockfile to the bundle's contents. `@acme/billing-sdk` drops out because only `admin` needs it, and `@acme/analytics` drops out because nothing declares it anymore. -4. Embeds the `@acme` packages that remain in the pruned lockfile, here `@acme/tokens`, downloading them through your `.npmrc`. The `!@acme/design-system` exclusion keeps the pattern away from the workspace member, which is bundled as source code and can't be embedded. +4. Embeds the `@acme` packages that remain in the pruned lockfile, here `@acme/tokens`, downloading them through your `.npmrc`. The `!@acme/design-system` exclusion keeps the pattern away from the workspace member, which is bundled as source code, and silences the warning pnpm workspaces can print for it. On Checkly, the runner installs `@acme/tokens` from the bundle and all public packages from npm. It never contacts your internal registry. @@ -454,4 +452,4 @@ DEBUG='checkly:cli:services:embedded-packages,checkly:cli:services:check-parser: ### Dependencies are reinstalled after a change -Changing the set of embedded packages, the pruned manifests, or `runner.registries` invalidates the runner's [dependency cache](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#dependency-caching). The next run installs dependencies from scratch. +Changing the set of embedded packages, the pruned manifests or lockfile, or `runner.registries` invalidates the runner's [dependency cache](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#dependency-caching). The next run installs dependencies from scratch. A prune pattern or a `!` exclusion that matches nothing changes none of these, so it leaves the cache untouched. From 2363fca35e9e8f24c9fe90d0ba543aa8d2c40a27 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 21:41:38 +0900 Subject: [PATCH 10/17] docs: describe embedding after the workspace-link and runner fixes (RED-1310) pnpm sibling workspace members are now skipped silently, so the ! workaround goes. The runner serves embedded packages from the bundle alone, so a pinned embed entry must cover every lockfile version of the package, and embedded packages never go through routing rules. Co-Authored-By: Claude Opus 5.5 --- .../playwright-checks/internal-registries.mdx | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 108f2d33..642dc890 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -57,7 +57,7 @@ This config embeds every package in the `@acme` scope that your lockfile contain Each entry is one of: - A package name, such as `'@acme/private-utils'`. Embeds every version of the package found in the lockfile. -- An exact version pin, such as `'legacy-private-pkg@2.1.0'`. +- An exact version pin, such as `'legacy-private-pkg@2.1.0'`. Checkly lists only the embedded versions of an embedded package, so a pin must cover every version of that package in your lockfile. Otherwise the install can fail; npm, for example, fails with a warning that names the missing version. Embed the package by name to include every version in your lockfile. - A name [pattern](#package-name-patterns), such as `'@acme/*'`, optionally prefixed with `!` to exclude packages that earlier entries selected. List every package the runner can't fetch, including private packages that are only dependencies of other private packages. Embedding a package doesn't embed its dependencies; see [Dependencies of dependencies](#dependencies-of-dependencies). @@ -83,7 +83,7 @@ The CLI validates the list before deploying: - An entry that matches no package in the lockfile fails validation and blocks the deploy. Only list packages your project actually uses. - An entry whose only matches can't be embedded also fails validation. Packages installed from git, a local path, or a URL, and lockfile entries without an integrity hash, can't be embedded; the runner must fetch them itself. -- Workspace members that a pattern matches are skipped, because they're bundled as source code rather than embedded. An entry that matches only workspace members fails validation. In a pnpm workspace, a member that another member depends on can also appear in a warning saying it can't be embedded; exclude it with `!` to silence the warning, for example `['@acme/*', '!@acme/design-system']`. +- Workspace members that a pattern matches are skipped, because they're bundled as source code rather than embedded. An entry that matches only workspace members fails validation. - A `!` exclusion that matches nothing is ignored. - A list that ends up selecting no packages at all only prints a warning. @@ -295,7 +295,7 @@ With this config, the runner installs `@acme` packages only from `https://npm.ac - Once `runner.registries` is set, the runner ignores the registry credentials and TLS settings, such as `strict-ssl` and `cafile`, in your bundled `.npmrc`, `pnpm-workspace.yaml`, and `.yarnrc.yml`. Give every upstream that needs authentication its own `auth` entry. - `packages` routes package names to upstreams. The first rule whose [pattern](#package-name-patterns) matches wins. The runner tries the rule's upstreams in order, but never falls through to a later rule, so private package names aren't sent to a broader registry. The last rule must be `{ pattern: '**', ... }`. - Routing patterns don't accept `!` exclusions or version pins. -- [Embedded packages](#embed-private-packages) always take priority over routing rules. +- [Embedded packages](#embed-private-packages) never go through routing rules: the runner installs them from the code bundle and doesn't ask any routed registry about them. `runner.registries` only affects the install on Checkly. Embedding and lockfile pruning still run on your machine and use your `.npmrc` credentials. @@ -308,7 +308,7 @@ Your lockfile records every package the install needs, including dependencies of | `bundle.packages.embed` | Entries match packages at any depth in the lockfile, so you can embed a transitive dependency by name. Embedding a package doesn't embed its dependencies. | | Lockfile pruning | Removes the dependencies of workspace members outside the bundle at every depth, except packages that something in the bundle still needs. | | `bundle.packages.prune` | Patterns only match dependencies declared in `package.json` files; a pattern that names a package that is only a transitive dependency has no effect. Removing a declared dependency also removes the transitive dependencies that only it needed from the bundled lockfile. | -| `runner.registries` | Routing rules apply to every package the runner installs, at any depth. | +| `runner.registries` | Routing rules apply to every package the runner fetches from a registry, at any depth. Embedded packages never reach them. | ### Embed private dependency chains @@ -353,10 +353,7 @@ export default defineConfig({ logicalId: 'acme-website', bundle: { packages: { - embed: [ - '@acme/*', - '!@acme/design-system', // Workspace member, bundled as source - ], + embed: ['@acme/*'], prune: [ { member: ['@acme/design-system'], @@ -379,7 +376,7 @@ When you run `npx checkly deploy`, the CLI: 1. Bundles `e2e` and `design-system`, because the tests import `design-system`. `admin` is left out. 2. Removes `@acme/analytics` from the bundled copy of `design-system`'s `package.json`. 3. Prunes the bundled lockfile to the bundle's contents. `@acme/billing-sdk` drops out because only `admin` needs it, and `@acme/analytics` drops out because nothing declares it anymore. -4. Embeds the `@acme` packages that remain in the pruned lockfile, here `@acme/tokens`, downloading them through your `.npmrc`. The `!@acme/design-system` exclusion keeps the pattern away from the workspace member, which is bundled as source code, and silences the warning pnpm workspaces can print for it. +4. Embeds the `@acme` packages that remain in the pruned lockfile, here `@acme/tokens`, downloading them through your `.npmrc`. The pattern also matches the workspace members, such as `design-system`; those are bundled as source code and skipped. On Checkly, the runner installs `@acme/tokens` from the bundle and all public packages from npm. It never contacts your internal registry. From b0fba9d1de09238f43dfa23e1bf59ccfdefd9841 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 21:56:28 +0900 Subject: [PATCH 11/17] docs: mention the CLI warning for partly embedded packages (RED-1310) Co-Authored-By: Claude Opus 5.5 --- .../playwright-checks/internal-registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx index 642dc890..f45810f7 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx @@ -57,7 +57,7 @@ This config embeds every package in the `@acme` scope that your lockfile contain Each entry is one of: - A package name, such as `'@acme/private-utils'`. Embeds every version of the package found in the lockfile. -- An exact version pin, such as `'legacy-private-pkg@2.1.0'`. Checkly lists only the embedded versions of an embedded package, so a pin must cover every version of that package in your lockfile. Otherwise the install can fail; npm, for example, fails with a warning that names the missing version. Embed the package by name to include every version in your lockfile. +- An exact version pin, such as `'legacy-private-pkg@2.1.0'`. Checkly lists only the embedded versions of an embedded package, so a pin must cover every version of that package in your lockfile. Otherwise the install can fail; npm, for example, can't find the missing version. `checkly test` and `checkly deploy` warn when an entry leaves versions of a package in your lockfile unembedded. Embed the package by name to include every version in your lockfile. - A name [pattern](#package-name-patterns), such as `'@acme/*'`, optionally prefixed with `!` to exclude packages that earlier entries selected. List every package the runner can't fetch, including private packages that are only dependencies of other private packages. Embedding a package doesn't embed its dependencies; see [Dependencies of dependencies](#dependencies-of-dependencies). From 41a42becfed151d418c4f0fcfbf7522f87aafe6b Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 22:05:57 +0900 Subject: [PATCH 12/17] docs: rename the internal registries page to match its title (RED-1310) Co-Authored-By: Claude Opus 5.5 --- constructs/project.mdx | 4 ++-- .../playwright-checks/custom-dependencies.mdx | 12 ++++++------ ... => private-packages-and-internal-registries.mdx} | 2 +- docs.json | 2 +- sitemap.xml | 6 +++--- 5 files changed, 13 insertions(+), 13 deletions(-) rename detect/synthetic-monitoring/playwright-checks/{internal-registries.mdx => private-packages-and-internal-registries.mdx} (99%) diff --git a/constructs/project.mdx b/constructs/project.mdx index 0293fc6c..f877ccb6 100644 --- a/constructs/project.mdx +++ b/constructs/project.mdx @@ -74,8 +74,8 @@ export default defineConfig({ | `repoUrl` | `string` | ❌ | - | Optional URL to a Git repository | | `checks` | `object` | ❌ | - | Top-level defaults for all checks in this project | | `cli` | `object` | ❌ | - | Defaults for CLI commands | -| `bundle` | `object` | ❌ | - | Dependency embedding and pruning for Playwright Check Suite code bundles. See [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) | -| `runner` | `object` | ❌ | - | Settings applied on Checkly runners for Playwright Check Suite installs: [registry routing](/detect/synthetic-monitoring/playwright-checks/internal-registries#route-runner-installs-to-other-registries) and the [dependency cache version](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#force-a-reinstall) | +| `bundle` | `object` | ❌ | - | Dependency embedding and pruning for Playwright Check Suite code bundles. See [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries) | +| `runner` | `object` | ❌ | - | Settings applied on Checkly runners for Playwright Check Suite installs: [registry routing](/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries#route-runner-installs-to-other-registries) and the [dependency cache version](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#force-a-reinstall) | ### Core Project Options diff --git a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx index 93dca7dd..ef40d54b 100644 --- a/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx +++ b/detect/synthetic-monitoring/playwright-checks/custom-dependencies.mdx @@ -83,7 +83,7 @@ You need to: 2. Store authentication tokens as [environment variables](/platform/variables) in Checkly -If your private packages come from an internal registry that Checkly can't reach, such as a registry behind your firewall or VPN, see [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) to embed them in the code bundle instead. +If your private packages come from an internal registry that Checkly can't reach, such as a registry behind your firewall or VPN, see [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries) to embed them in the code bundle instead. ### Configure authentication to private dependencies @@ -169,7 +169,7 @@ Learn more about [customizing install commands](/detect/synthetic-monitoring/pla ## 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`](/constructs/playwright-check#param-engine) change. Changes to [embedded or pruned packages and registry routing](/detect/synthetic-monitoring/playwright-checks/internal-registries) also invalidate the cache. +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`](/constructs/playwright-check#param-engine) change. Changes to [embedded or pruned packages and registry routing](/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries) also invalidate the cache. ### How caching works @@ -182,7 +182,7 @@ When dependency caching is enabled: 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. To make those installs faster, remove dependencies your checks don't use, such as linters or Storybook, from the code bundle with [`bundle.packages.prune`](/detect/synthetic-monitoring/playwright-checks/internal-registries#speed-up-dependency-installs). +When the cache can't be used, the install takes longer the more packages your project declares. To make those installs faster, remove dependencies your checks don't use, such as linters or Storybook, from the code bundle with [`bundle.packages.prune`](/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries#speed-up-dependency-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. @@ -244,7 +244,7 @@ Browser caching requires Private Location agent v8.2.0 or later. 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 [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/internal-registries) +- If the registry is only reachable from your own network, see [Private Packages and Internal Registries](/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries) - Check that the registry URL is correct - Ensure your package name matches exactly (including scope) @@ -269,7 +269,7 @@ If Checkly uses the wrong package manager: 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`](/detect/synthetic-monitoring/playwright-checks/internal-registries#speed-up-dependency-installs) +- Remove dependencies your checks don't use from the code bundle with [`bundle.packages.prune`](/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries#speed-up-dependency-installs) - Consider using a custom `installCommand` to install only required packages ### Memory usage exceeded @@ -277,7 +277,7 @@ If package installation exceeds time limits: 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`](/detect/synthetic-monitoring/playwright-checks/internal-registries#speed-up-dependency-installs) +- Remove dependencies your checks don't use from the code bundle with [`bundle.packages.prune`](/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries#speed-up-dependency-installs) - Consider using a custom `installCommand` to install only necessary packages ### General installation failures diff --git a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx similarity index 99% rename from detect/synthetic-monitoring/playwright-checks/internal-registries.mdx rename to detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx index f45810f7..356cfd5e 100644 --- a/detect/synthetic-monitoring/playwright-checks/internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx @@ -2,7 +2,7 @@ title: 'Private Packages and Internal Registries in Playwright Check Suites' description: 'Run Playwright Check Suites that depend on private packages from internal registries Checkly cannot reach, and speed up dependency installs, by embedding and pruning dependencies in the code bundle.' sidebarTitle: 'Internal Registries' -canonical: 'https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries/' +canonical: 'https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries/' --- When you run `npx checkly test` or `npx checkly deploy`, the CLI packs your Playwright tests into a code bundle together with the files your package manager needs: `package.json` files, the lockfile, and `.npmrc`. Before each run, Checkly installs your dependencies from that bundle, fetching packages from the registries your project uses. diff --git a/docs.json b/docs.json index 30b44cac..43291c98 100644 --- a/docs.json +++ b/docs.json @@ -259,7 +259,7 @@ "detect/synthetic-monitoring/playwright-checks/performance-metrics", "detect/synthetic-monitoring/playwright-checks/add-to-group", "detect/synthetic-monitoring/playwright-checks/custom-dependencies", - "detect/synthetic-monitoring/playwright-checks/internal-registries", + "detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries", "detect/synthetic-monitoring/playwright-checks/environment-variables", "detect/synthetic-monitoring/playwright-checks/timeouts" ] diff --git a/sitemap.xml b/sitemap.xml index 3faab70a..df29b749 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -1191,15 +1191,15 @@ https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/environment-variables/ - - https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/internal-registries/ - https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/overview/ https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/performance-metrics/ + + https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries/ + https://www.checklyhq.com/docs/detect/synthetic-monitoring/playwright-checks/quickstart/ From 5405fc925151ae561b4d1d7086a74736edc95085 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 22:13:00 +0900 Subject: [PATCH 13/17] docs: warn against pruning packages the install needs (RED-1310) Co-Authored-By: Claude Opus 5.5 --- .../private-packages-and-internal-registries.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx index 356cfd5e..710dcd9e 100644 --- a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx @@ -220,7 +220,7 @@ Prefer exact member names with `keep`, since a wildcard can match a member you a #### Requirements and caveats - When the bundle contains a lockfile, `prune` only takes effect if lockfile pruning succeeds in the same run, so the manifests and lockfile stay in sync. Otherwise the original `package.json` files ship unchanged and the CLI prints a warning. A bundle without a lockfile always ships the pruned manifests. -- The CLI doesn't check your code against the pruned dependencies. Don't remove anything your tests need at runtime. +- The CLI doesn't check your code against the pruned dependencies. Don't remove anything your tests need at runtime, or anything the install itself needs. For example, keep `typescript` when a package's `prepare` or `postinstall` script compiles TypeScript during the install (see [lifecycle scripts](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#using-lifecycle-scripts)). ### Speed up dependency installs @@ -259,7 +259,7 @@ export default defineConfig({ 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 your tests don't import or run; the CLI doesn't check this for you. +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. ## Route runner installs to other registries From 66f2285748121a9f2aaab07468039f1009a2881d Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Thu, 29 Oct 2026 22:17:45 +0900 Subject: [PATCH 14/17] docs: document the code bundle size limit for embedded packages (RED-1310) Co-Authored-By: Claude Opus 5.5 --- .../private-packages-and-internal-registries.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx index 710dcd9e..13a0fe2a 100644 --- a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx @@ -101,6 +101,16 @@ If you use bun or Yarn Berry and your credentials only live in `bunfig.toml` or If a download fails to authenticate, the error names the credential source the CLI used. +### Code bundle size + +The Checkly API accepts code bundles of up to 30 MB, compressed. Embedded packages ship inside the code bundle, so embedding large packages, or many packages that add up, can push the bundle over that limit. `checkly test`, `checkly pw-test`, and `checkly deploy` then fail when they upload the bundle: + +```text Terminal +The code bundle is too large to upload: the compressed bundle is 34.2 MB, but the Checkly API accepts at most 30 MB. Reduce the bundle size by removing large files from the Playwright project, narrowing any 'include' patterns, or embedding fewer private packages ('bundle.packages.embed'). +``` + +To stay under the limit, embed only the packages the runner can't fetch from a registry it can reach, and let [lockfile pruning](#lockfile-pruning) and [`bundle.packages.prune`](#prune-manifest-dependencies) drop the packages your checks don't use. Packages that pruning removes from the bundled lockfile aren't embedded. + ## Pruning Pruning reduces what the runner installs to what your code bundle needs. This keeps internal packages your checks never use out of the install, so you don't have to embed them or make their registry reachable, and it makes the install faster. The CLI never modifies the files on disk; it only rewrites the copies in the code bundle. @@ -447,6 +457,10 @@ Run the CLI with debug logging to see which packages each `embed` entry matched, DEBUG='checkly:cli:services:embedded-packages,checkly:cli:services:check-parser:*' npx checkly test ``` +### The code bundle is too large to upload + +The compressed bundle exceeds the 30 MB the Checkly API accepts. Embedded packages count toward it; see [Code bundle size](#code-bundle-size). + ### Dependencies are reinstalled after a change Changing the set of embedded packages, the pruned manifests or lockfile, or `runner.registries` invalidates the runner's [dependency cache](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#dependency-caching). The next run installs dependencies from scratch. A prune pattern or a `!` exclusion that matches nothing changes none of these, so it leaves the cache untouched. From d955ad2528ece7595d5f6f98e7976ecb2a7b9f75 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Fri, 30 Oct 2026 02:15:13 +0900 Subject: [PATCH 15/17] docs: note that the code bundle limit can be raised on request (RED-1310) Co-Authored-By: Claude Opus 5.5 --- .../private-packages-and-internal-registries.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx index 13a0fe2a..1d60ab80 100644 --- a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx @@ -111,6 +111,8 @@ The code bundle is too large to upload: the compressed bundle is 34.2 MB, but th To stay under the limit, embed only the packages the runner can't fetch from a registry it can reach, and let [lockfile pruning](#lockfile-pruning) and [`bundle.packages.prune`](#prune-manifest-dependencies) drop the packages your checks don't use. Packages that pruning removes from the bundled lockfile aren't embedded. +If your bundle still needs more room, contact [support@checklyhq.com](mailto:support@checklyhq.com) to raise your account's limit to 100 MB. + ## Pruning Pruning reduces what the runner installs to what your code bundle needs. This keeps internal packages your checks never use out of the install, so you don't have to embed them or make their registry reachable, and it makes the install faster. The CLI never modifies the files on disk; it only rewrites the copies in the code bundle. @@ -459,7 +461,7 @@ DEBUG='checkly:cli:services:embedded-packages,checkly:cli:services:check-parser: ### The code bundle is too large to upload -The compressed bundle exceeds the 30 MB the Checkly API accepts. Embedded packages count toward it; see [Code bundle size](#code-bundle-size). +The compressed bundle exceeds the limit the Checkly API accepts for your account: 30 MB, unless support has raised it. Embedded packages count toward it; see [Code bundle size](#code-bundle-size). ### Dependencies are reinstalled after a change From 33334553f945973e8afbfc14173b201d7ee97c96 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Fri, 30 Oct 2026 02:28:11 +0900 Subject: [PATCH 16/17] docs: offer the larger code bundle limit on Enterprise plans (RED-1310) Co-Authored-By: Claude Opus 5.5 --- .../private-packages-and-internal-registries.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx index 1d60ab80..d6d2be42 100644 --- a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx @@ -111,7 +111,7 @@ The code bundle is too large to upload: the compressed bundle is 34.2 MB, but th To stay under the limit, embed only the packages the runner can't fetch from a registry it can reach, and let [lockfile pruning](#lockfile-pruning) and [`bundle.packages.prune`](#prune-manifest-dependencies) drop the packages your checks don't use. Packages that pruning removes from the bundled lockfile aren't embedded. -If your bundle still needs more room, contact [support@checklyhq.com](mailto:support@checklyhq.com) to raise your account's limit to 100 MB. +Enterprise plans can raise the limit to 100 MB. Contact your account executive or [contact us in the Checkly Web App](https://app.checklyhq.com/?support=true). ## Pruning @@ -461,7 +461,7 @@ DEBUG='checkly:cli:services:embedded-packages,checkly:cli:services:check-parser: ### The code bundle is too large to upload -The compressed bundle exceeds the limit the Checkly API accepts for your account: 30 MB, unless support has raised it. Embedded packages count toward it; see [Code bundle size](#code-bundle-size). +The compressed bundle exceeds the limit the Checkly API accepts for your account: 30 MB, unless it has been raised for your account. Enterprise plans can raise it to 100 MB. Embedded packages count toward it; see [Code bundle size](#code-bundle-size). ### Dependencies are reinstalled after a change From 5f165383705b2a1b453578f04e7e86cda41ab7b4 Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Fri, 30 Oct 2026 02:28:23 +0900 Subject: [PATCH 17/17] docs: drop a repeated phrase in the bundle size troubleshooting entry (RED-1310) Co-Authored-By: Claude Opus 5.5 --- .../private-packages-and-internal-registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx index d6d2be42..f227e217 100644 --- a/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx +++ b/detect/synthetic-monitoring/playwright-checks/private-packages-and-internal-registries.mdx @@ -461,7 +461,7 @@ DEBUG='checkly:cli:services:embedded-packages,checkly:cli:services:check-parser: ### The code bundle is too large to upload -The compressed bundle exceeds the limit the Checkly API accepts for your account: 30 MB, unless it has been raised for your account. Enterprise plans can raise it to 100 MB. Embedded packages count toward it; see [Code bundle size](#code-bundle-size). +The compressed bundle exceeds the limit the Checkly API accepts for your account: 30 MB, unless it has been raised. Enterprise plans can raise it to 100 MB. Embedded packages count toward it; see [Code bundle size](#code-bundle-size). ### Dependencies are reinstalled after a change