storybranch

storybranch

Alpha

Local visual diffs for Storybook

Capture stories as PNGs, pixel-diff against baselines on disk, and accept changes in a browser 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
missing baseline button--default__1200x900.png
pixels button--modes__narrow.png

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

Baseline
baseline
This scan
Diff overlay
this scan

What you need before the first capture

Storybook on a URL Chromium 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. 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 and prints missing baseline for every shot. That is the baseline set. npm run visual:approve writes those PNGs.

    missing baseline …

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 Chromium can reach it.

    $ npx storybook dev -p 6006

  2. Step 2

    Capture & diff

    npm run visual walks the story index, writes PNGs, and compares them to committed baselines. 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`. - `visual` runs `storybranch test --url <storybook>`. Exit 1 means a visual diff. Lines: `missing baseline`, `pixels`, `size`, `stale`. A clean run prints `ok`. - Read `.storybranch/report.json` (`new`, `changed`, `unchanged`, `stale`, `error`). - The first run is `missing baseline` for every shot. - Commit only `.storybranch/baseline/`. 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. Chromium downloads in that install, then add a script and run it against your running Storybook URL.

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