Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

Covered in this doc

How to integrate Percy into a Gatsby static site


Node 10 or higher
A PERCY_TOKEN. Your token can be found on your Percy project settings page

Environment setup

The first step is to make your PERCY_TOKEN available in your environment. The percy package relies on the PERCY_TOKEN environment variable for authenticating and authorizing access to each project.

On Linux and Mac, run:

$ export PERCY_TOKEN=aaabbbcccdddeeefff

On Windows, run:

$ set PERCY_TOKEN=aaabbbcccdddeeefff


Keep your PERCY_TOKEN secret. Anyone with access to your token can consume your account quota, though they cannot read data.


$ npm install --save @percy/agent gatsby-plugin-percy


// In your gatsby-config.js
module.exports = {
  plugins: [
    // ... your other plugins
// In your gatsby-config.js
// This is an example of all the possible options passed
module.exports = {
  plugins: [
      resolve: `gatsby-plugin-percy`,
      options: {
        files: [`dir/*.html`],
        ignore: [`ignore/*.html*`],
        config: `config/.percy.yaml`,

Once installed, running gatsby build will automatically take snapshots of the pages located in your project's public directory.


Options are not required. Percy searches the current working directory and up for a matching config file. The files and ignore options can be specified within a static-snapshots section of your Percy config file as snapshot-files and ignore-files respectively.

  • files - A single file glob or array of file globs to snapshot within the public directory
  • ignore - A single file glob or array of file globs to ignore within the public directory
  • config - Path to a Percy config file

Updated about a month ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.