How to Install Reg-suit in a Next.js Project

To install Reg-suit in a Next.js project: make sure your Next.js environment uses Node.js 20.9 or newer, install the Reg-suit CLI, run its setup wizard in your project, configure the directory containing screenshots, and then run the comparison. Reg-suit compares images; it does not capture screenshots. You need a separate capture step that writes images into the configured directory.

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

The commands follow the Reg-suit package documentation. The Node.js requirement comes from the current Next.js App Router installation docs and Pages Router installation docs; it is not a separately verified Reg-suit minimum. The docs do not establish a Reg-suit and Next.js version compatibility matrix.

1. Check your project and install the CLI

From your project directory, check that Node.js meets the Next.js requirement and that the existing app starts as expected. Then install Reg-suit globally and initialize it:

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

The setup wizard configures Reg-suit and lets you choose plugins. The package documentation says initialization uses npm by default and also describes yarn and yarn workspaces options. If you prefer not to install the CLI globally, use npx reg-suit to invoke it, as shown in the package’s CI examples.

2. Create screenshots for comparison

Reg-suit needs actual screenshot files to compare. It does not launch Next.js, browse routes, or create those files for you. Use your existing browser automation or screenshot process to:

1. Start the Next.js app in the environment you want to check.
2. Visit the routes and viewport sizes relevant to your test.
3. Save the resulting screenshots in the directory configured as core.actualDir.
4. Use consistent filenames and capture settings across runs so that each new image corresponds to the same page and state as its baseline.

The exact capture command depends on your existing toolchain and is outside Reg-suit’s installation. If the directory is empty, Reg-suit has no actual images to compare. If filenames or viewport conditions change between runs, the comparison may not represent a visual change in the page itself.

3. Configure regconfig.json

After initialization, inspect regconfig.json in the project root. The key setting for the capture handoff is core.actualDir, which points to the directory containing the screenshots produced by your capture step. Reg-suit’s documented default working directory is .reg.

{
  "core": {
    "actualDir": "path/to/your/screenshots",
    "workingDir": ".reg"
  },
  "plugins": {}
}

This is a minimal shape to explain the core paths, not a complete plugin configuration. Keep any fields generated by reg-suit init that your workflow uses; configure plugin-specific values under plugins as directed by the relevant plugin documentation. Add the working directory to .gitignore, as the Reg-suit README recommends.

4. Choose baseline, storage, and notification plugins

Plugins determine where expected images come from and where results go. They are workflow choices rather than prerequisites for every local comparison.

Decision	What it controls	Documented choices
Snapshot key	How Reg-suit identifies the baseline for a run	Git-hash key generator or simple key generator
Snapshot storage and reports	Where baselines and reports are retrieved or persisted	Publisher plugins include S3 and GCS
Notifications	Where a run’s result is sent	Integrations named in the README include GitHub, GitLab, Slack, and Chatwork

Select only what your workflow needs. A local setup can focus on generating screenshots and comparing them. A team workflow may need a shared publisher for baselines and a notifier for review. Reg-suit’s documented run operation can combine expected-image synchronization, comparison, publishing, and optional notification.

The package documentation reports version 0.14.5, and its publication is not recent enough to establish that every plugin listing or CI snippet is current. Check the versions and instructions for the exact packages you install before relying on version-specific plugin configuration.

5. Run a visual comparison

Once your capture step has put images in actualDir and the configuration is in place, run Reg-suit from the project root:

reg-suit run

For a local CLI invocation without a global install, use:

npx reg-suit run

With the selected plugins configured, the documented run flow synchronizes expected images, compares them, publishes results, and notifies configured destinations. If you only want a local comparison, do not assume you need remote storage or notifications: configure the workflow for the local task and consult the CLI and plugin documentation for the operations supported by the versions you use.

6. Run Reg-suit in CI

The same separation applies in CI: your workflow must first start the app and produce screenshots in actualDir, then invoke Reg-suit. A minimal command step after setup is:

npx reg-suit run

