How to Use Chromatic with Vite and Storybook

To use Chromatic with Vite and Storybook, use Storybook’s Vite builder, add the official @chromatic-com/storybook addon, connect a Chromatic project, then publish Storybook with the Chromatic CLI. Your first build establishes visual baselines; later builds compare story screenshots with those baselines so you can review changes. In CI, store the project token as a protected secret and publish on pull requests.

This workflow checks rendered appearance, such as layout, color, size, and contrast. It does not prove that every interaction or application behavior works; combine it with interaction, accessibility, and other tests as needed.

1. Confirm Storybook is using Vite

In a Vite application, Storybook’s Vite builder is the standard starting point and can reuse the project’s Vite configuration. If Storybook is already initialized, the builder may already be installed. Check .storybook/main.ts (or the JavaScript equivalent) and the installed Storybook framework before adding packages or changing configuration.

Keep Vite settings in the application’s Vite config where possible. Add Storybook-specific changes through viteFinal only when needed. Avoid copying Webpack settings into a Vite project unless you have confirmed an equivalent applies. See the Storybook Vite builder documentation.

2. Add the Chromatic Storybook addon

npx storybook@latest add @chromatic-com/storybook

The addon can install and configure the integration. The cited Storybook 8 documentation says Storybook 7.6 or later is required; check the current addon documentation against your installed Storybook version before upgrading or following version-specific steps: Storybook visual testing.

Create or select a project in Chromatic and connect it during addon setup. The setup can add the required configuration and project identifier. Treat project tokens as credentials: do not commit a real token in source control.

3. Publish the first build and create baselines

Install the CLI as a project dependency if your team wants a pinned, repeatable version, then run it using your project token. Replace the placeholder with a token supplied securely in your shell:

npm install --save-dev chromatic
CHROMATIC_PROJECT_TOKEN=YOUR_PROJECT_TOKEN npx chromatic

The CLI builds and uploads Storybook, then starts Chromatic’s publishing and testing workflow. The first build captures snapshots that become the comparison baseline. Later builds compare new story snapshots with those accepted baselines. See the Chromatic CLI documentation.

For a quick local run, you can pass the token as an option instead, but avoid putting secrets in shell history or committed scripts:

npx chromatic --project-token=YOUR_PROJECT_TOKEN

4. Review visual changes and update baselines

Open the published build and inspect the highlighted visual differences.
For an intended design change, accept the change so it becomes the new baseline.
For an unexpected difference, fix the component, styles, data, or rendering conditions and publish again.
Confirm accepted baselines synchronize for teammates and later CI builds.

Pixel comparison evaluates rendered appearance; markup snapshot comparison evaluates rendered HTML. A visual pass is not a substitute for behavioral or accessibility checks. Storybook describes its visual testing integration in the visual testing guide.

5. Configure Vite only when the defaults need adjustment

Keep the setup minimal until a real incompatibility appears. If Storybook must read a Vite configuration stored somewhere other than the expected project root, configure the builder’s viteConfigPath. If only Storybook needs a plugin, alias, or define adjustment, merge it through viteFinal in .storybook/main.ts. The option names and types can vary with the builder version, so use the documentation matching the installed Storybook release.

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
import { mergeConfig } from 'vite';

const config: StorybookConfig = {
  framework: '@storybook/react-vite',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@chromatic-com/storybook'],
  async viteFinal(baseConfig) {
    return mergeConfig(baseConfig, {
      // Add only Storybook-specific Vite settings here.
      resolve: { alias: { '@': '/src' } },
    });
  },
};

export default config;

This is an example shape for a React/Vite Storybook; retain your existing framework and story globs. Ensure any alias points to the correct absolute path for your project. If Vite configuration is already shared correctly, omit viteFinal. Refer to the builder options for viteConfigPath and viteFinal.

6. Run Chromatic in GitHub Actions

Add the project token under your repository’s Actions secrets, conventionally named CHROMATIC_PROJECT_TOKEN. Then add a workflow such as the following. The action tag shown is a major-version reference; check Chromatic’s current documentation and pin a specific action version or commit according to your repository policy.

# .github/workflows/chromatic.yml
name: Chromatic

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  chromatic:
    name: Publish Storybook to Chromatic
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - uses: chromaui/action@v1
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

Runner versions and action tags change over time; confirm them against the official Chromatic GitHub Action documentation. Protect the secret and limit where it is available, particularly for workflows that process contributions from forks. The action publishes the build and reports its result to the pull request.

