Sign in or start for free

Global SDK configuration

Suggest Edits

👍

Covered in this doc

Global configuration options for responsive widths and minimum height

🚧

New CLI configuration documentation

Documentation for the new @percy/cli package is located on this page.

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).
  • enable-javascript: A boolean that enables JavaScript for all snapshots in the project. This may cause side-effects like animations or redirects making your snapshots less reliable.

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.
  • cache-responses: Caches successful network responses in asset discovery.
  • 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: 150 # ms
    cache-responses: true  # default
    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": 150,
      "cache-responses": true,
      "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': 150, // ms
      'cache-responses': true,
      '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": 150,
        "cache-responses": true,
        "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!

Updated almost 3 years ago