Chromatic for Storybook

Storybook is an open source tool built for developing UI components in isolation and creating living, interactive component documentation. Storybook makes it trivial to reproduce hard to reach component states and ensuring those states are documented in code. When you adopt Storybook you also unlock automation for UI components and libraries via Chromatic.

New to Storybook? Check out our hands-on tutorials at storybook.js.org/tutorials.

Stories capture all states and variations of a component. They’re a pragmatic, reproducible way to keep track of UI test cases. Using play functions, stories allow you to simulate user interactions to run functional tests on components. Chromatic uses these stories to power visual tests.

“Unlinked” projects are the way to go if you use an OAuth provider or Git host that Chromatic doesn’t support yet, or if you need an enterprise plan but wish to trial Chromatic with your project first.

To setup Chromatic with an “unlinked” project:

1. Make sure your code is in a local or self-hosted repository (Chromatic uses Git history to track baselines).
2. Sign in using your personal account via any of the supported providers. We’ll use this to authenticate you as a user only so the account doesn’t have to be associated with your work.
3. Select “Create a project” and type your project name to create an unlinked project.

Nice! You created an unlinked project. This will allow you to get started with UI Testing workflow regardless of the underlying git provider. You can then configure your CI system to automatically run a Chromatic build on push.

The Chromatic CLI provides the option to generate a JUnit XML report of your build, which you can use to handle commit / pull request statuses yourself. See debug options for details.

Unlinked projects have certain drawbacks:

• You won’t get automatic PR checks, so pull requests will not be marked with our status messages. You’ll need to set this up manually via your CI provider.
• Authentication and access control must be handled manually through user invites.

The chromatic command will also give you the option of adding an npm script to your package.json so you can run future builds with npm run chromatic/yarn chromatic. If you want to add it manually, it should look something like:

{
  "scripts": {
    "chromatic": "chromatic"
  }
}

The above script command will pick up your project token by reading the CHROMATIC_PROJECT_TOKEN environment variable. After adding the above, ensure you set CHROMATIC_PROJECT_TOKEN when you run builds - such as in your CI config.

If you allowed chromatic to add the above line, it will also have written the environment variable to your package.json. This environment variable can also be set via your CI config for extra privacy.

Running the Chromatic command may generate certain files for logging and debugging purposes. Exactly which files it generates depends on your configuration, but these entries should likely be added to your .gitignore file:

build-storybook.log
chromatic.log
chromatic-build-*.xml
chromatic-diagnostics.json

This error often appears when git is not available in your CI environment. Chromatic uses git to associate commits to pull/merge requests and set baselines. We require that an executable git is available (on the $PATH ) of the chromatic script.

Common cases:

• Docker containers: Git may not be installed on certain Docker containers. You’ll need to make the image includes Git.
• Heroku CI: Git history isn’t available by default. You’ll have to give Heroku auth access to your repo so that it can clone it before running CI. This can be unideal. Some customers end up using other CI providers to run Chromatic like GitHub Actions (free) or CircleCI.
• Google Cloud CI: The .git folder is ignored by default. Based on their documentation you can try .gcloudignore. However, some customers have run into trouble with this solution and instead opted to use other CI providers to run Chromatic like GitHub Actions (free) or CircleCI.
• You don’t use Git: Enable Git version control in your project and try Chromatic again.

Debug yourself:

• Try running the command manually git log -n 1 --format="%H,%ct,%ce,%cn" and check if there are errors

Chromatic takes snapshots very quickly. However, if we lose the connection to your server (for instance if you stop your server mid-build, or your internet connection goes down), builds can time out. Check your connection and try restarting the build.

We do our best to interpret your Storybook script in package.json, but you might need to pass additional options to the chromatic command. Check out all the options »

Chromatic builds and runs Storybook flawlessly most of the time, but we’re not perfect (we wish). Sometimes builds don’t run due to rare infrastructure issues. If this happens, try to re-run the build via your CI provider. We keep track of these errors to improve the service.

This happens if certain stories were disabled via the chromatic: { disable: true } option at a higher level.

To solve this you can:

1. Remove the top-level chromatic: { disable: true } option
2. Enable snapshots for specific stories
3. Run yarn storybook-build locally and fix the issues in your stories

From Storybook 7.6 onwards, you can use the storybook doctor command to run checks and identify issues in Storybook: npx storybook@latest doctor

This tool helps detect problems like mismatched Storybook versions, duplicated dependencies, and incompatible add-ons. For each detected issue, it offers detailed descriptions, references, and suggestions for follow-up actions. Learn more here.

You can add the Storybook ESlint plugin to help you debug Storybook syntax issues and comply with best practices.

To debug an issue with your Storybook project, run the commands below locally and confirm all stories are loading correctly without console log errors and warnings.

​npm run build-storybook
npx http-server storybook-static -o

Use the same method to debug the following errors:

✖ Failed to verify your Storybook

✖ Failed to publish your built Storybook

✖ Failed to publish build - Failed to extract stories from your Storybook

If styles are not rendering correctly, there could be several reasons behind that:

1. The order in which stylesheets are loaded.

   • In development mode, styles from the preview might be imported earlier than component styles, while in production mode, this order could be reversed. This affects the specificity and, ultimately, the rendering of styles. If this is the case, the styles render but are overwritten by others.
   • In Storybook 6 and earlier, stylesheets were loaded upfront, while from Storybook 7 onwards, stylesheets are loaded on-demand when the story is viewed. This affects how styles load.

2. Browser compatibility. If the browser version does not support certain CSS features, styles may not apply correctly. Find browser versions supported by our Capture Infrastructure here.

If you have additional questions, use our in-app chat to contact or email us at support@chromatic.com.