Sign inSign up
Setup
Interaction tests
Publish
Composition

Storybook Composition

Chromatic publishes your Storybook to a secure CDN. That means you can combine published Storybooks with your local Storybook using Composition.

Chromatic does not snapshot externally composed Storybooks for UI Tests or UI Review.

Compose published Storybooks

Chromatic generates a permalink for published Storybooks to use with Composition that includes:

  • Versioned endpoints, URLs that resolve to different published Storybooks depending on a version=x.y.z query parameter (where x.y.z is the released version of the package).
  • Support for /stories.json
  • Support for /metadata.json and the releases field.

Setup

In your local Storybook, add a refs key to .storybook/main.js. Paste the permalink in the url field.

// .storybook/main.js

const config = {
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
  refs: {
    // 👇 Upper-case characters not supported in the refs key
    "chromatic-published-storybook": {
      // The title of your Storybook
      title: "Design System",
      // The url provided by Chromatic when it was published
      url: "https://your-published-url.chromatic.com",
    },
  },
};

export default config;

When your local Storybook starts, it will auto detect the refs and compose your published Storybook. You’ll see both sets of stories side-by-side.

Multiple Storybooks combined through composition

Compose Storybook by branch or commit

Depending on your use case, you may want to compose Storybook using a permalink to a branch or a commit.

Branch: https://<branch>--<appid>.chromatic.com

If you want your local Storybook to compose the latest Storybook on main, use the branch permalink. This is useful for folks who work on multiple Storybooks simultaneously.

  • Building a component library in React and Vue at the same time
  • Monorepos with multiple inter-connected Storybook projects

Commit: https://<commithash>--<appid>.chromatic.com

If you want your local Storybook to compose a specific version of Storybook, use the commit permalink. This is useful for folks who depend on a fixed version of a component library package.

Access control

Published Storybooks follow the access rules of your project. If you have a private project, you’ll need sign in to Chromatic (via Storybook’s UI) to load the private Storybook.


Package Composition

Design system and component library authors can automatically compose their Storybook inside their consumer’s Storybooks.

Add a storybook property in the package.json. Use the permalink to a commit in the url field.

{
  "storybook": {
    "url": "https://your-published-url.chromatic.com"
  }
}

Once the package is installed and Storybook starts, it scans for external Storybooks referenced by your packages and loads them into the UI.

Versioning

Chromatic supports automatic versioning for the following Git providers.

Git providerSupport
GitHubPublic projects only via GitHub Releases
GitLabPublic and private projects
BitbucketNot supported
Unlinked projectsNot supported
How to manually query for versions?

If automatic versioning isn’t supported for your Git provider, you can still get version information by manually updating your package.json with the permalink of the current published Storybook (e.g. https://<commithash>--<appid>.chromatic.com).

Use the /metadata.json endpoint to get additional information about the deployed Storybook version. It will output a response similar to the example below:

{
  "versions": {
    "v0.1.1": "https://your-published-url.chromatic.com"
  }
}

Resources