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!

Global SDK configuration

Covered in this doc

Global configuration options for responsive widths and minimum height

Percy SDKs can be configured by using a configuration file. To quickly get started, create a .percy.yml file in your project's root directory (or wherever percy exec -- is run from). This config file allows you to globally set configuration options for each build.

A common use case is configuring all snapshots in a build to capture the same widths. You can do so with the following:

version: 1
snapshot:
  widths: [375, 1280, 1920]

After saving the configuration file, running percy exec -- should automatically detect the file and use the specified options for all snapshots in the build!

Configuration files

Percy SDKs can be configured by using a configuration file, or by adding a "percy" entry to your package.json. Percy will look for the following configs, in order, in the current working directory:

  • a "percy" property in package.json
  • a JSON or YAML, extensionless .percyrc file
  • a .percy.* file with the extensions .json, .yaml, .yml, or .js.
  • a percy.config.js CommonJS module

Failing to find a config in the current directory, Percy will continue to search up the directory tree, checking for each of these configs in each directory, until it finds some acceptable configuration (or hits the home directory).

You can also specify the path directly to a config file by passing a --config or -c option to the percy exec command:

$ percy exec --config ./configs/percy.conf.yml -- ...

For versions of @percy/agent prior to 0.17.x, Percy will only ever look for a .percy.yml file in the current working directory.

All options

We currently support for the following configuration options:

snapshot

  • widths: an array of numbers, in pixels, representing the widths you'd like to capture for each snapshot. Default: [375, 1280]
  • min-height: a number specifying the minimum height in pixels each snapshot should be. Default: 1024
  • percy-css: A string containing Percy specific CSS that will be applied to each snapshot (per-snapshot Percy CSS is concatenated to the end of this value).

static-snapshots

  • path: The default directory path for your static sites built output
  • base-url: If your static files will be hosted in a subdirectory, instead of the web server's root path, set that subdirectory with this flag. Default: /
  • snapshot-files: Glob or comma-seperated string of globs for matching the files and directories to snapshot. Default: **/*.html,**/*.htm
  • ignore-files: Glob or comma-separated string of globs for matching the files and directories to ignore.

agent

asset-discovery:

  • allowed-hostnames: An array of additional hostnames to save asset contents from. By default Percy only captures assets from the hostname that the snapshot was taken on.
  • request-headers: An object containing HTTP headers to be sent for each request made during asset discovery.
  • network-idle-timeout: The amount of time where the snapshotted page has had zero network requests (in milliseconds). Once this has been reached, asset discovery closes.
  • page-pool-size-min: The minimum number of puppeteer pages used for asset discovery
  • page-pool-size-max: The maximum number of puppeteer pages used for asset discovery

A complete config

version: 1
snapshot:
  widths: [375, 1280]
  min-height: 1024 # px
  percy-css: |
    iframe {
      display: none;
    }
static-snapshots:
  path: _site/
  base-url: /blog/
  snapshot-files: '**/*.html'
  ignore-files: '**/*.htm'
agent:
  asset-discovery:
    allowed-hostnames:
      - cdn.example.com
    request-headers:
      Authorization: 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='
    network-idle-timeout: 50 # ms
    page-pool-size-min: 5 # pages
    page-pool-size-max: 20 # pages
{
  "version": 1,
  "snapshot": {
    "widths": [375, 1280],
    "min-height": 1024,
    "percy-css": "iframe { display: none; }"
  },
  "static-snapshots": {
    "path": "_site/",
    "base-url": "/blog/",
    "snapshot-files": "**/*.html",
    "ignore-files": "**/*.htm"
  },
  "agent": {
    "asset-discovery": {
      "allowed-hostnames": [
        "cdn.example.com"
      ],
      "request-headers": {
        "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" 
      },
      "network-idle-timeout": 50,
      "page-pool-size-min": 5,
      "page-pool-size-max": 20
    }
  }
}
module.exports = {
  'version': 1,
  'snapshot': {
    'widths': [375, 1280],
    'min-height': 1024, // px
    'percy-css': `
      iframe {
        display: none;
      }`
  },
  'static-snapshots': {
    'path': '_site/',
    'base-url': '/blog/',
    'snapshot-files': '**/*.html',
    'ignore-files': '**/*.htm'
  },
  'agent': {
    'asset-discovery': {
      'allowed-hostnames': [
        'cdn.example.com'
      ],
      'request-headers': {
        'Authorization': 'Basic ' + (
          Buffer.from('username:password').toString('base64')
        )
      },
      'network-idle-timeout': 50, // ms
      'page-pool-size-min': 5, // pages
      'page-pool-size-max': 20 // pages
    }
  }
};
{
  // ...
  "percy": {
    "version": 1,
    "snapshot": {
      "widths": [375, 1280],
      "min-height": 1024,
      "percy-css": "iframe { display: none; }"
    },
    "static-snapshots": {
      "path": "_site/",
      "base-url": "/blog/",
      "snapshot-files": "**/*.html",
      "ignore-files": "**/*.htm"
    },
    "agent": {
      "asset-discovery": {
        "allowed-hostnames": [
          "cdn.example.com"
        ],
        "request-headers": {
          "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" 
        },
        "network-idle-timeout": 50,
        "page-pool-size-min": 5,
        "page-pool-size-max": 20
      }
    }
  },
  // ...
}

Debugging

If you're having trouble with setting up a configuration file, you can set the LOG_LEVEL=debug environment variable when running Percy. At the top of the debug logs there will be information about which config was found, if any, and which config options were defined.

Keep in mind, Percy will look for configs based on where you're executing the percy command from. If you're still having trouble with setting up a config file, feel free to reach out to support!

Global SDK configuration


Suggested Edits are limited on API Reference Pages

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