How to Install Reg-suit in a React Project

Install Reg-suit in a React project as a development dependency, then run its interactive setup:

npm install -D reg-suit
npx reg-suit init

Reg-suit is a Node.js command-line tool that compares image files. It does not render your React components or take screenshots for you. Your project needs a separate capture step that saves the UI states you want to compare; then configure Reg-suit’s actualDir to point at that image directory. See the Reg-suit repository, npm documentation, and the official Puppeteer demo for the documented workflow and configuration references.

1. Check your React project and install Reg-suit

From the root of the React repository, check that Node.js and npm are available and that the project has a package manifest:

node --version
npm --version
ls package.json

Install Reg-suit locally so the project’s manifest and lockfile record the CLI dependency:

npm install -D reg-suit

Run the initializer through npx:

npx reg-suit init

The initializer is interactive. It installs and configures Reg-suit and can set up plugins. Choose only integrations your workflow needs. A cloud publisher or pull-request notifier is optional; neither should be treated as a prerequisite for installing the CLI. The prompts and available plugin versions can change, so follow the choices shown by the version installed in your project.

The Reg-suit README also documents a global CLI installation:

npm install -g reg-suit
cd path-to-your-project
reg-suit init
reg-suit run

Both installation paths are documented. With a project dependency, use npx reg-suit so the command resolves to the project’s installed version. The global route makes the command available in your shell but does not record Reg-suit in the project’s dependencies.

2. Capture the React UI states you want to compare

Before a comparison can run, produce image files for the target pages, components, or states. Reg-suit compares those supplied images; a React render or component test alone does not create the screenshots.

You can use a browser automation setup such as Puppeteer, or a Storybook-oriented capture setup. The Reg-suit project lists React examples, and its official Puppeteer demo shows browser capture feeding an image directory to Reg-suit. The appropriate capture method depends on how your project serves the UI and selects states.

For a small app, a capture script can open a running local site and save a page image. Install Puppeteer if you choose this route:

npm install -D puppeteer

For example, save this as scripts/capture.mjs. Set APP_URL to the route under test, and make sure that route is already available when the script runs:

import { mkdir } from 'node:fs/promises';
import puppeteer from 'puppeteer';

const appUrl = process.env.APP_URL ?? 'http://localhost:3000';
const outputDir = 'artifacts/screenshots';

await mkdir(outputDir, { recursive: true });
const browser = await puppeteer.launch({ headless: true });

try {
  const page = await browser.newPage({
    viewport: { width: 1440, height: 900 },
    deviceScaleFactor: 1,
  });
  await page.goto(appUrl, { waitUntil: 'networkidle0' });
  await page.screenshot({ path: `${outputDir}/home.png`, fullPage: true });
} finally {
  await browser.close();
}

This is a capture example, not a Reg-suit requirement. Adapt the route, viewport, readiness condition, and output name to your app. For multiple states, capture each state with a stable filename and ensure the page is in the intended state before saving. If your application does not become network-idle because it uses persistent connections, use a meaningful selector or explicit readiness condition in your capture script instead.

Add a script to package.json so local work and CI can use the same capture command. For example:

{
  "scripts": {
    "capture:visual": "node scripts/capture.mjs"
  }
}

Start the app separately using the development or preview command your repository already provides, then run npm run capture:visual. Do not assume every React project uses the same port or start script.

3. Point Reg-suit at the captured images

Reg-suit’s package documentation describes a root-level regconfig.json. Its core section includes actualDir, the directory containing the current images. The working directory is optional and defaults to .reg; image difference thresholds such as thresholdRate or thresholdPixel are also optional.

For the example capture script above, a minimal configuration is:

{
  "core": {
    "actualDir": "artifacts/screenshots"
  }
}

Use the path your own capture script actually writes. If your initializer created or edited configuration, inspect that file and preserve its valid plugin settings when making changes. Do not copy a directory name from an example unless it matches your generated images.

Thresholds affect how image differences are treated. Start with the defaults and inspect the comparison output before loosening a threshold. If you set thresholdRate or thresholdPixel, use the documented configuration accepted by the installed version and choose a value based on the visual changes your project intends to permit. Avoid setting a broad threshold just to make unstable captures pass.

4. Run the comparison and establish a baseline

Once the capture script has generated the configured image files, run Reg-suit from the project root:

npx reg-suit run

Reg-suit needs a reference image set to compare against the current captures. Follow the initialized workflow to publish or retrieve snapshots if you selected a storage plugin, and review the command output to determine whether the run is creating a baseline or reporting changes. The project documents S3 and Google Cloud Storage publisher plugins for snapshot persistence; those integrations are useful when snapshots must survive across machines or CI agents. Keep the baseline creation and update process deliberate so a changed screenshot is not accepted without review.

A practical setup sequence is:

Render the app in a predictable environment and capture the states you care about.
Confirm the generated image paths and set core.actualDir to that directory.
Initialize Reg-suit and configure only the plugins needed for storage or notifications.
Run npx reg-suit run locally and review the baseline and differences.
Use the same capture and comparison commands in CI once the local workflow is repeatable.

5. Optional storage and pull-request notifications

Reg-suit lists publisher plugins for S3 and Google Cloud Storage, as well as notifier plugins for GitHub, GitLab, Slack, and Chatwork. These are extensions to the comparison workflow, not screenshot capture tools. Choose a publisher when your baseline needs to persist outside a developer’s machine or be shared with CI. The cited project documentation establishes that these plugins exist; it does not establish their relative service cost or performance.

