Skip to content
Vizzly Docs

Storybook SDK Overview

The Storybook package adds a vizzly storybook <path> command.

It reads your built index.json, finds stories, opens them in a browser, and captures screenshots across configured viewports.

Install

Terminal window
npm install -D @vizzly-testing/cli @vizzly-testing/storybook
npx playwright-core install chromium

Run it

Terminal window
npm run build-storybook
vizzly storybook ./storybook-static

For local review:

Terminal window
vizzly tdd start
vizzly storybook ./storybook-static

For cloud builds, make sure VIZZLY_TOKEN is available.

The command auto-detects local TDD mode from .vizzly/server.json. If no local server is running, it uses apiKey or VIZZLY_TOKEN for cloud upload. If neither is available, it warns and skips capture instead of pretending a cloud build happened.

Config

The plugin defaults include:

export default {
  storybook: {
    viewports: [
      { name: 'mobile', width: 375, height: 667 },
      { name: 'desktop', width: 1920, height: 1080 },
    ],
    browser: {
      type: 'chromium',
      headless: true,
      args: [],
    },
    screenshot: {
      fullPage: true,
      omitBackground: false,
      timeout: 45000,
    },
    include: null,
    exclude: null,
    interactions: {},
  },
};

Omit concurrency to let Vizzly choose a number from your CPU count, or set a positive integer to override it. screenshot.timeout is the Playwright capture timeout. Add screenshot.requestTimeout when you need to override the Vizzly upload/request timeout.

Custom browser.args are appended after Vizzly’s Chromium defaults.

Cloud builds also honor top-level build.*, comparison.*, parallelId, git metadata, and PR metadata from config, flags, and CI environment variables.

Useful CLI flags

Terminal window
vizzly storybook ./storybook-static --include "components/**"
vizzly storybook ./storybook-static --exclude "**/*.deprecated"
vizzly storybook ./storybook-static --viewports "mobile:375x667,desktop:1920x1080"
vizzly storybook ./storybook-static --concurrency 5
vizzly storybook ./storybook-static --browser chromium --timeout 45000 --request-timeout 60000

Skipping stories

Stories can be skipped with Storybook parameters or tags.

The plugin supports:

  • parameters.vizzly.skip
  • vizzly-skip story tags

Per-story overrides

You can also set per-story options in Storybook:

export let Primary = {
  parameters: {
    vizzly: {
      skip: false,
    },
  },
};

Next steps