If you use the Git-hash key generator, provide usable Git branch history. The Reg-suit README says this plugin needs the current branch name to identify the base commit and describes detached-HEAD workarounds. Shallow checkouts or detached CI checkouts can prevent the plugin from finding the intended comparison base, so adjust checkout history and branch context for your CI provider.

Store credentials for any configured publisher or notifier in CI environment variables or your CI secret store. Reg-suit’s README documents substituting environment values in plugin configuration; avoid committing credentials directly to regconfig.json. Use the CI workflow examples in the package documentation as a starting concept, but verify action versions and plugin instructions rather than copying dated versions unchanged.

7. Keep captures consistent

• Capture the same routes, viewport dimensions, and application state on baseline and candidate runs.
• Wait for the page content your screenshot process depends on before saving each image.
• Make sure generated files land in the configured actualDir.
• Use stable names so a route’s latest image can be matched with its expected image.
• Keep Reg-suit’s working directory out of version control as recommended by its README.
• When using remote storage, check that the CI job has the intended credentials and permissions.

Or skip the browser setup

If you already have screenshots, Reg-suit can compare them. If you need to capture pages as part of a developer workflow, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF; this example saves a WebP response for a page. See the ScreenshotNeo API documentation for request options.

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

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month with no card.

Troubleshooting

Symptom	Likely cause	What to check
No images are compared	The capture step did not write files to core.actualDir, or the configured path is wrong	Inspect the resolved directory and confirm it contains the expected screenshot files before running Reg-suit.
Reg-suit cannot find a baseline	The baseline has not been initialized or synchronized, or the selected key does not identify the intended snapshot	Review the key generator and publisher configuration and confirm the expected snapshot exists for that key.
Git-based baseline selection fails in CI	The checkout lacks branch context or enough history, or CI is using a detached HEAD	Provide the branch name and required history; use the detached-HEAD guidance in the Reg-suit README.
Publishing or notification fails	Plugin settings, credentials, or permissions are missing or no longer match the installed plugin version	Check the plugin’s current configuration instructions and CI secret values. Keep secrets out of committed config.
Images differ on every run	Capture inputs are inconsistent, such as viewport, route state, or timing	Make the capture process use stable routes, dimensions, and page state before writing images.
reg-suit is not found	The CLI is not installed globally or its executable directory is not on PATH	Use npx reg-suit run or correct the global npm executable path.
Initialization offers unexpected plugin options	Package and plugin versions or setup instructions may differ from the older README examples	Check the versions currently installed and follow the matching package documentation.

Performance, reliability, and cost

Reg-suit’s work depends on the number and size of screenshots and on the configured baseline storage and notification steps. Keep the capture set focused on pages and states that matter, and avoid needlessly duplicating screenshots. The research sources establish no benchmark or fixed runtime, so measure your own CI workflow if execution time is a concern.

For reliability, treat screenshot creation, baseline retrieval, image comparison, and publishing as distinct stages when diagnosing a failed job. A successful Reg-suit command cannot compensate for a capture process that produced missing or inconsistent files. Remote publishers add credential and service configuration that a local-only workflow does not require.

The cited sources do not establish Reg-suit pricing or a compatibility guarantee. The documented workflow is based on npm packages and whichever optional storage and notification services you configure; account for those services under their own terms and pricing.

FAQ

Does Reg-suit work with both Next.js routers?

Reg-suit is a CLI that compares supplied images, so its workflow is not tied to a Next.js router. The current Next.js installation documentation for both App Router and Pages Router states the Node.js 20.9 minimum.

Does Reg-suit take screenshots of Next.js pages?

No. You need a separate capture tool or script to create the images that Reg-suit compares.

Do I need S3 or GCS to use Reg-suit?

No. They are documented publisher choices for workflows that need remote persistence. Choose storage and notification plugins to fit your review process.

Can I run it without a global install?

Yes. The package documentation shows npx reg-suit run in CI examples.

Sources

• Reg-suit package documentation for installation, initialization, configuration, plugins, and CI guidance.
• Next.js App Router installation and Pages Router installation for the framework’s Node.js requirement.