For GitHub pull-request reporting, the official notifier guide documents installing reg-notify-github-plugin, preparing the plugin, installing the Reg-suit GitHub App for the repository, and obtaining the repository client ID. Plugin and GitHub App setup can change; follow the current GitHub notifier guide for the exact configuration. Add this only if pull-request reporting is useful to your team.

6. Use the same workflow in CI

Reg-suit can run locally or in CI. To make results comparable, CI should use the same capture script, route list, viewport, and image directory as local runs. A typical job runs in this order:

Install dependencies from the repository’s lockfile.
Start the React app or preview server and wait until it is ready.
Run the project’s capture command.
Run npx reg-suit run.
Publish or report results only if the project has configured the corresponding plugins.

Keep the browser and application environment consistent where practical. Dynamic content, changing fonts, animations, remote data, and different rendering environments can create image differences unrelated to the code change. Stabilize test data and wait for the UI state you intend to capture.

Configuration and workflow choices

Choice	When to use it	What to check
Project dependency or global CLI	Use a project dependency when the CLI should be installed with repository tooling; the README also documents global installation.	Use `npx reg-suit` for the project-installed version.
Capture framework	Use the browser or component capture method that fits your React app; Puppeteer is demonstrated by the official demo.	It must write stable image files for the states you intend to compare.
`core.actualDir`	Set it to the directory containing the current captured images.	Match the exact path and ensure captures run before comparison.
Working directory	Configure only if the default `.reg` directory is unsuitable for your setup.	Check the installed package documentation and generated config.
Difference thresholds	Use optional `thresholdRate` or `thresholdPixel` settings only when the default comparison behavior does not fit.	Understand the chosen threshold and review changes it may permit.
Publisher	Add S3 or GCS publishing when snapshots need persistence across machines or CI.	Configure the appropriate plugin and storage access.
Notifier	Add a supported notifier when the team needs results delivered through GitHub, GitLab, Slack, or Chatwork.	Follow that plugin’s current setup instructions.

Or skip the browser setup

If your goal is to capture a website screenshot rather than build a repeatable React component baseline, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. A single GET request captures a URL as an image or PDF. For a React page that is reachable at a URL, this cURL call saves a WebP screenshot:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Replace the example URL with your deployed or locally reachable page and use your API key. The ScreenshotNeo API docs describe the request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000 screenshots. Sign up for free ScreenshotNeo screenshots.

Complete ScreenshotNeo examples

These examples make the same one-URL request. Replace YOUR_API_KEY and the example target with your page. See the API documentation for capture options and response behavior.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as image_file:
    image_file.write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', image));

Troubleshooting

Symptom	Likely cause	What to do
`reg-suit` is not found	The project dependency is not installed, or a global command is unavailable in the shell.	From the repository root, run `npm install -D reg-suit` and invoke `npx reg-suit`.
The comparison cannot find current images	`actualDir` does not match the capture output path, or the capture step did not run.	Run the capture script first, inspect its output directory, and align `core.actualDir`.
The app screenshot is blank or incomplete	The page was not ready, the URL was wrong, or the browser capture happened before the target UI state loaded.	Confirm the app is serving the expected route. Wait for a stable selector or application-ready signal before capturing.
Every run shows unexpected differences	Content or rendering may vary between runs due to animations, dynamic data, fonts, timing, or viewport differences.	Make test data deterministic, wait for the intended state, and keep capture dimensions and environment consistent.
Local run works but CI does not	CI may not start the app, wait for readiness, or preserve/retrieve the reference snapshots.	Check the CI order: install, start and wait, capture, then compare. Configure a publisher if snapshots must persist across CI agents.
A plugin setup fails	The plugin may not be installed or configured for the repository, or its external app/storage configuration may be incomplete.	Check the plugin’s official instructions and configure only the credentials and repository integration it requires.
Thresholds hide a change you care about	A configured threshold may permit more image difference than intended.	Revisit the optional threshold settings and inspect the reported output before accepting a baseline.

Performance, reliability, and cost

The total workflow time includes rendering the app, capturing each state, and comparing the resulting images. The research sources do not provide a benchmark for React projects, so expect the number of routes, readiness waits, and browser startup to affect runtime, and measure your own CI job. Capture only the states that provide useful regression coverage, and avoid unnecessary repeated browser setup when your capture framework allows reuse.

For reliability, use stable routes and deterministic data, explicitly wait for the content under test, and keep screenshot dimensions consistent. Store baselines where every required local or CI run can access them. S3 and GCS publisher plugins are documented options for persistent storage; storage pricing depends on the provider and usage, and is not specified by the Reg-suit sources here.

Reg-suit is an npm CLI, and its documentation does not establish a product price for installation. Any costs for optional cloud storage or CI depend on the services and usage your project chooses. ScreenshotNeo uses separate usage plans: 1,000 screenshots per month free with no card; Starter is $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. These are API capture plans and do not replace Reg-suit’s baseline comparison workflow.

FAQ

Does Reg-suit install into the React app?

No. It is a Node.js CLI used alongside the app. It compares screenshots produced by a separate capture step.

Do I need a cloud storage plugin to get started?

No. Storage publishers are optional integrations. Add one when your workflow needs snapshots shared or persisted across machines or CI agents.

Can I use Storybook screenshots?

Yes, a Storybook-oriented capture setup is one approach named by the project. Configure Reg-suit to use the directory your capture process produces.

Can ScreenshotNeo replace Reg-suit?

They serve different steps. ScreenshotNeo captures a page from a URL; Reg-suit compares image files against references. A screenshot API alone does not establish the visual regression baseline workflow described here.