storybranch

storybranch

Alpha

Local visual diffs for Storybook

Capture stories as PNGs in Chrome, Firefox, and Edge, 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 or Edge with --browsers or storybranch.config.json next to .storybook/. 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 …

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.

  1. Step 1

    Run Storybook

    Start Storybook locally, or anywhere Chrome, Firefox, and Edge can reach it. Install includes Chrome. Firefox and Edge are extra Playwright browsers.

    $ 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

For agents in your app

Paste the ignore rules into the app that owns the baselines, and the note into that repo’s AGENTS.md.

.gitignore

Keep .storybranch/baseline/ tracked.

.storybranch/actual/ .storybranch/diff/ .storybranch/report.json

AGENTS.md

Exit 1 on the first run is the baseline set. Approve only when a person asked for it.

## storybranch `@adriangohjw/storybranch` is a dev dependency. Storybook must already be running at your `--url`. Run `npm run visual` from the package that has `.storybook/` (or pass `--cwd`). - `visual` runs `storybranch test --url <storybook>`. Exit 1 means a visual diff. In a terminal you get scan time, a status summary, and one `->` row per snapshot, plus `storybranch review at …`; in CI/non-TTY you get `missing baseline`, `pixels`, `size`, or `stale` per snapshot. A clean run prints `ok`. - Default browser is `chrome`. Filenames end in `__chrome.png`, `__firefox.png`, or `__edge.png`. Extra browsers come from `storybranch.config.json` or `storybranch.config.ts` in that package, or from `--browsers`. - Read `.storybranch/report.json` in that package (`new`, `changed`, `unchanged`, `stale`, `error`). - The first run lists every shot as `new` in the summary (or `missing baseline` lines in CI). - Commit only `.storybranch/baseline/` in that package. Ignore `actual/`, `diff/`, and `report.json`. - Run `npm run visual:approve` only when asked to accept the shots. `visual:review` and `--open` are for a person.

Add it to your app

Install @adriangohjw/storybranch as a dev dependency. That install downloads Chrome. Add Firefox or Edge with Playwright when a config or --browsers asks for them, then run the script against your Storybook URL.

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