storybook-diff

A TypeScript CLI that compares two compiled Storybook directories and outputs JSON describing which stories were created, deleted, or modified.

For webpack builds, every compiled module is parsed into its exports and the imported names each export uses. A story is flagged only when something it actually uses changes: its own export, a component or helper it renders (at any depth), an npm package, or a global input such as the Storybook preview (decorators, parameters) or iframe.html. Vite builds are compared the same way from their minified chunks.

Quick start

npm install
npm run build

node dist/cli.js \
  test-samples/storybook-before \
  test-samples/storybook-after

Usage

storybook-diff <storybook-a-dir> <storybook-b-dir> [options]

Arguments

• storybook-a-dir: path to a compiled static Storybook directory (must contain index.json or stories.json and *.iframe.bundle.js files)
• storybook-b-dir: path to a second compiled static Storybook directory

Options

| Option | Description | |---|---| | --ignore-modules <patterns> | Comma-separated glob patterns of modules to ignore (repeatable) | | --no-rename-detection | Disable automatic rename detection |

Vite builds

Without *.iframe.bundle.js (webpack), the chunks under assets/ are parsed instead. The minifier renames variables across a whole chunk whenever anything in it changes, so code is compared with its names renumbered, following imports to the code they name. A story is flagged when anything it uses, runs at load time or preloads (CSS) differs; moving code between chunks is not a change. Rollup keeps no source paths, so changes are reported by chunk: story chunks by the story's import path, others as chunk:<name> (e.g. chunk:Button). Load-time changes in the preview entry (chunk:iframe) affect every story. Comparing webpack against Vite reports every story as modified (<builder changed>).

Ignoring modules

Nothing is ignored by default: changes are tracked per export, so a large generated module only flags the stories that use the exports that changed.

--ignore-modules takes glob patterns of modules whose own changes are ignored; changes in modules they import still count. Supports * (single segment) and ** (any depth), e.g. '*/generated/*', '**/node_modules/@faker-js/**', 'iframe.html'. Loader output matches its source file ('src/**/*.scss'). For Vite builds, shared chunks only match by chunk name, e.g. 'chunk:graphql*'.

Rename detection

Simple rename detection is checked for similarly named stories that were added/deleted in the same run, where the suffix and story name match exactly.

- /components/Old/MyComponent.tsx // MyStory
+ /components/New/MyComponent.tsx // MyStory

This can be disabled with the --no-rename-detection flag.

Output

The CLI prints JSON to stdout.

Example output

{
  "summary": {
    "totalA": 350,
    "totalB": 352,
    "created": 2,
    "deleted": 0,
    "modified": 1,
    "unchanged": 349,
    "contentChanged": 0,
    "dependencyChanged": 1
  },
  "created": [
    { "id": "sidebar-nav--collapsed", "title": "Sidebar/Nav", "name": "Collapsed" },
    { "id": "sidebar-nav--expanded", "title": "Sidebar/Nav", "name": "Expanded" }
  ],
  "deleted": [],
  "modified": [
    {
      "id": "button--primary",
      "title": "Button",
      "name": "Primary",
      "hashA": "abc123...",
      "hashB": "def456...",
      "changeType": "dependency",
      "triggeringModules": [
        "./src/components/Button/Button.tsx"
      ]
    }
  ],
  "changeSources": [
    {
      "modulePath": "./src/components/Button/Button.tsx",
      "affectedStoryCount": 1,
      "ignored": false
    },
    {
      "modulePath": "./src/generated/graphql-types.tsx",
      "affectedStoryCount": 200,
      "ignored": true
    }
  ],
  "ignoredModules": [
    "./src/generated/graphql-types.tsx"
  ]
}

Output schema

summary

| Field | Type | Description | |---|---|---| | totalA | number | Total stories in build A | | totalB | number | Total stories in build B | | created | number | Stories present only in B | | deleted | number | Stories present only in A | | modified | number | Stories present in both with changes detected (includes renames) | | unchanged | number | Stories present in both with no changes | | contentChanged | number | Modified stories where the story export itself changed | | dependencyChanged | number | Modified stories where a transitive dependency changed | | nameChanged | number? | Modified stories where the story was renamed between A and B |

created / deleted

Array of { id, title, name }.

modified

Array of objects sorted by ID, renames last:

| Field | Type | Description | |---|---|---| | id | string | Story ID | | title | string | Story title | | name | string | Story name | | hashA | string | Content hash from build A | | hashB | string | Content hash from build B | | changeType | "content" | "dependency" | "both" | "renamed" | What triggered the change | | triggeringModules | string[] | Change sources that reach the story (only present when changeType is "dependency" or "both") | | previousRef | { id, title, name } | The story's previous identity, only present when changeType is "renamed" |

changeSources

Array of every change with its blast radius:

| Field | Type | Description | |---|---|---| | modulePath | string | A source module path (loader output is reported by its source file, e.g. ./src/theme.scss), an npm package directory (e.g. ../node_modules/react), a global file (iframe.html, sb-preview/runtime.js), or chunk:<name> for Vite | | affectedStoryCount | number | How many stories use what changed | | ignored | boolean | Whether this module was filtered out |

ignoredModules

Array of module path strings that were filtered out. Only present when modules were ignored.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Invalid arguments | | 2 | Input directory or Storybook metadata could not be read | | 3 | Unexpected processing failure |

How it works

1. Load story metadata from index.json or stories.json in each build. Docs-only entries are excluded.
2. Parse every module in *.iframe.bundle.js (webpack). Each export gets a hash of its code and of the local code it uses, plus the list of imported names it references (import() included). Statements that run when the module loads are tracked separately, so evaluating a module only pulls in its load-time side effects. Those reach everything that loads the module for the project's own modules, global stylesheets and anything imported only for its side effects (import "dayjs/locale/en-au"); other npm package and CSS module imports reach stories through the exports they use. Unused styling and React factory calls left behind by the minifier (css(...), styled(...), memo(...)) are not effects. CommonJS and other non-ESM modules are hashed whole. Vite chunks are parsed the same way, statement by statement, with minified names renumbered. A build with nothing to index is an error rather than an empty diff.
3. Find global inputs: everything storybook-config-entry.js loads (the preview file, its decorators, addon and framework previews, and packages they import only for their side effects), iframe.html (including preview-head.html), and the scripts and stylesheets it loads outside the bundle, such as sb-preview/runtime.js, along with the files they import.
4. Compare builds export by export. Only build noise is normalised (webpack chunk ids, bundle file hashes, import numbering, and compiler-numbered helpers such as _templateObject12 and styled-components ids, which shift when code is added above them), so literals such as phone numbers and colours are compared exactly.
5. Walk back from each change to the stories that use it, in both builds. A change that the preview uses affects every story.
6. Diff snapshots by comparing stories by ID: created (only in B), deleted (only in A), modified (story export changed or it uses a change), unchanged.

Development

npm install
npm run build        # compile TypeScript
npm test             # build + run tests

Test fixtures live in test/fixtures/.

Real-world test samples can be placed in test-samples/ or test-samples-<group>/.