iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Choose the layout that matches how your teams work: combine package stories into one Storybook and publish one Chromatic project for a shared catalog, or keep Storybooks separate and give each subproject its own Chromatic project, token, and CI run. In GitHub Actions, set each run’s workingDir to the package it should build. Check path bases carefully before enabling TurboSnap.
Should you use one Chromatic project or several?
Decide whether your organization wants one shared catalog and status or independent Storybooks and pull request checks. Chromatic documents both layouts in its monorepo guide.
| Decision point | Combined Storybook and project | Separate Storybooks and projects |
|---|---|---|
| Catalog | One shared Storybook catalog. | Separate catalogs and configurations. |
| Chromatic identity | One Chromatic project. | One project per subproject. |
| Tokens and CI | One token and run for the central Storybook. | Each subproject needs its own project token and invocation. |
| Pull request status | One principal project status. | Separate build statuses can be used for subprojects. |
| Best fit | Teams maintaining stories centrally and wanting one catalog. | Teams needing independent checks or project configuration. |
Combine stories when the catalog is shared
Add each package’s story-file glob to the principal Storybook’s stories setting, then publish that Storybook through a single Chromatic project. This gives contributors one catalog and one publishing target. For targeted snapshot testing, Chromatic documents TurboSnap and the onlyStoryFiles and onlyStoryNames controls. Avoid publishing a Storybook that omits stories as though it were complete: Chromatic can mark missing stories as removed.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Keep Storybooks separate when checks or ownership differ
Create or link a Chromatic project for each subproject, store a distinct project token for each, and run Chromatic in that package’s context. This adds CI invocations and project setup, but provides separate identities and build statuses. If a linked or renamed project no longer appears in pull request checks, Chromatic notes that existing required checks may need to be removed and re-added in the Git provider because the check name changed.
#1 Best Overall
How to run Chromatic for multiple Storybooks in GitHub Actions
Use one action step per Storybook, with a matching token and working directory. Start from Chromatic’s current GitHub Actions guide for the exact action syntax and current action version; versions can change. The following illustrates the configuration pattern, not a pinned current workflow:
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: 20
- 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/adminReplace the illustrative package paths, secrets, package-manager command, and action/runtime versions with values for your repository and the current official guide. The checkout uses full Git history, as in Chromatic’s documented workflow example.
- Check out the history. Chromatic’s example checks out full Git history, which supports its build comparison workflow.
- Install dependencies. Use the CI install command for your package manager and repository layout.
- Run one action per package. Match each
workingDirto the Storybook package and eachprojectTokento that Chromatic project’s secret. - Confirm a build script exists. The package should expose
build-storybook, or setbuildScriptNameto the script it actually uses. - Use prebuilt output if appropriate. If another CI step builds Storybook, pass its output path using
storybookBuildDir.
Chromatic’s guide shows sequential action steps in one workflow and recommends separate workflow files when subprojects should run in parallel. Its documentation also states a 5,000-file upload limit, including stories and assets; for a project above that documented threshold, it recommends zip: true.
How Chromatic path settings work in a monorepo
Path options do not all resolve from the same directory. This distinction is a frequent source of errors when the action runs inside a package. Chromatic’s configuration reference defines these bases:
| Options | Path base |
|---|---|
storybookBaseDir, externals, untraced |
Repository root. |
storybookConfigDir, storybookBuildDir |
Current working directory. |
workingDir changes the current working directory used by the second group; it does not change the repository-root base for the first group. For example, with workingDir: client, storybookBuildDir: storybook-static refers to client/storybook-static. An externals pattern for a file in that package still needs a repository-root-relative path such as ./client/....
If you invoke the CLI from the repository root for a Storybook under packages/webapp, Chromatic’s TurboSnap setup guide recommends configuring storybookBaseDir and storybookConfigDir for the package and its .storybook directory. Do not mechanically add the package prefix to every option; use the documented base for each one.
Rank #4
When and how to enable TurboSnap
TurboSnap uses changed files and dependency tracing to reduce which stories receive snapshots. It does not skip building and publishing Storybook. Establish reliable default builds first: Chromatic’s current setup guide lists ten successful CI builds among the requirements before TurboSnap is unlocked, alongside version and setup prerequisites.
The same guide currently lists 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, and UI Tests enabled. These are changeable eligibility requirements, so verify them in the live setup guide before relying on them.
Best Value
Check what TurboSnap can trace
- Set
storybookBaseDirto the Storybook’s package location when needed, and make sure its config directory points to the correct.storybookfolder. - Represent cross-package dependencies accurately. Chromatic discusses dependency graph configuration and, for Nx, the use of
implicitDependenciesfor relationships that affect tracing; see its monorepo optimization guidance. - Review
staticDirsand files outside the standard dependency graph. Relevant external files may need to be declared withexternals. - For a combined Storybook, use TurboSnap or the documented
onlyStoryFilesandonlyStoryNamesfilters when you need to narrow snapshot testing. Do not publish an incomplete catalog as the full build.
Fix common monorepo and multiple-Storybook failures
- The wrong package builds: Check that the action step’s
workingDirand project token both match the intended subproject. - Chromatic cannot find the build script: Add
build-storybookto that package, setbuildScriptNameto the existing script, or provide prebuilt output withstorybookBuildDir. - The config path includes the package name twice: When
workingDiris set,storybookConfigDiris relative to that directory. Remove a duplicated package prefix. - TurboSnap traces unexpected packages or rebuilds broadly: Verify
storybookBaseDir, cross-package dependency relationships, and repository-root-relativeexternalsanduntracedpatterns. Package manifests and dependencies can affect tracing. - A project is missing from pull request checks after linking or renaming: Check whether the provider still has an old required check configured; Chromatic says the check may need to be removed and added again under its new name.
- A partial build marks stories removed: Do not publish a Storybook missing stories as the complete catalog. Use snapshot filters for targeted testing instead.
- The upload exceeds Chromatic’s documented file threshold: The GitHub Actions guide says the limit is 5,000 files including stories and assets; enable
zip: trueas Chromatic recommends for projects exceeding it.
Or skip the browser setup
Chromatic handles visual Storybook testing; for a separate task—capturing website screenshots from a URL—ScreenshotNeo offers a one-request API. It accepts consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks and failed captures are not billed, and response headers identify the page verdict and billing status. It also has an MCP server for AI agents.
For example, save a website screenshot as WebP with cURL (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.webpOne thousand screenshots a month are free with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
Can several packages’ stories appear in one Chromatic project?
Yes. Add their story globs to one Storybook’s `stories` setting and publish that Storybook through one project.
Does TurboSnap avoid building Storybook?
No. It narrows snapshot testing through changed-file and dependency tracing, but Storybook is still built and published.
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.
