storybranch

storybranch

Alpha

Local visual diffs for Storybook

Capture stories as PNGs in Chrome, Firefox, Edge, and Safari, pixel-diff against baselines on disk, and accept changes in a review UI — no cloud required.

See a reviewView on GitHub
$ npm install -D @adriangohjw/storybranch
$ npm run visual

Add "visual": "storybranch test --url http://127.0.0.1:6006" to the app’s scripts. Storybook must be running at that URL.

~/my-app — storybranch
$ npm run visual
storybranch review at http://127.0.0.1:4321
12 snapshots scanned · 4.2s build time
3 snapshots need attention · 1 new · 2 changed
-> new: button--primary
-> changed: button--hover
-> changed: button--disabled

Review changes in the browser

When something drifts, storybranch serves a local UI to compare baseline vs this scan (with an optional diff overlay) and accept updates.

storybranch review

commit a589471 · 5 snapshots

changedchrome

hero / default

1200x900 · chrome

hero--default__1200x900__chrome.png

Baseline
Baseline snapshot
This scan
Diff overlay
This scan

What you need before the first capture

Storybook on a URL the capture browsers can open, baselines as files, and a first run that is supposed to fail.

  1. 01

    Your Storybook

    Point storybranch at a running Storybook URL. The default snapshot is Chrome. Add Firefox, Edge, or Safari with --browsers or storybranch.config.json next to .storybook/. webkit is an alias for safari. Linux WebKit screenshots do not match macOS. Chromatic modes or viewports on a story become extra snapshots. Setting both on one story is an error.

    storybranch test --url …

  2. 02

    Baselines in git

    Commit .storybranch/baseline/. Leave actual/, diff/, and report.json untracked so pull requests show the images that matter.

    .storybranch/baseline/

  3. 03

    First run

    A first run exits 1 with a snapshot summary (new counts). That is the baseline set. npm run visual:approve writes those PNGs.

    snapshots need attention …

  4. 04

    Sidebar addon

    Optional Storybook sidebar addon: register @adriangohjw/storybranch/addon to run capture from the UI and highlight stories from the last report.json. Accept baselines in the review UI, not in the addon.

    addons: ["@adriangohjw/storybranch/addon"]

Scripts in your app, then ship

Install with npm, pnpm, or bun (see #install). No dashboard signup. Baselines are files you already know how to review in a PR. For GitHub Actions, see CI.

  1. Step 1

    Run Storybook

    Start Storybook locally, or anywhere Chrome, Firefox, Edge, and Safari can reach it. Install includes Chrome. Firefox, Edge, and WebKit are extra Playwright browsers. Linux WebKit is not Apple Safari, and its screenshots do not match a macOS runner.

    $ npx storybook dev -p 6006

  2. Step 2

    Capture & diff

    npm run visual walks the story index and writes one PNG per story, mode, and browser. Names look like hero--default__1200x900__chrome.png. Exit 1 means a shot needs attention.

    $ npm run visual

  3. Step 3

    Review or approve

    Reopen the review UI, or promote every actual into baseline/.

    $ npm run visual:review npm run visual:approve

  4. Step 4

    Ship in CI

    In GitHub Actions, build Storybook and run storybranch with --exit-once so the job does not start the review server. Pull requests can pass --only-changed. See the CI page for a copy-paste workflow.

    $ storybook build && storybranch test --build --exit-once

Add it to your app

Install @adriangohjw/storybranch as a dev dependency. That install downloads Chrome. Add Firefox, Edge, or WebKit (`safari` or `webkit`) with Playwright when a config or --browsers asks for them, then run the script against your Storybook URL. Linux WebKit screenshots do not match macOS.

"visual": "storybranch test --url http://127.0.0.1:6006"
$ npm install -D @adriangohjw/storybranch
$ npm run visual
GitHub repositoryGitHub Actions CIAgent snippetFull README