Choose one Chromatic project if your packages belong in a shared Storybook catalog; use a separate Chromatic project and token for each Storybook when teams need independent identities or pull-request checks. In GitHub Actions, run each project from its package directory, confirm its build script and token, and get ordinary builds working before adding TurboSnap.
Choose a combined or separate Chromatic setup
Chromatic supports both approaches. The right choice depends on whether your teams want a single catalog and status or independently configured Storybooks and checks. The distinction is about ownership and workflow, not a documented performance advantage.
As an Amazon Associate I earn from qualifying purchases.
| Decision | One combined Storybook and Chromatic project | Separate Storybooks and Chromatic projects |
|---|---|---|
| Catalog | One shared catalog containing stories from multiple packages | Each subproject has its own Storybook |
| Project identity | One Chromatic project | One Chromatic project for each subproject |
| Token and CI run | One token and run for the central Storybook | Each subproject has its own project token and CI invocation |
| Pull-request status | One principal project status | Separate build statuses can be used for each subproject |
| Best fit | Teams maintaining a centrally shared component catalog | Teams needing independent checks, configuration, or project ownership |
Combine packages when one catalog is the goal
Add each package’s story-file glob to the main Storybook’s stories configuration, then publish that Storybook through one Chromatic project. This gives teams one publishing target and a unified set of stories. For targeted snapshot testing, use Chromatic’s onlyStoryFiles or onlyStoryNames controls, or TurboSnap after setup is reliable. Avoid publishing a Storybook that omits stories as though it were complete: Chromatic treats missing stories as removed.
Recommended Free Tools
Separate projects when checks or ownership must be independent
Create or link one Chromatic project for each subproject, keep each project token distinct, and invoke Chromatic for that subproject. This requires more project setup and CI invocations, but makes independent project identities and build statuses possible. Chromatic’s monorepo guide describes both layouts: Chromatic monorepo documentation.
#1 Best Overall
Run Chromatic for multiple Storybooks in GitHub Actions
For separate Storybooks, make one Chromatic action invocation per subproject and set workingDir to that package. The token in each step must belong to the Chromatic project for the same package. The following illustrates the structure; substitute your package directories, repository secrets, and currently supported action version. Consult Chromatic’s live GitHub Actions guide for copyable syntax and current action-version guidance.
name: Chromatic
on: [push, pull_request]
jobs:
chromatic:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- name: Publish web Storybook
uses: chromaui/action@latest
with:
projectToken: ${{ secrets.CHROMATIC_WEB_TOKEN }}
workingDir: packages/web
- name: Publish admin Storybook
uses: chromaui/action@latest
with:
projectToken: ${{ secrets.CHROMATIC_ADMIN_TOKEN }}
workingDir: packages/adminThe action and Node versions above are illustrative, not timeless recommendations. Check the current GitHub Actions documentation for supported versions. The example checks out full Git history, as Chromatic’s workflow guidance shows, and installs dependencies from the repository root. Adapt dependency installation if your package manager or workspace setup requires a different CI command.
Make sure each package can build its Storybook
By default, Chromatic looks for the Storybook build script in the working directory. Each package should have a suitable build-storybook script in its package.json. If the script has another name, set buildScriptName to that name. If a separate CI step already built Storybook, pass its output directory with storybookBuildDir, interpreted relative to the working directory.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesWhen you want subprojects to publish in parallel, Chromatic’s GitHub Actions guidance recommends separate workflow files. The sequential action steps shown above are an option when sequential runs are acceptable.
Account for the documented upload limit
Chromatic currently documents a 5,000-file upload limit, including stories and assets. For projects exceeding that limit, its guidance recommends zip: true. This is a Chromatic upload threshold, not a general filesystem limit; check the current action documentation for the option’s syntax and behavior.
Understand path bases before configuring monorepo options
Path settings do not all resolve from the same directory. In particular, setting workingDir changes the base for some settings but not others.
| Option | Path base |
|---|---|
untraced, externals, storybookBaseDir |
Repository root |
storybookConfigDir, storybookBuildDir |
Current working directory |
For example, with workingDir: client, a storybookBuildDir value of storybook-static refers to the directory inside client. But a repository-root-relative externals pattern for a file in that package needs the package prefix, such as ./client/.... See Chromatic’s configuration reference before changing these paths.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRunning from the repository root
If you invoke the CLI at the repository root for a Storybook in packages/webapp, Chromatic’s TurboSnap setup guide recommends configuring storybookBaseDir to identify the package and storybookConfigDir to identify its .storybook directory. Do not add the package prefix mechanically to every path: storybookConfigDir is relative to the current working directory, while storybookBaseDir is relative to the repository root.
Add TurboSnap only after normal builds are reliable
TurboSnap uses changed files and dependency tracing to limit which stories are snapshotted. It still builds and publishes Storybook; it is not a way to skip those steps. Chromatic recommends establishing reliable default behavior first because incorrect tracing can miss UI changes. Its current setup guide lists these prerequisites, which can change and should be verified there before enabling the feature:
- Chromatic CLI 10.0 or later.
- Storybook 6.5 or later, or Vitest 4 or later.
- Git 2.28.0 or later.
- A supported Webpack- or Vite-based setup.
- Ten successful CI builds and UI Tests enabled.
For a combined Storybook, TurboSnap can select affected stories automatically. If you use staticDirs or other files outside the usual dependency graph, check whether they need to be declared as externals. For more targeted snapshot selection, Chromatic also documents onlyStoryFiles and onlyStoryNames.
Make cross-package dependencies visible
Monorepo dependency relationships affect change detection: a change in one package may affect stories in another. Review how your workspace represents those relationships and ensure the dependency graph used for tracing reflects them. Chromatic discusses dependency graphs and specifically documents Nx implicitDependencies for expressing relationships relevant to TurboSnap: TurboSnap and monorepos.
Free tools Windows power users keep installed
One-click scans. No signup required.
Troubleshoot common monorepo failures
- The wrong Storybook builds: Check that each action step’s
workingDirpoints to the intended package and its token belongs to that package’s Chromatic project. - Chromatic cannot find the build script: Add
build-storybookto that package’s scripts, setbuildScriptNameto its actual script name, or provide prebuilt output throughstorybookBuildDir. - The configuration path repeats the package name: If
workingDiris set, remove the duplicated prefix fromstorybookConfigDir; it resolves from the working directory. - TurboSnap includes unexpected packages or rebuilds broadly: Check
storybookBaseDir, the dependency graph, and repository-root-relativeexternalsanduntracedpatterns. Package manifests and cross-package imports can affect tracing. - A linked or renamed project no longer appears as an expected pull-request check: Chromatic notes that existing required checks in the Git provider may need to be removed and re-added if the check name changes.
- Publishing a partial build marks stories removed: Do not publish an incomplete Storybook as the complete catalog. Use snapshot filters for targeted testing instead.
Or skip the browser setup
If the task is capturing a page rather than publishing component stories and reviewing visual changes, ScreenshotNeo is a separate website screenshot API and MCP server for developers. A single request can return a screenshot or PDF. For example, save a WebP screenshot with cURL (replace the target URL as needed):
Best Value
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 for request options. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Learn about ScreenshotNeo.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Sources and version-sensitive details
Chromatic’s configuration, GitHub Actions, monorepo, TurboSnap setup, path-reference, and monorepo optimization documentation were reviewed on October 3, 2026. Action/runtime versions, upload limits, and TurboSnap eligibility requirements can change; use the linked official documentation when updating a workflow.
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.