CLI versus the GitHub Action

Approach	Useful when	Configuration and credentials
Chromatic CLI	You need a portable command for local use or any CI provider.	Pass the project token through a secure environment variable or supported config.
GitHub Action	You want a repository-native pull request check.	Store the token as a repository secret and pin the action version.

Both publish Storybook and use the project’s synchronized baselines. The local addon supports interactive review; CI provides repeatable publishing and checks.

7. Configure the CLI when the project needs it

The CLI reads chromatic.config.json from the project root. Command-line flags take precedence over config-file options. The project token authenticates a build. For a custom Storybook build script or a prebuilt Storybook directory, configure the CLI to use the correct script or output directory rather than assuming the default applies.

{
  "$schema": "https://www.chromatic.com/config-file.schema.json",
  "projectToken": "YOUR_PROJECT_TOKEN"
}

Do not put an actual token in a committed config file. Prefer injecting it from the environment or CI secret. Consult the CLI options reference for the current option names for custom scripts, build directories, and other flags.

8. Check published Storybook visibility

Published Storybooks are private by default for logged-in collaborators, and public visibility is available as a setting. Before sharing a published link outside the team, check the project’s visibility setting and make sure it matches your intended audience. See Chromatic publishing documentation.

Or skip the browser setup

If you need screenshots of a live page while debugging a story or checking a deployed preview, ScreenshotNeo is a website screenshot API and MCP server. It does not replace Chromatic’s story baseline workflow; it gives you a direct way to capture a URL without setting up browser automation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Equivalent requests in Python and Node.js:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

See the ScreenshotNeo API documentation for request options. Cookie banners are accepted and removed before capture, along with known newsletter popups and chat widgets; those cleanup steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server exposes screenshot, page-info, and PDF-capture tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.

Troubleshooting

Symptom	Likely cause	What to do
Storybook uses the wrong builder or fails to start.	The framework package or builder configuration does not match the project’s Storybook version.	Check the installed framework and Vite builder documentation; avoid carrying over Webpack-only configuration.
Vite alias or plugin works in the app but not in Storybook.	Storybook is not loading the expected Vite config, or requires a Storybook-specific adjustment.	Use the correct `viteConfigPath` or merge the needed setting through `viteFinal`.
Addon installation reports a version incompatibility.	The installed Storybook version is older than the addon supports.	Check the current addon requirements. The cited Storybook 8 page specifies 7.6 or later.
Chromatic reports an authentication or project error.	The token is missing, invalid, or belongs to a different project.	Verify the selected project and secret value; do not expose the token in logs or source control.
CI succeeds locally but cannot find Storybook.	The workflow uses a custom build script or output directory that the CLI/action does not know about.	Configure the documented script or directory option, or let Chromatic run the expected build script.
Many stories change unexpectedly.	Rendered output may depend on fonts, assets, timing, environment variables, or data that differ between builds.	Make rendering inputs deterministic, ensure required assets are available, and review changes before accepting a new baseline.
A pull request from a fork cannot publish.	Repository secrets are generally unavailable to untrusted fork workflows.	Use a secure workflow design that does not expose project credentials to untrusted code; consult GitHub and Chromatic guidance.

Performance, reliability, and cost considerations

Build cost: Chromatic must build and upload the Storybook. Keep stories and dependencies intentional, and use the documented large-build options when needed.
Stable comparisons: Deterministic story inputs reduce noisy differences. Control fonts, data, animation, and timing where they affect rendered output.
Baseline reliability: Treat acceptance as a review decision. Accepting a difference changes the comparison target for the team.
CI reliability: Use a protected secret, checkout history as recommended by the action docs, and pin action versions so workflow behavior is predictable.
Plan and usage cost: Chromatic’s pricing and included usage can change. Check the current plan details before estimating project cost; this research does not establish a price or usage quota.

FAQ

Does Chromatic test the whole Vite application?

It tests the stories published from Storybook. Add stories for the components and states you want visually checked.

Will a visual test catch a broken click handler?

A screenshot comparison checks appearance, not the full behavior of an interaction. Use interaction tests or application tests for behavior.

Accepted baselines synchronize to the cloud for teammates and CI. Check project visibility before sharing published content externally.

Can I use this setup outside GitHub Actions?

Yes. The Chromatic CLI can run in other CI providers; the GitHub Action is one automation option.