How to Use Chromatic with a Private npm Package

Direct answer: give your CI job registry credentials so it can install the private npm package, then run Chromatic with its separate project token. Install the dependencies before Chromatic starts the Storybook build. The Chromatic token does not grant access to your npm registry.

1. Keep the two credentials separate

The workflow uses two different kinds of access:

Credential	What it authorizes	When it is needed
Registry token or credential	Downloading the private package from its registry	During dependency installation and any build step that fetches packages
Chromatic project token	Uploading the Storybook build to the correct Chromatic project	When the Chromatic CLI or supported CI action runs

Keep both values in your CI provider’s protected secret storage. Limit each secret to the steps that need it. Chromatic’s CLI recognizes CHROMATIC_PROJECT_TOKEN; npm’s documented CI pattern uses a literal environment-variable reference in .npmrc. Chromatic CLI documentation · npm CI documentation

2. Configure npmjs.org authentication

If the package is hosted on npmjs.org, add this project-level .npmrc file at the repository root:

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

Commit this file with the literal ${NPM_TOKEN} placeholder. Do not put the actual token in the file or commit a live credential. Add the actual NPM_TOKEN value to your CI secret store, with read access to the package. For an install-and-test job, use an appropriately scoped read-only token when your npm account and workflow support it. Check that the token’s owner is actually authorized to read the package.

At runtime, npm substitutes the environment variable while authenticating to the configured registry. Make the secret available to the dependency installation step. If a later build step installs packages too, it needs registry access as well.

3. Install dependencies before running Chromatic

Use your project’s lockfile-preserving CI install command and run it in the directory containing the relevant package manager configuration. For npm, a typical sequence is:

npm ci
npm run build-storybook
npx chromatic

In a CI workflow, set NPM_TOKEN for the install step and CHROMATIC_PROJECT_TOKEN for the Chromatic step. The following is a provider-neutral sketch, not literal YAML for a particular CI system:

steps:
  - checkout repository
  - configure Node and the project's package manager
  - install dependencies with the lockfile-preserving CI command
      environment:
        NPM_TOKEN: protected CI secret for registry read access
  - run Chromatic
      environment:
        CHROMATIC_PROJECT_TOKEN: protected Chromatic project secret

Adapt the syntax to your CI provider. Chromatic documents saving the project token as a secret environment variable named CHROMATIC_PROJECT_TOKEN. Its documented flow installs dependencies before the Storybook build and Chromatic upload. Chromatic CI documentation

Chromatic CLI and build command

Install chromatic as a project dependency or invoke it using your project’s chosen package execution method. Then run the CLI with the project token available in the environment:

CHROMATIC_PROJECT_TOKEN="$CHROMATIC_PROJECT_TOKEN" npx chromatic

Chromatic’s default Storybook build script is build-storybook. If your project uses another script or a custom build command, configure the documented build-script-name or build-command option so Chromatic builds the intended Storybook. Keep the registry credential available to the step if that command installs or resolves private dependencies. Chromatic configuration reference

4. If your package is on GitHub Packages

Do not use the npmjs.org .npmrc registry line unchanged for a package hosted elsewhere. GitHub Packages requires a mapping for the package’s scope to the GitHub npm registry, plus a credential accepted for that package. A representative scope mapping is:

@YOUR_SCOPE:registry=https://npm.pkg.github.com

Follow GitHub’s current instructions for the package and organization. GitHub documents GITHUB_TOKEN for packages associated with the workflow repository when access is granted. Some packages in other private repositories require a personal access token (classic) with read:packages. Package-level Actions access and repository permissions can also determine whether the workflow identity can read the package. GitHub npm registry documentation

5. Monorepos and multiple Storybooks

Run installation and Chromatic from the correct workspace or subproject context. Confirm that the Storybook project declares the private package as a dependency and that the workspace or package manager configuration makes it resolvable there. In a monorepo with separate Storybook projects, Chromatic’s custom CI guidance says each subproject needs its own project token. Use the build command appropriate to that subproject. Chromatic custom CI guidance

