found-pixel

Storybook build + visual regression workflow for Buildkite, in one CLI.

Each consumer repo drops in a .storybook/found-pixel.config.json and one pipeline step instead of copying shell + Node scripts between repos.

What it does

On every build:

1. Runs the configured storybook build command
2. Uploads the archive and static site to S3 under <repoName>/storybook/<branch-slug>/
3. Annotates the Buildkite build with a link to the hosted storybook
4. If the branch is the default branch, also uploads under the commit SHA for future base resolution

On pull requests (additional to the above):

5. Resolves a base storybook from S3 — tries merge-base SHA first (for PRs into the default branch), then the base branch slug, then the default branch
6. Runs storybook-diff between base and head, writing the JSON to artifacts/
7. Runs lost-pixel against the changed stories only, capturing pixel-level diffs; uploads screenshots to S3 and constructs PR comment image URLs via screenshots.baseUrl (if configured)
8. Upserts a PR comment with added / deleted / modified sections, thumbnail previews for stories with visual changes, and a "Detected N story changes" summary
9. Annotates the Buildkite build with a diff summary and a link to the PR comment

Install

In the consumer repo:

npm install --save-dev found-pixel
# or
yarn add --dev found-pixel

Runtime requirements on the Buildkite agent:

• Node 20+
• aws CLI (for S3 reads/writes)
• git (for merge-base resolution)
• buildkite-agent (for annotations and artifact upload)

