@coder/pixel-storybook

@coder/pixel-storybook

Storybook engine for Coder Pixel, a visual regression testing platform. Builds your Storybook, captures screenshots of every story across a configurable browser/viewport/theme matrix, and reports them to the Pixel platform for comparison and review.

Installation

npm install @coder/pixel-storybook

Playwright browsers must be available:

npx playwright-core install chromium

Usage

PIXEL_KEY=<project api key> npx pixel-storybook

Configuration

Create a pixel.jsonc (or pixel.json) in your project root:

{
	// The base URL of your Pixel platform instance.
	"platformAccessUrl": "https://pixel.example.com",
	// The project ID on the platform.
	"projectId": "00000000-0000-0000-0000-000000000000",
	"storybook": {
		// Shell command that builds your Storybook.
		"buildCommand": "pnpm build-storybook",
		// Where the build output is written. (default: "storybook-static/")
		"outputDirectory": "storybook-static/",
	},
	// Matrix of variants to snapshot. (default: chrome x laptop)
	"matrix": {
		"browsers": ["chrome"],
		"viewports": ["phone", "laptop"],
		"colorSchemes": ["light", "dark"],
	},
}

Viewport variants only apply to stories with Storybook's parameters.layout: "fullscreen". Other layouts (centered, padded) size the story to its content, so those stories are captured once, cropped to the content plus a small padding, regardless of the configured viewports. A per-story matrix.viewports override still forces viewport variants, with a warning suggesting the layout should probably be fullscreen.

Environment variables

Variable	Purpose
PIXEL_KEY	Project API key (required)
PIXEL_COMMIT	Commit hash (default: GITHUB_SHA or git)
PIXEL_BASELINE_COMMIT	Baseline commit for comparison
PIXEL_BRANCH	Branch name (default: GitHub Actions refs or git)
PIXEL_AUTO_REVIEW	"true" to auto-approve snapshots (main builds)
PIXEL_CONFIG_DIR	Directory containing pixel.jsonc

Per-story options

Stories can customize capture behavior through parameters.pixel:

export const Primary: Story = {
	parameters: {
		pixel: {
			// Exclude this story entirely.
			exclude: false,
			// Per-story diff threshold.
			threshold: 0.1,
			// Elements to mask before capture.
			mask: [{ selector: ".timestamp" }],
			// Override the top-level matrix for this story.
			matrix: { viewports: ["phone", "desktop"] },
		},
	},
};

Inside a capture, isPixel() (exported from @coder/pixel-storybook/storyapi) returns true, so stories can disable animations or other nondeterministic behavior.