Authenticate your CI job to the registry that hosts the private package, install your project dependencies, and then run Chromatic. These are two separate credentials: the package manager needs registry access to install the dependency, while Chromatic needs its own project token to publish the build.
How the two credentials fit together
Chromatic does not replace the credentials your package manager needs to fetch a private dependency. The registry token authorizes package installation; the Chromatic project token authorizes a Chromatic build. Keep them as separate CI secrets and expose each only to the step that needs it. Chromatic documents the project token as CHROMATIC_PROJECT_TOKEN, which its CLI recognizes automatically (Chromatic CLI documentation).
As an Amazon Associate I earn from qualifying purchases.
The order matters: install dependencies before running Chromatic so the Storybook project can resolve the private package during its build. Chromatic’s documented CI flow installs project dependencies before the Chromatic build (Chromatic CI documentation).
Configure private-package access for your registry
npmjs.org
For a private package hosted on npmjs.org, add this project-level .npmrc entry:
#1 Best Overall
//registry.npmjs.org/:_authToken=${NPM_TOKEN}Commit the file with the literal ${NPM_TOKEN} reference, not a live credential. Store the actual token as a protected CI secret named NPM_TOKEN, so npm can substitute it at runtime. npm recommends a project-specific .npmrc with a token variable for CI authentication (npm: Using private packages in a CI/CD workflow).
For a job that only installs packages and runs tests, use a granular read-only token where supported. Its owner or organization must also be authorized to read the package.
GitHub Packages
GitHub Packages uses a different setup: map the package’s scope to https://npm.pkg.github.com and use a credential eligible for that package. GitHub documents GITHUB_TOKEN for packages associated with the workflow repository when access is granted. For certain packages in other private repositories, it documents a personal access token (classic) with read:packages. Package-level Actions access and repository permissions can affect access, so use the instructions that match the package and organization (GitHub: Working with the npm registry).
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteOther registries
Do not assume the npmjs.org .npmrc line works for every registry. Check the registry endpoint, any package-scope mapping, the credential type it accepts, and whether the CI identity is granted read access.
Run the install before Chromatic
Adapt the sequence below to your CI provider and package manager. The YAML is illustrative rather than a drop-in workflow: secret syntax, Node setup, and install commands vary by provider and project.
# Illustrative CI sequence; adapt to your provider and package manager.
- checkout repository
- configure Node and the selected package manager
- install dependencies using 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>For npm projects, use the CI install command appropriate to the lockfile—for example, npm ci when the project uses package-lock.json. The key is that registry credentials are present during installation, and the Chromatic token is present when the Chromatic command runs. Avoid printing secrets in logs or placing their literal values in the repository.
Configure and run Chromatic
Chromatic’s quickstart uses the chromatic package, a project token, and a command that builds the Storybook. Its default Storybook build script is build-storybook; projects with a different build setup can configure build-script-name or build-command (Chromatic configuration reference).
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11One typical npm-based arrangement is to install the CLI as a project development dependency, then run it after the private package and the rest of the project dependencies have been installed:
npm install --save-dev chromatic
npx chromatic --project-token="$CHROMATIC_PROJECT_TOKEN"In CI, set CHROMATIC_PROJECT_TOKEN from your secret store rather than typing a real token into the command or committing it. You can also use the supported CI action instead of invoking the CLI directly; either way, configure the token securely and point Chromatic at the intended Storybook build.
Monorepos
Run the install and Chromatic command in the correct workspace or subproject context so its dependencies and Storybook configuration are available. Chromatic’s custom CI guidance says each subproject needs its own project token (Chromatic: Automate Chromatic with your custom CI provider).
Troubleshoot installation and build failures
- Install reports authorization failure or package not found: confirm the secret exists in the install step, the CI identity is permitted to read the package, and the configured registry and scope match the package host. Private package visibility and access rules are controlled by the registry owner or organization.
- GitHub Packages install fails: check that the scope routes to
https://npm.pkg.github.com, the credential is eligible for that package, and repository or package-level workflow access is granted. - Install succeeds but Storybook cannot resolve the package: check workspace configuration, whether the package is declared as a dependency available to the Storybook project, and whether CI ran from the intended directory. There is no universal Chromatic-specific workaround for project dependency or workspace misconfiguration.
- Chromatic rejects the build token: verify that the Chromatic project token—not the registry token—is supplied as
CHROMATIC_PROJECT_TOKENfor the Chromatic step, and that it belongs to the intended Chromatic project. - Chromatic builds the wrong Storybook or cannot find the build command: run from the intended subproject and configure the correct build script or command with Chromatic’s supported settings.
Or skip the browser setup
If your workflow also needs website screenshots, ScreenshotNeo is a separate screenshot API and MCP server—not a replacement for registry authentication or Chromatic. A single GET request captures a URL as an image or PDF:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation. It accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides screenshot and PDF tools for AI agents. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Best Value
Frequently Asked Questions
Does Chromatic need the private registry token?
No. The package manager needs registry credentials to install the dependency; Chromatic needs its separate project token to run a build.
Can I use one token for npm and Chromatic?
No. They authorize different services and should be stored and supplied separately.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
