Join our Discord
IntelliStory for Storybook
Speed up your Percy Storybook builds by snapshotting only the stories whose code changed since your last build.
IntelliStory uses your Git history to identify the files that changed since your last Percy build and snapshots only the stories affected by those changes. Unchanged stories reuse their existing baselines. This reduces snapshot count and shortens build time.
Prerequisites
Before you start, ensure that you have the following installed:
Follow these steps to enable IntelliStory on your Storybook project.
Install the Percy CLI
Install the Percy CLI, the Storybook package, and the IntelliStory bundler plugin in your project.
Add the bundler plugin
Add the bundler-plugin-smartsnap plugin that matches your Storybook builder to your .storybook/main.ts. It emits the enriched-stats.json file that IntelliStory reads. For the full configuration reference, see the bundler-plugin-smartsnap README.
If your Storybook uses the Vite builder (@storybook/*-vite), add vitePlugin() to the Vite plugin list inside viteFinal.
If your Storybook uses the Webpack 5 builder (@storybook/builder-webpack5), push webpackPlugin() onto config.plugins inside webpackFinal.
Both plugins accept an outFile option (default enriched-stats.json) if you need to change the emitted filename, relative to the bundle output directory.
Build Storybook
Build your Storybook to generate the static build directory along with the enriched-stats.json file.
Confirm enriched-stats.json exists inside your build directory (default: ./storybook-static).
Run Percy with IntelliStory
Run the Percy CLI against your build directory with the --intelli-story flag enabled.
How it works
When IntelliStory runs, it compares your current commit against your last Percy build and snapshots only the stories whose source files changed. Unchanged stories reuse their existing baselines, which lowers your snapshot count and shortens build time.
When IntelliStory cannot determine which stories a change affects, it falls back to snapshotting your full Storybook. See Advanced topics for the conditions that trigger a fallback.
Configuration
You can configure IntelliStory through CLI flags or your percy.yml file. CLI flags override percy.yml values.
| CLI flag |
percy.yml key |
Description |
|---|---|---|
--intelli-story |
storybook.intelliStory.enabled |
Turns IntelliStory on. Boolean, defaults to false. |
--intelli-story-baseline |
storybook.intelliStory.baseline |
Sets the Git commit SHA or branch name to diff the current build against. String, auto-predicted by Percy when unset. |
--intelli-story-untraced |
storybook.intelliStory.untraced |
Excludes the matching file patterns from change detection, for files that change often but do not affect rendered output. Glob array. |
--intelli-story-bail-on-changes |
storybook.intelliStory.bailOnChanges |
Forces a full build when the matching files change, for global styles or design tokens that affect every story. Glob array. |
--intelli-story-stats-file |
storybook.intelliStory.statsFile |
Sets the stats file name to read from the Storybook build directory. String, defaults to enriched-stats.json. |
--intelli-story-trace |
storybook.intelliStory.trace |
Emits an HTML file that visualizes the dependency graph IntelliStory built, for debugging. Boolean, defaults to false. |
--intelli-story-fail-build-on-failure |
storybook.intelliStory.failBuildOnFailure |
Fails the build on an IntelliStory error instead of falling back to a full snapshot set. Boolean, defaults to false. |
Example: percy.yml
Example: CI with an explicit baseline
For branches without a prior Percy build, set the baseline explicitly. IntelliStory then uses this commit or branch as the reference for change detection.
Advanced topics
In some situations, IntelliStory cannot determine which stories a change affects. In these cases, it falls back to snapshotting your full Storybook, logs a warning, and continues the build. To fail the build instead, pass --intelli-story-fail-build-on-failure on the CLI, or set storybook.intelliStory.failBuildOnFailure: true in your percy.yml. The following sections group the conditions that trigger a full-build fallback.
Setup and configuration
IntelliStory falls back when it cannot read a valid stats file from your Storybook build directory.
| Trigger | What it means | How to fix |
|---|---|---|
Percy was run against a URL or in start mode |
IntelliStory requires the Storybook build directory so it can read enriched-stats.json. |
Run percy storybook ./storybook-static instead of pointing Percy to a URL. |
statsFile is not a valid .json filename |
The configured stats filename contains path segments or is not a .json file. |
Use a flat filename like enriched-stats.json. The default is correct for most setups. |
| Stats file not found in the build directory | The bundler plugin did not emit the stats file. | Confirm bundler-plugin-smartsnap is configured in .storybook/main.ts and rebuild Storybook. |
| Stats file exists but is not a regular file | A directory or symlink with that name was found instead of a file. | Remove the conflicting entry and rebuild Storybook. |
Stats file is missing a top-level buildId
|
The stats file is stale or was partially written. | Rebuild Storybook to regenerate enriched-stats.json. |
Baseline detection
IntelliStory falls back when it cannot establish a baseline commit to diff your current build against.
| Trigger | What it means | How to fix |
|---|---|---|
| Percy could not predict a base build commit and no baseline was set | Common on a first IntelliStory run or when project history is too sparse. | Set --intelli-story-baseline=<commit-or-branch> to give IntelliStory an explicit baseline. |
No files changed between HEAD and the base build commit |
Your working tree matches the baseline exactly, so there is nothing to diff. | No action needed. Percy runs the full set this once. |
Storybook-wide changes
IntelliStory falls back when a change can affect every story, so it snapshots the full set to stay safe.
| Trigger | What it means | How to fix |
|---|---|---|
A file inside .storybook/ changed |
Changes to preview.js, addons, or manager wiring can affect every story’s render. |
No action needed. This is the safe default. To run IntelliStory anyway, ensure your .storybook/ changes are isolated to files declared in untraced. |
Dependency and lockfile changes
IntelliStory falls back when it cannot resolve how a package.json or lockfile change maps to affected stories.
| Trigger | What it means | How to fix |
|---|---|---|
| Manifest changes span multiple directories | Multiple workspace package.json files changed in a monorepo. Per-workspace resolution is not yet supported. |
Split the build per workspace, or accept the full-build fallback for cross-workspace dependency changes. |
| Manifest changed but no lockfile is present | IntelliStory needs a lockfile to resolve the dependency impact of a package.json change. |
Commit a lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml) next to the changed package.json. |
| Multiple lockfiles exist in the same directory | IntelliStory cannot pick a canonical lockfile when two coexist. | Remove the unused lockfile so only one remains. |
| Lockfile not present at the base ref | First IntelliStory run, the lockfile was renamed, or the package is new. | No action needed. Subsequent builds will have a baseline lockfile. |
snyk-nodejs-lockfile-parser is not available |
The optional dependency was not installed, usually because the Percy CLI was installed under a Node version lesser than v18. | Reinstall the Percy CLI on Node v18 or later. |
User-configured and runtime
IntelliStory falls back on a setting in your own configuration or on a runtime error during graph processing.
| Trigger | What it means | How to fix |
|---|---|---|
A changed file matched a bailOnChanges glob |
Working as configured. You explicitly told IntelliStory to fall back when these files change. | No action needed. Remove the pattern from bailOnChanges if you no longer want a full build for that file. |
| Graph generation did not complete | The Percy API took too long or returned a failure status during graph processing. | Retry the build. If the issue persists, contact Percy support. |
FAQs
This section explains the most common IntelliStory log messages and how to resolve them.
Why does Percy log snyk-nodejs-lockfile-parser is not available?
This message appears when the Percy CLI was installed on a Node version below 18. Reinstall the Percy CLI under Node.js v18 or later.
Why does Percy log stats file "enriched-stats.json" not found?
Your Storybook build did not emit the stats file. Confirm bundler-plugin-smartsnap is wired into .storybook/main.ts per the bundler-plugin-smartsnap README, then rebuild Storybook before running Percy.
Why does Percy log no snapshots have importPath set?
This message means IntelliStory could not map your stories back to their source files. Confirm you are on Storybook v7 or later. On older versions, IntelliStory relies on parameters.fileName, which is not always populated.
Why did IntelliStory fall back to a full snapshot set?
Check your Percy build log for an IntelliStory: message. The message tells you which bail condition triggered. See Advanced topics for what each one means.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!