React Styleguidist advanced topics

Reference for the @percy/styleguidist CLI plugin, covering CLI commands, per-component JSON sidecar, filtering, programmatic API, and peer-dependency matrix.

On this page, you learn the full surface of @percy/styleguidist: the two CLI commands, the per-component JSON sidecar (including which keys are honored and which are dropped at read time), how filtering and the custom config path work, the programmatic API, .percy.yml integration, and the supported peer-dependency matrix.

CLI commands

The plugin registers two commands on the Percy CLI.

percy styleguidist <url|directory>

Snapshot the components in a Styleguidist build or against a running dev server.

percy styleguidist-start

Spawn the Styleguidist dev server, snapshot all components, then shut the server down. This is useful in CI where you do not want to manage the dev server lifecycle yourself.

Flags

Both commands accept the following flags.

styleguidist-start additionally accepts --port and --host to pass through to the dev server.

Filtering components

Patterns are matched against the component name discovered by React Styleguidist. Both flags can be repeated; an exclude pattern always wins over an include pattern.

Custom config path

By default the plugin looks for styleguide.config.js in the directory you run the command from. Use --config to point at a different file (for example, when your repository keeps multiple style guides side-by-side):

Per-component JSON sidecar

To override Percy’s defaults for a single component, drop a JSON sidecar next to it. The plugin reads <Component>.json from the same directory as the component file.

Allowlisted sidecar keys

Sidecars are read from disk without code review, so the plugin only honors an allowlist of non-executable options. Anything outside the tables below (including code-shaped keys such as execute and domTransformation) is dropped at read time with a warning. For state-mutating snapshots or DOM transformations, configure those options in .percy.yml (which is committed alongside JS code and reviewed) or drive captures through the programmatic API.

additionalSnapshots keys

Each entry in additionalSnapshots accepts the following keys.

Dropped-key warning behavior

If an additionalSnapshots entry’s only differentiator was a stripped (non-allowlisted) key, it would now be an exact duplicate of the base snapshot. In that case, the entire entry is dropped at read time, and the plugin logs a Dropping additionalSnapshot ... warning. Look for these warnings in your CI logs if a snapshot you expected is missing from the Percy build.

Configuration precedence

Per-component sidecars and the global .percy.yml are merged with the following precedence (highest wins):

1. Keys from the component’s <Component>.json sidecar.
2. Keys from .percy.yml under the snapshot (or top-level) section.
3. Percy project-level defaults.

A component without a sidecar uses the global defaults from .percy.yml directly.

Examples

Multiple browsers and widths

Ignore a dynamic region

Additional snapshots at different widths

Programmatic API

For custom orchestration (combining @percy/styleguidist with other Percy plugins, filtering by git diff, or integrating with a test runner), drive captures from JavaScript using @percy/core directly.

takeStyleguidistSnapshots(percy, opts) resolves to { captured, failed, total }. It does not throw on per-component failures. Your code decides whether to fail the build based on the counters.

Options

.percy.yml integration

The Styleguidist plugin honors the standard .percy.yml schema. Anything you set under snapshot applies to every component that does not override it via a sidecar.

Because .percy.yml lives in your repository and goes through code review, use it (rather than a sidecar) when you need executable options such as execute or domTransformation.

Plugin-specific options

The plugin reads the following key from .percy.yml under a top-level styleguidist section.

Peer-dependency matrix

Verify your installed versions before filing an issue:

Troubleshoot

Peer-dependency warning at install time

If npm install warns about an unmet peer for react-styleguidist or @percy/cli, confirm the installed versions fall inside the peer-dependency matrix. The plugin will refuse to load against a Styleguidist major outside the supported range.

“Dropping sidecar key” or “Dropping additionalSnapshot” warnings

These warnings come from the sidecar allowlist. The two common causes:

• You added a key that is not in the allowlisted sidecar keys table. Most often this is execute or domTransformation, both of which are code-shaped and intentionally blocked in sidecars. Move that logic to .percy.yml or to the programmatic API.
• An additionalSnapshots entry only differed from the base snapshot by a stripped key, so it would have produced a duplicate snapshot. Add a name, prefix, suffix, or widths override to make the entry meaningfully different.

Exit codes

When driving captures via the programmatic API, no exit code is set. takeStyleguidistSnapshots returns { captured, failed, total }, and your code decides whether failed > 0 should fail the build.

Related topic

• Integrate with React Styleguidist