Install Reg-suit in your Next.js project with npm, run reg-suit init to create its configuration, and then run reg-suit run after a separate screenshot process has saved images to the configured directory. Reg-suit compares images; it does not capture your Next.js pages for you.
Before you install
Check your project’s Node.js version against the current Next.js requirement: the Next.js App Router and Pages Router installation documentation both state a minimum of Node.js 20.9. This is a Next.js requirement, not a separately verified Reg-suit minimum. The reviewed documentation does not establish a specific Reg-suit/Next.js compatibility matrix.
As an Amazon Associate I earn from qualifying purchases.
Reg-suit describes itself in its package documentation as “a command line interface for visual regression testing.” Its published package page reports version 0.14.5; check the package and plugin documentation for current versions before pinning version-sensitive dependencies or copying old CI examples.
Recommended Free Tools
Install and initialize Reg-suit
The documented quick start installs the CLI globally, initializes it in the project, and runs it:
#1 Best Overall
npm install -g reg-suit
cd path-to-your-project
reg-suit init
reg-suit run- Open a terminal and install the CLI with
npm install -g reg-suit. - Change to your Next.js project root—the directory where you want
regconfig.jsonto live. - Run
reg-suit init. Follow its prompts to set up Reg-suit and select any needed plugins. The initializer uses npm by default; the package documentation also describes yarn and yarn workspaces options. - Review the generated
regconfig.json, especially the image directory and plugin settings. - Capture the app’s pages with your chosen browser or screenshot tool, save the resulting images in the configured actual-image directory, and run
reg-suit run.
If you do not want a global installation, Reg-suit’s CI examples use local invocation with npx reg-suit run. Install the CLI as a project dependency using the package manager used by your repository, then invoke it through npx.
Capture screenshots separately
Reg-suit needs image files to compare. It is not a Next.js plugin and does not start the application, navigate routes, or create screenshots. Your capture toolchain must start or access the app, visit the target pages, and put images into the directory named by core.actualDir.
That separation is useful: teams can choose a browser automation or screenshot workflow that fits their app, while Reg-suit handles the baseline and visual comparison stages. Make sure the capture step finishes successfully before invoking Reg-suit; an empty or misplaced image directory cannot provide the intended visual checks.
Configure regconfig.json and image directories
The project-root regconfig.json holds Reg-suit’s core settings and selected plugins. In the package documentation’s example, core.actualDir points to the directory containing the images to compare, and workingDir defaults to .reg. Add that working directory to .gitignore, as the README recommends.
Use the actual directory name created by your screenshot step; the capture process and core.actualDir must agree. Do not assume a particular generated config is correct without checking it, particularly if you have changed the location or naming of screenshots.
Choose baseline, storage, and notification plugins
Plugins determine how a comparison is identified, where its expected images and reports are persisted, and whether anyone is notified. You do not need to configure every plugin merely to perform a local setup.
| Decision | Documented choices | What it affects |
|---|---|---|
| Snapshot key | Git-hash key generator or simple key generator | How Reg-suit identifies the baseline set to use. |
| Snapshot and report publishing | S3 or Google Cloud Storage publisher plugins | Whether baseline images and reports are persisted remotely for team or CI workflows. |
| Notifications | Integrations named in the README include GitHub, GitLab, Slack, and Chatwork | Where results are sent after a run. |
Plugin options belong in the plugins object in regconfig.json. Use only the plugins your workflow needs, and consult the current plugin documentation for exact option names and package versions. The package page’s README names these integrations, but does not establish that every historical setup snippet remains current.
Run Reg-suit locally
Once screenshots exist in core.actualDir, run:
reg-suit runThe documented run operation combines expected-image synchronization, comparison, publishing, and optional notification. If you only want to compare locally, distinguish that goal from the full run-and-publish workflow: remote storage and notifications are plugin choices, not prerequisites for every local setup. Check the current CLI documentation for the appropriate command and configuration for a compare-only workflow.
Best Value
Run Reg-suit in CI
Reg-suit is a CLI that can run in CI; it does not require a Next.js-specific integration. A typical job installs project dependencies, builds or starts the app as needed by your screenshot tool, generates the images, and then invokes Reg-suit. The package documentation demonstrates npx reg-suit run in CI examples.
- Check out the repository and ensure the job has the Git history required by your configuration.
- Install dependencies and run the application or preview server required by your capture step.
- Capture the same routes and states consistently, saving images to
core.actualDir. - Make credentials for any selected storage or notification plugins available as protected CI environment variables; the README documents environment-value substitution in plugin configuration.
- Run
npx reg-suit runand inspect the resulting comparison and any configured report or notification.
If you use reg-keygen-git-hash-plugin, the README says it needs the current branch name to identify the base commit. Shallow history or a detached HEAD can leave it without the information it needs; adjust checkout depth or branch metadata for your CI provider, following the plugin’s documented detached-HEAD workaround.
Troubleshoot common setup problems
- Next.js refuses to start or install: verify Node.js is at least 20.9, the minimum stated in the reviewed Next.js installation docs.
- Reg-suit finds no actual images: confirm the capture step ran and that its output directory matches
core.actualDirinregconfig.json. - CI cannot identify a Git baseline: with the Git-hash key generator, provide usable branch history and branch information; shallow checkouts and detached HEAD states may need correction.
- Publishing or notifications fail: verify that the selected plugin is configured, the required CI credentials are present, and environment substitutions resolve to non-empty values.
- A README command or plugin option does not work as written: check the installed Reg-suit and plugin versions against their current documentation. The package page reports version 0.14.5, and not every listed example is established as current.
- You only wanted a local comparison: review whether your setup is invoking the full synchronization, publishing, and notification flow; remove remote publisher or notifier configuration if it is unnecessary for your intended workflow.
Or skip the browser setup
Reg-suit still needs an image-producing step. If you would rather request a website screenshot through an API, ScreenshotNeo returns an image or PDF from one GET request. For example, save a screenshot as WebP:
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners are accepted and removed before capture, along with supported consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server provides screenshot tools for AI agents. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
