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

The package is not on npm yet

$ git clone https://github.com/adriangohjw/storybranch.git && cd storybranch && bun install && bunx playwright install chromium && bun run build

Then, from your app, with Storybook 10+ already running:

$ bun /path/to/storybranch/apps/cli/src/cli.ts test --url http://127.0.0.1:6006

After publish, that second command is bunx storybranch test --url http://127.0.0.1:6006.

~/my-app — storybranch
$ storybranch test --url http://127.0.0.1:6006
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 10+ URL. Chromatic modes or viewports on a story become extra snapshots. Setting both on one story is an error.

    Storybook 10+

  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. approve writes those PNGs.

    missing baseline …

Three commands, then ship

No dashboard signup. Baselines are files you already know how to review in a PR.

Today storybranch is bun /path/to/storybranch/apps/cli/src/cli.ts after the clone in the hero. After publish, it is bunx storybranch.

  1. Step 1

    Run Storybook

    Start Storybook 10+ locally, or anywhere Chromium can reach it.

    $ bunx storybook dev -p 6006

  2. Step 2

    Capture & diff

    storybranch walks the story index, writes PNGs, and compares them to committed baselines. Exit 1 means a shot needs attention.

    $ storybranch test --url http://127.0.0.1:6006

  3. Step 3

    Review or approve

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

    $ storybranch review storybranch 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 Storybook 10+ must already be running. Until storybranch is on npm, invoke `bun /path/to/storybranch/apps/cli/src/cli.ts`. After publish, `bunx storybranch` is the same CLI. - `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 `approve` only when asked to accept the shots. `review` and `--open` are for a person.

Run it on your Storybook

The package is not on npm yet. Clone and build, then run the CLI from your app so the baselines land there. Storybook 10+ should already be up.

$ git clone https://github.com/adriangohjw/storybranch.git && cd storybranch && bun install && bunx playwright install chromium && bun run build
$ bun /path/to/storybranch/apps/cli/src/cli.ts test --url http://127.0.0.1:6006

After publish, the second command is bunx storybranch test --url http://127.0.0.1:6006.

GitHub repositoryAgent snippetFull README