6. Security and reliability checklist

Store the registry credential and Chromatic project token in CI secret storage, not in source control.
Use a registry credential with only the read access required by the job, where supported.
Confirm the CI identity is authorized for the package, including organization or package-level access rules.
Provide the registry credential during dependency installation; a Chromatic token cannot substitute for it.
Install with the project’s lockfile-preserving CI command so the CI dependency tree follows the checked-in lockfile.
Run the build and Chromatic command from the directory and workspace that own the intended Storybook.
Use the correct registry endpoint and scope mapping for the actual package host.
Keep the Chromatic project token scoped to the Chromatic upload step when your CI provider permits step-level environment configuration.

7. Troubleshooting

Symptom	Likely cause	What to check or fix
Install returns an authorization error	The token is absent, invalid, lacks read permission, or belongs to an identity without package access.	Check that `NPM_TOKEN` is present in the install step, is current, and can read this exact package. For GitHub Packages, verify the workflow and package permissions and use the credential type GitHub allows for that package.
Install says the package cannot be found	The registry or scope mapping may point to the wrong host, or the package is private and inaccessible to the CI identity.	Verify the package’s registry host and scope configuration. Confirm access with the owner or organization; private-package access rules depend on those permissions.
Local install works but CI install fails	Your local login is available on your machine but not in the CI environment, or the secret is not exposed to the job or step.	Use the checked-in variable-based `.npmrc` pattern for npmjs.org, set the matching secret in CI, and ensure it is available during installation.
Dependencies install, but Storybook cannot resolve the package	The Storybook build may run from the wrong directory, the package may not be declared for that workspace, or package-manager workspace configuration may not expose it.	Inspect the subproject’s dependencies, workspace configuration, and command working directory. Verify that the package resolves in the same context used by the Storybook build.
Chromatic reports a missing or invalid project token	The Chromatic secret is unset, named incorrectly, or belongs to another project.	Provide the intended project token as `CHROMATIC_PROJECT_TOKEN` to the Chromatic step and verify it in the Chromatic project settings.
Chromatic builds the wrong Storybook or fails to find the build script	The project uses a non-default script or the command runs from the wrong monorepo subproject.	Run Chromatic from the intended project directory and configure its documented `build-script-name` or `build-command` as needed.

8. Performance, reliability, and cost notes

The private package adds work to dependency installation and the Storybook build. Keep installation deterministic with the project lockfile and avoid adding a second install during the build unless the project requires it. The credentials must remain valid and available whenever CI needs to fetch the dependency; a token with inadequate scope or package access makes the build fail before Chromatic can upload it.

Chromatic’s project token and registry credentials solve separate access problems, so a successful package install does not validate the Chromatic token, and a successful Chromatic upload does not prove that every clean CI run can reach the private registry. Validate both parts in the workflow. No universal runtime, reliability rate, or cost figure follows from this setup; those depend on the CI provider, registry, project build, and applicable Chromatic plan.

9. Or skip the browser setup

This guide is about Chromatic and private npm dependencies. If your task also needs website screenshots, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent banners are accepted like a visitor and removed, along with newsletter popups and chat widgets; each cleanup step can be turned off.
Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses identify the page verdict and billing status in headers.
An MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

10. FAQ

Does Chromatic need the private package’s registry token?

The package manager needs it to install the package. Chromatic needs its own project token to authorize the Chromatic build. Supply each credential to the relevant CI step.

Can I use one token for both npm and Chromatic?

They authorize different services. Configure a registry credential for package access and a Chromatic project token for Chromatic.

Is the npmjs.org `.npmrc` line universal?

No. It configures authentication to npmjs.org. Other registries, including GitHub Packages, need their own registry and scope settings.

Does this require a particular CI provider?

No. The essential sequence is registry authentication, dependency installation, then Chromatic with its project token. Secret and YAML syntax varies by provider.