Chromium is installed lazily on first review run via playwright install --with-deps chromium, using the playwright-core copy bundled with lost-pixel (so browser revisions match lost-pixel's expectations).

Configuration

Create found-pixel.config.json in one of the following locations (searched in order, first match wins):

1. ./found-pixel.config.json (repo root)
2. ./.storybook/found-pixel.config.json
3. ./.github/found-pixel.config.json
4. ./tools/storybook/found-pixel.config.json

Example:

{
  "defaultBranch": "master",
  "buildCommand": "npm run build-storybook",
  "outputDir": "storybook-static",
  "artifactsDir": "artifacts",
  "s3": {
    "bucket": "my-org-storybook",
    "region": "ap-southeast-2"
  },
  "screenshots": {
    "baseUrl": "https://d1234abcd.cloudfront.net",
    "s3": {
      "bucket": "my-org-screenshots",
      "region": "ap-southeast-2"
    },
    "uploadPrefix": "public"
  },
  "github": {
    "repo": "my-org/my-app"
  },
  "storybookDiff": {
    "ignoreModules": [
      "*/generated/*"
    ],
    "maxDepth": 5,
    "autoIgnoreThreshold": 50,
    "useGitattributes": true
  },
  "visualRegression": {
    "enabled": true
  },
  "comment": {
    "heading": "📘 UI Review",
    "marker": "<!-- found-pixel-comment -->",
    "viewerUrl": "https://my-org.github.io/diffy",
    "maxChars": 62000,
    "codeOnlyStoriesLimit": 25
  }
}

Required: s3.bucket, s3.region, github.repo.

Notable defaults (all optional):

• buildCommand: "npm run build-storybook"
• outputDir: "storybook-static"
• artifactsDir: "artifacts"
• defaultBranch: "master"
• visualRegression.enabled: true
• comment.heading: "📘 Storybook Review"
• comment.marker: "<!-- found-pixel-comment -->"
• comment.maxChars: 62000
• screenshots.uploadPrefix: public"

screenshots is optional. When provided, visual regression screenshots are uploaded to screenshots.s3 under <repoName>/shots/<slug>/. Set screenshots.baseUrl to the domain serving that bucket (e.g. a CloudFront distribution) — image URLs in the PR comment are then constructed as ${baseUrl}/${key}. Set screenshots.uploadPrefix if your bucket serves content from a subdirectory (e.g. "public" uploads to public/<key> but the CDN serves it at baseUrl/<key>). Without a baseUrl, screenshots are still uploaded but no thumbnail URLs are generated. When screenshots is omitted entirely, screenshots are not uploaded.

comment.viewerUrl is optional. When set, diff thumbnails in the PR comment link to the viewer with ?id=<storyId>&r=<repo>&a=<baseSlug>&b=<compareSlug>. When unset, thumbnails link directly to the screenshot URL.

storybookDiff options

All flags accepted by the storybook-diff CLI:

| Key | Type | Default | Maps to | |---|---|---|---| | ignoreModules | string[] | [] | --ignore-modules (repeatable) | | maxDepth | number \| null | 5 | --max-depth N, or --no-depth-limit when null | | autoIgnoreThreshold | number | 50 | --auto-ignore-threshold N | | useGitattributes | boolean | true | --no-gitattributes when false |

See src/config.ts for the full zod schema.

Environment variables

Read from the Buildkite environment automatically:

| Variable | Purpose | |---|---| | BUILDKITE_BRANCH | Current branch (slugified with / → - unless BRANCH_SLUG is set) | | BUILDKITE_COMMIT | Commit SHA; used as the upload key on default-branch builds | | BUILDKITE_BUILD_URL | Linked from the PR comment and annotations | | BUILDKITE_JOB_ID | Linked from the PR comment and annotations | | BUILDKITE_PULL_REQUEST | PR number, or "false" for non-PR builds | | BUILDKITE_PULL_REQUEST_BASE_BRANCH | Target branch; drives base-storybook resolution | | BRANCH_SLUG | Optional override for the derived slug | | GITHUB_PR_TOKEN or GITHUB_TOKEN | Optional GitHub Pull Request integration |

Pipeline usage

Buildkite pipeline step:

steps:
  - label: ":storybook: Visual Regression"
    command: npx found-pixel run
    plugins:
      - docker#v5:
          image: node:20

Or split across steps if you want to parallelise other work:

steps:
  - label: ":storybook: Build"
    command: npx found-pixel build
    key: storybook-build

  - label: ":mag: Review"
    command: npx found-pixel review
    depends_on: storybook-build
    if: build.pull_request.id != null

CLI reference

found-pixel build    # build storybook, upload to S3, annotate
found-pixel review   # (PR only) download base, diff, regress, upsert comment
found-pixel run      # build then review

review is a no-op when the build isn't a pull request.

Library usage

The comment renderer is a pure function, exported for reuse in custom pipelines:

import { renderComment } from "found-pixel/comment";

const body = renderComment({
  diff,                            // storybook-diff JSON output
  visualIds,                       // string[] | undefined
  baseSlug,
  compareSlug,
  repoName,
  buildUrl,
  storybookUrl: (slug) => `https://.../storybook/${slug}/admin/index.html`,
  shotUrl: (storyId, kind) => urls[kind][storyId] ?? null,
  comment: {
    heading: "📘 UI Review",
    marker: "<!-- found-pixel-comment -->",
    maxChars: 62000,
    codeOnlyStoriesLimit: 25,
    viewerUrl: "https://diffy.example.com",
  },
});

Development

npm install
npm test           # runs vitest against all fixtures
npm run build      # tsc → dist/
npm run typecheck  # tsc --noEmit

Comment format changes

The comment generator has snapshot tests that write rendered markdown to test/snapshots/*.md. The .md files are committed so diffs are reviewable inline when the format changes.

Workflow:

# 1. Change src/comment.ts
# 2. Regenerate snapshots
npm run test:update
# 3. Inspect the diff in test/snapshots/*.md before committing

To preview a single fixture without running the test suite:

npm run preview-comment modified-with-visuals

Adding a fixture

1. Create test/fixtures/<name>/input.json matching the shape in test/helpers.ts (FixtureInput)
2. Run npm run test:update to create the snapshot
3. Review the generated test/snapshots/<name>.md

Size-driven cases (large-diff collapsing, oversized truncation) are programmatic in test/comment.test.ts rather than on-disk fixtures, since their scale would make the input JSON unreviewable.