# @percy/config

> Handles loading and adding options to Percy configuration files. Uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) to load configuration files and [JSON schema](https://json-schema.org/) with [AJV](https://github.com/epoberezkin/ajv) to val

Latest version **1.32.12** (published 2026-10-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install @percy/config
pnpm add @percy/config
yarn add @percy/config
bun add @percy/config
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.32.12 |
| Published | 2026-10-21 |
| First published | 2020-07-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14 |
| Dependencies | 4 |
| Unpacked size | 37.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 87 |
| Maintainers | percy-admin |

## Links

- npm: https://www.npmjs.com/package/@percy/config
- Repository: https://github.com/percy/cli
- Homepage: https://github.com/percy/cli#readme
- Issues: https://github.com/percy/cli/issues
- npm.io page: https://npm.io/package/@percy/config

## Dependencies (4)

- [ajv](https://npm.io/package/ajv.md) ^8.6.2
- [yaml](https://npm.io/package/yaml.md) ^2.0.0
- [cosmiconfig](https://npm.io/package/cosmiconfig.md) ^8.0.0
- [@percy/logger](https://npm.io/package/@percy/logger.md) 1.32.12

## Recent versions

- 1.32.12 (latest) — 2026-10-21
- 1.32.12-beta.4 (beta) — 2026-10-21
- 1.31.15-alpha.0 (alpha) — 2026-05-21
- 1.32.12-beta.3 — 2026-10-16
- 1.32.12-beta.2 — 2026-10-09
- 1.32.12-beta.1 — 2026-10-06
- 1.32.12-beta.0 — 2026-10-01
- 1.32.11 — 2026-09-24
- 1.32.11-beta.2 — 2026-09-22
- 1.32.11-beta.1 — 2026-09-22
- 1.32.11-beta.0 — 2026-09-21
- 1.32.10 — 2026-09-17
- 1.32.10-beta.1 — 2026-09-11
- 1.32.10-beta.0 — 2026-09-08
- 1.32.9 — 2026-09-08
- … 392 more at https://npm.io/package/@percy/config/versions

## README

# @percy/config

Handles loading and adding options to Percy configuration files. Uses
[cosmiconfig](https://github.com/davidtheclark/cosmiconfig) to load configuration files and [JSON
schema](https://json-schema.org/) with [AJV](https://github.com/epoberezkin/ajv) to validate those
configuration files.

- [Loading config files](#loading-config-files)
- [Extending config options](#extending-config-options)

## Loading config files

The `.load()` method will load and validate a configuration file, optionally merging it with any
provided `overrides`. If no `path` is provided, will search for the first supported config found
from the current directory up to the home directory. Configuration files are cached and reused unless
`reload` is `true`.

```js
import PercyConfig from '@percy/config'

// loading is done synchronously
const config = PercyConfig.load(options)
```

#### Options

- `path` — Config file path or directory containing a config file
- `overrides` — Config option overrides
- `reload` — Do not use cached config (**default** `false`)
- `bail` — Return undefined when failing validation (**default** `false`)
- `print` — Print info and error logs (**default** `false`)

#### Supported files

- `"percy"` entry in `package.json`
- `.percyrc` YAML or JSON file
- `.percy.json` JSON file
- `.percy.yaml` or `.percy.yml` YAML file
- `.percy.js` or `percy.config.js` file that exports an object

## Extending config options

The `.addSchema()` function will add a sub-schema to the Percy configuration file which will be
parsed and validated when `PercyConfig.load()` is called. See [JSON
schema](https://json-schema.org/) for possible schema options.

```js
import PercyConfig from '@percy/config'

PercyConfig.addSchema({
  propertyName: JSONSchema
})
```

---
_Source: https://npm.io/package/@percy/config · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._