Sign inSign up
Introduction

Setup and publish Storybook

The Chromatic CLI builds then publishes Storybook to a secure workspace in the cloud. That allows your team to access all your stories at chromatic.com.

Publish Storybook

Sign up

Before publishing, generate a unique project token for your Storybook by signing in to Chromatic and creating a project. Sign in with your GitHub, GitLab, Bitbucket, or email.

How to continue setup if you require SSO, on-premises, or have a different Git provider.

These instructions will teach you how to setup Chromatic with an “unlinked” project. This can be useful in these situations:

  • You need an enterprise plan but want to trial Chromatic in your project first
  • You use an OAuth provider that we don’t support right now
  • You use Git hosting that we don’t support right now

Start by signing 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.

Select “Create a project” and type your project name to create an unlinked project.

Setup 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.

Now continue setting up Chromatic as usual.

Setup project

Install

Install the chromatic package from npm.

npm install --save-dev chromatic

Storybook 6.5 or later is required. We also guarantee support for Node 14.18.x through Node 16.19.1. Other Node releases may encounter errors. To switch between Node versions, we recommend using nvm, n, or another version manager.

Learn how to add chromatic to your package.json

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.

Setup .gitignore to ignore certain files in your Git repository

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

Run Chromatic

Once you installed the chromatic package and have a project token, run the following command in your project directory.

npx chromatic --project-token <your-project-token>

We use the build-storybook script from your package.json by default. If you have customized the storybook script (for example, adding a static directory with -s), check that you’ve done the same for build-storybook.

When complete, you’ll see the build status and a link to the published Storybook:

Build 1 published.

View it online at https://www.chromatic.com/build?appId=...&number=1.

View published Storybook

You published Storybook online! Every time you run the chromatic command you get a corresponding build in Chromatic’s web app. You can now browse components, view UI Tests results (if enabled), and navigate to associated PR/MRs for UI Review.

Build for publish

Get the PR check

Chromatic posts a “Storybook Publish” status check in your pull/merge request that links to the latest published Storybook. This gives teams secure, convenient access to browse components and stories. Get the PR check by automating Chromatic with CI.

PR badge for publish

During setup we recommend running chromatic on the command line to make sure the configuration is correct. For production use run Chromatic in CI.


Next: Catch UI bugs

📸 Now that you published Storybook, let’s see how to automate UI Tests to catch bugs.

Read next chapter


Command options

If you have customized the way your Storybook runs, you may need to pass additional options to the chromatic command. Learn more in the package documentation.

Troubleshooting

Command error git log -n 1

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
Why do my builds timeout

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.

Chromatic doesn’t work with my custom Storybook script

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 »

Why do I get errored builds randomly?

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.

Why is my build failing with the message Cannot run a build with no stories?

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