{"id":16482,"library":"percy-client","title":"Percy Client (Deprecated)","description":"The `percy-client` package was the original JavaScript API client library for Percy, a visual testing and review platform. It provided low-level programmatic access to Percy's API for managing visual builds and snapshots, crucial for integrating automated visual regression testing into CI/CD pipelines. This library allowed developers to create builds, capture DOM snapshots, upload associated resources (like HTML, CSS, and images), and finalize builds directly through code. The package is currently at version 3.9.0, with its last significant update approximately three years ago. It has since entered a maintenance state, receiving only minor dependency updates before being officially deprecated. Its primary differentiation was offering direct API control, which is now handled by the newer `@percy/client` package and the `@percy/cli` ecosystem, which offer a more comprehensive and extensible toolchain for visual testing.","status":"deprecated","version":"3.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/percy/percy-js","tags":["javascript"],"install":[{"cmd":"npm install percy-client","lang":"bash","label":"npm"},{"cmd":"yarn add percy-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add percy-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` was historically common for this package, modern Node.js projects should use ESM `import`. However, this package is deprecated; use `@percy/client` instead.","wrong":"const PercyClient = require('percy-client');","symbol":"PercyClient","correct":"import PercyClient from 'percy-client';"}],"quickstart":{"code":"import PercyClient from 'percy-client';\n\n// Ensure PERCY_TOKEN is set in your environment variables for authentication\n// For example: export PERCY_TOKEN='YOUR_PERCY_PROJECT_TOKEN'\nconst percyToken = process.env.PERCY_TOKEN || '';\n\nconst client = new PercyClient({\n token: percyToken,\n clientInfo: 'my-custom-integration',\n environmentInfo: 'my-node-environment'\n});\n\nasync function runPercyBuildAndSnapshot() {\n if (!percyToken) {\n console.warn('PERCY_TOKEN is not set. Snapshots will be skipped.');\n return;\n }\n\n console.log('Creating a new Percy build...');\n const build = await client.createBuild();\n console.log(`Build created: ${build.attributes['web-url']}`);\n\n console.log('Creating a snapshot...');\n const htmlContent = `\n \n \n My Test Page\n \n

Hello from Percy!

\n

This is a test snapshot.

\n \n \n `;\n const snapshot = await client.createSnapshot(build.id, {\n name: 'Homepage with H1',\n widths: [768, 1280]\n });\n\n // Uploading the HTML content as a resource for the snapshot\n await client.uploadResource(build.id, snapshot.id, {\n resourceUrl: '/', // The URL this resource represents\n mimetype: 'text/html',\n content: Buffer.from(htmlContent)\n });\n\n console.log('Finalizing snapshot...');\n await client.finalizeSnapshot(snapshot.id);\n\n console.log('Finalizing build...');\n await client.finalizeBuild(build.id);\n console.log('Percy build process completed!');\n}\n\nrunPercyBuildAndSnapshot().catch(error => {\n console.error('An error occurred during Percy process:', error);\n process.exit(1);\n});","lang":"javascript","description":"This quickstart demonstrates how to programmatically create a Percy build, create a snapshot, upload HTML content as a resource, and finalize the snapshot and build using the `percy-client` library. It illustrates the low-level API interaction for visual testing."},"warnings":[{"fix":"Migrate your integration to use `@percy/cli` and `@percy/client`. Refer to the official Percy documentation for migration guides. Start by installing `@percy/cli`: `npm install --save-dev @percy/cli` and then upgrade any Percy SDKs you are using.","message":"This package (`percy-client`) is officially deprecated and no longer actively maintained. Users are strongly advised to migrate to the `@percy/client` package and the `@percy/cli` toolchain for all new and existing Percy integrations. Continued use of `percy-client` may lead to compatibility issues with newer Percy platform features.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade to `percy-client` version 3.2.3 or higher, which updated Buffer usage to remove deprecated constructor syntax. However, the recommended fix is to migrate to the `@percy/client` package as `percy-client` itself is deprecated. [cite: github releases]","message":"Older versions of `percy-client` might use deprecated `Buffer` constructor syntax, which can lead to runtime warnings or errors in newer Node.js environments. [cite: github releases]","severity":"gotcha","affected_versions":"<3.2.3"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Instead of `percy-client`, install `@percy/cli` (`npm install --save-dev @percy/cli`) and `@percy/client` (`npm install @percy/client`). Update your codebase to use the new API, typically by importing `PercyClient` from `@percy/client` or using `percy exec` with a framework-specific SDK.","cause":"Attempting to install or use the deprecated `percy-client` package, which is superseded by a newer, modular architecture.","error":"This package has been deprecated in favor of @percy/client"},{"fix":"Ensure that the `percy-client` or associated SDK is correctly initialized with the necessary context or framework instance as per its specific API requirements. For `percy-webdriverio`, this means passing a WebdriverIO browser instance to its constructor.","cause":"This specific error indicates an attempt to use `percy-client` (or an SDK like `percy-webdriverio` which might have used it internally) without providing the required framework-specific instance (e.g., a WebDriverIO browser object) in its constructor.","error":"Error: A WebdriverIO instance is needed to initialise percy-webdriverio"}],"ecosystem":"npm"}