README.md

vite-plugin-turbosnap

Generate a preview-stats.json file from your vite storybook project for consumption by chromatic cli to support turbosnap. Turbosnap can limit the number of files that are snapshotted by Chromatic to only those which might have changed due to the files that have changed. It is also smart enough to run all of the snapshots if certain files, like storybook config, package.json, or anything imported by preview.js has changed.

This is experimental, and may not support all project and storybook configurations, yet.

Please open an issue if you experience any trouble, and be sure to include the log file that is generated from the --diagnostics flag of chromatic-cli, as well as the cli's output using the --debug --trace-changed=expanded flags.

Note

Storybook 8 has this plugin built-in and will automatically remove it from your config. Use --stats-json when building Storybook to enable Turbosnap instead.

Setup

Prerequisites

• A Chromatic account.
• chromatic-cli 6.5.0 or higher.
• Storybook 7, or 6.5 with @storybook/builder-vite 0.1.22 or higher.

Install

npm i --save-dev vite-plugin-turbosnap

Configuration

Add this plugin to viteFinal in your .storybook/main.js:

// .storybook/main.js

import turbosnap from "vite-plugin-turbosnap";
import { mergeConfig } from "vite";

export default {
  // ... your existing storybook config
  async viteFinal(config, { configType }) {
    return mergeConfig(config, {
      plugins:
        configType === "PRODUCTION"
          ? [
              turbosnap({
                // This should be the base path of your storybook.  In monorepos, you may only need process.cwd().
                rootDir: config.root ?? process.cwd(),
              }),
            ]
          : [],
    });
  },
};

Usage

When you run build-storybook to create your production storybook, an additional file will be created in the output directory, named preview-stats.json. See the chromatic turbosnap docs for more information on how to configure and use turbosnap.

How it works

The turbosnap feature of Chromatic limits the snapshots that are executed to only those which can be reliably traced back to a changed file. In order to do this, it needs to have a dependency graph of the project, so that it knows when you change button.js, for instance, that it needs to re-run not only the button.stories.js file, but also any other stories which might include your custom button component. By default, it relies on the stats file that is output from webpack, the default storybook builder. In order to use this feature with a vite project, this plugin collects information about each module being built by vite, constructs a mapping between each file and all of the files which import it, and generates a file that mimics that created by webpack, with only the information that the chromatic cli needs to perform its checks.

Credits

Thanks to Gert Hengeveld for guidance on chromatic cli changes, and to my team at Defined Networking for giving me the time to build and test this on our own chromatic storybook project.