# @percy/sdk-utils

> Common JavaScript SDK utils

Latest version **1.32.10** (published 2026-09-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @percy/sdk-utils
pnpm add @percy/sdk-utils
yarn add @percy/sdk-utils
bun add @percy/sdk-utils
```

## Health

**Score 60/100 (C)** — status: active.

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

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.32.10 |
| Published | 2026-09-17 |
| First published | 2020-10-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=14 |
| Dependencies | 1 |
| Unpacked size | 82.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 86 |
| Maintainers | percy-admin |

## Links

- npm: https://www.npmjs.com/package/@percy/sdk-utils
- 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/sdk-utils

## Dependencies (1)

- [pac-proxy-agent](https://npm.io/package/pac-proxy-agent.md) ^7.0.2

## Recent versions

- 1.32.10 (latest) — 2026-09-17
- 1.32.10-beta.1 (beta) — 2026-09-11
- 1.31.15-alpha.0 (alpha) — 2026-05-21
- 1.32.10-beta.0 — 2026-09-08
- 1.32.9 — 2026-09-08
- 1.32.9-beta.1 — 2026-09-08
- 1.32.9-beta.0 — 2026-09-07
- 1.32.8 — 2026-09-03
- 1.32.8-beta.5 — 2026-09-01
- 1.32.8-beta.4 — 2026-08-31
- 1.32.8-beta.3 — 2026-08-27
- 1.32.8-beta.2 — 2026-08-27
- 1.32.8-beta.1 — 2026-08-25
- 1.32.8-beta.0 — 2026-08-24
- 1.32.7 — 2026-08-20
- … 364 more at https://npm.io/package/@percy/sdk-utils/versions

## README

# @percy/sdk-utils

Common JavaScript SDK utils

- [Usage](#usage)
  - [`logger()`](#loggerdebug)
  - [`percy`](#percy)
  - [`isPercyEnabled()`](#ispercyenabled)
  - [`postSnapshot()`](#postsnapshot)
  - [`request`](#requesturl-options)

## Usage

### `logger([debug])`

This function is a direct export of [`@percy/logger`](./packages/logger).

### `percy`

This object contains information about the local Percy environment and is updated when
[`isPercyEnabled`](#ispercyenabled) is called for the first time.

``` js
import { percy } from '@percy/sdk-utils'

// reflects/updates process.env.PERCY_SERVER_ADDRESS
percy.address === 'http://localhost:5338'

// updated after isPercyEnabled() is called
percy.enabled === true|false
percy.version.major === 1
percy.version.minor === 2
percy.version.patch === 3
percy.version.toString() === '1.2.3'
percy.config === {} // .percy.yml config

// updated after fetchPercyDOM() is called
percy.domScript === fs.readFile(require.resolve('@percy/dom'))
```

### `isPercyEnabled()`

Returns `true` or `false` if the Percy CLI API server is running. Calls the server's `/healthcheck`
endpoint and populates information for the [`percy`](#percy) property. The result of this function
is cached and subsequent calls will return the first cached result. If the healthcheck fails, will
log a message unless the CLI loglevel is `quiet` or `silent`.

``` js
import { isPercyEnabled } from '@percy/sdk-utils'

// CLI API not running
await isPercyEnabled() === false
// [percy] Percy is not running, disabling snapshots

// CLI API is running
await isPercyEnabled() === true
```

### `fetchPercyDOM()`

Fetches and returns the `@percy/dom` serialization script hosted by the local Percy API server. The
resulting string can be evaluated within a browser context to add the `PercyDOM.serialize` function
to the global scope. Subsequent calls return the first cached result.

``` js
import { fetchPercyDOM } from '@percy/sdk-utils'

let script = await fetchPercyDOM()

// selenium-webdriver
driver.executeScript(script)
// webdriverio
browser.execute(script)
// puppeteer
page.evaluate(script)
// protractor
browser.executeScript(script)
// etc...
```

### `postSnapshot(options)`

Posts snapshot options to the local Percy API server.

``` js
import { postSnapshot } from '@percy/sdk-utils'

await postSnapshot({
  // required
  name: 'Snapshot Name',
  url: 'http://localhost:8000/',
  domSnapshot: 'result from PercyDOM.serialize()'
  // optional
  environmentInfo: ['<lib>/<version>', '<lang>/<version>'],
  clientInfo: '<sdk>/<version>',
  widths: [475, 1280],
  minHeight: 1024,
  enableJavaScript: false,
  requestHeaders: {}
})
```

### `request(url[, options])`

Sends a request to the local Percy API server. Used internally by the other SDK utils.

``` js
import { request } from '@percy/sdk-utils'

await request('/percy/idle')
await request('/percy/stop')
```

#### `request.fetch(url, options)`

The underlying implementation of the `request()` util. For Node environments, `http.request` is
used; for browser environments, `window.fetch` is used. Can be overridden by the SDK's framework to
work around CORS/CSP issues.

The returned object must contain the following normalized properties from the request response:
`status`, `statusText`, `headers`, `body`

``` js
import { request } from '@percy/sdk-utils'

// Cypress SDK example
request.fetch = async function fetch(url, options) {
  options = { url, retryOnNetworkFailure: false, ...options }
  return Cypress.backend('http:request', options)
}
```

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