Integrate your React Styleguidist tests with Percy

Create a Percy project
Sign in to Percy. In Percy, create a project of the type Web, and then name the project. After the project is created, Percy generates a token. Make a note of it. You have to use it to set your environment variable in the next step.

For details on creating a project, see Create a Percy project.

Set the project token as an environment variable
Run the given command to set PERCY_TOKEN as an environment variable:

To learn about environment variables in Percy, see Percy environment variables.

Install Percy dependencies
In your React Styleguidist project, install the Percy CLI and the Styleguidist plugin:

The @percy/styleguidist plugin requires:

• @percy/cli ^1.31.0
• react-styleguidist >=11 <14
• Node.js >=18

Configure per-component snapshot options
To override the default Percy snapshot behavior for a single component, add a JSON sidecar file alongside the component. Percy reads <Component>.json from the same directory as the component file.

Components without a .json sidecar use the global Percy defaults from your .percy.yml (or .percy.json) configuration.

For the full list of allowlisted sidecar keys, additionalSnapshots options, and dropped-key warning behavior, see React Styleguidist advanced topics.

Run Percy
Build your style guide and run Percy against the output directory:

Percy uploads the snapshots and returns a direct URL to the build on the Percy dashboard.

Congratulations! You have integrated React Styleguidist with Percy. When you run another build with visual changes to your components, Percy takes new snapshots and shows the comparison against the previous run.

For other ways to run Percy, see React Styleguidist advanced topics. It covers pointing at a running dev server, spawning the dev server in one step with percy styleguidist-start, filtering components with --include/--exclude, and driving captures from JavaScript.