For a monorepo with multiple web apps, run Percy’s Cypress SDK inside each app’s test job and provide that job with the Percy project token it should use. Percy’s documented Cypress workflow is to install @percy/cli and @percy/cypress, capture stable named states with cy.percySnapshot(), set PERCY_TOKEN, and run Cypress through npx percy exec -- cypress run. Which apps should share a Percy project is a team design choice; the Percy-authored sources reviewed here do not establish a universal monorepo rule.
How Percy fits a monorepo with multiple web apps
Percy associates test runs with a project token. In a monorepo, make the relationship between each app’s CI job and its intended Percy project explicit. This helps keep visual results attributable to the app that produced them.
Percy’s documented Cypress setup is a supported starting point, not a complete monorepo recipe. Choose where each app’s tests run, how dependencies are installed, and whether apps share a project according to your repository and review process.
Decide whether apps share a Percy project
The available Percy-authored sources do not prescribe how many projects a monorepo should use. Treat the choice as a design decision to verify against the current Percy account and CLI behavior.
| Design | Consider it when | Questions to settle |
|---|---|---|
| Separate project/config boundaries per app | Apps need independent baselines, owners, or review cadence. | Can each CI job access only its app’s intended token? Are build failures and baseline approvals easy to attribute? |
| One shared project | The team intentionally wants a shared visual baseline and approval lifecycle. | Are snapshot names unambiguous? Do reviewers understand which app produced each result? Does the current account and CLI support the workflow you intend? |
These are engineering trade-offs, not Percy-mandated topologies. Also decide whether app jobs run concurrently or whether a test suite is sharded: the sources cited here do not establish current cross-framework or general multi-app parallel-build coordination.
Map apps, tests, and CI ownership
Before changing configuration, document the route from each app to its test command and Percy project. Keep this mapping in app-level CI configuration or another place maintainers can review.
| App | Test framework and command | Base URL or environment | Percy project/token owner | CI job |
|---|---|---|---|---|
| App A | Fill in repository value | Fill in environment URL | Fill in project and secret owner | Fill in job name |
| App B | Fill in repository value | Fill in environment URL | Fill in project and secret owner | Fill in job name |
Replace the example rows with actual repository details. If your apps use different test frameworks, Percy setup may differ by app; the concrete commands below cover Cypress because that is the documented workflow cited here.
Install Percy for a Cypress app
Install Percy’s CLI and Cypress integration in the workspace where your repository’s package-manager conventions make them available to that app:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsnpm install --save-dev @percy/cli @percy/cypressWhere these packages belong depends on your monorepo’s package manager and workspace setup. The cited guide does not specify package-manager-specific hoisting or workspace configuration, so follow your repository’s established dependency policy.
Load the Cypress integration from the support setup used by the app’s tests:
import '@percy/cypress'Then add snapshots to tests that drive the app into states worth reviewing:
cy.percySnapshot('Account settings — loaded');Use meaningful names that distinguish the app, page, and state when project organization alone does not make that context clear. Keep the captured set focused on critical pages or components rather than every possible state.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Make snapshots stable and useful
Visual comparisons are most actionable when captures represent intentional, repeatable UI states. For each app’s visual coverage:
- Control fixture data and other inputs that affect what the page renders.
- Wait for relevant UI activity to settle before taking the snapshot.
- Avoid volatile timestamps, randomized content, and animations that create noisy differences.
- Choose a small, purposeful set of pages and component states that matter to the app.
- Review proposed baseline changes deliberately and approve only visual changes the team intends to accept.
These practices follow Percy’s Cypress guidance. Apply them independently to each app so a shared repository does not turn unrelated UI churn into indistinguishable review work.
Run Cypress through Percy in each app’s CI job
Store the relevant Percy project token in your CI secret manager and expose it to the corresponding app job as PERCY_TOKEN. Do not commit a real token to source control or place it in a checked-in example.
Percy’s documented Cypress command is:
npx percy exec -- cypress runRun it in the app’s appropriate workspace, with that app’s test configuration and intended token. The per-app orchestration is a practical monorepo pattern; it is not a Percy-published universal monorepo recipe.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRank #4
# Example shape only: run from the app workspace with its CI secret configured as PERCY_TOKEN
npx percy exec -- cypress runFor a repository using separate CI jobs, configure each job to select the correct workspace and secret rather than relying on an implicit repository-wide token. If jobs must run simultaneously, or one suite is split across workers, check the current Percy CLI documentation for the supported build and parallelization mechanism before adding coordination flags. A 2020 Percy changelog entry describes more straightforward parallel-build support and global configuration for Ember SDK v2; that release note is specific to that SDK and does not establish current behavior for Cypress, other frameworks, or cross-app builds.
Review builds and baselines by app
Review the Percy build produced by the relevant app job. Make snapshot names recognizable wherever the project layout does not already communicate app ownership, and approve baseline changes only after confirming they reflect intended UI changes.
Keep CI ownership clear as well: a failed capture, unexpected diff, or missing result should be traceable to the app job and token that produced it. This is a configuration and review practice, not a claim about special Percy monorepo semantics.
Cross-host assets: check version-sensitive guidance
If an app loads assets from another hostname, a 2019 Percy changelog describes an agent.asset-discovery.allowed-hostnames setting and says the feature requires @percy/agent v0.10.0 or later. That is a legacy, version-qualified example, not a guarantee that the same syntax is current. Check the current CLI and SDK documentation for your installed versions before relying on it.
Best Value
Troubleshoot common monorepo problems
Results appear under the wrong Percy project
Check which CI secret is exported as PERCY_TOKEN in the app job, and confirm the job is running the intended app’s tests. Keep app-to-token mapping explicit rather than depending on a shared environment default.
The Percy integration is not available to Cypress
Confirm that @percy/cypress is installed where the app’s Cypress run can resolve it and that its support setup imports @percy/cypress. Workspace and hoisting behavior varies by package-manager configuration.
Snapshots are missing or visually noisy
Verify that the test reaches the intended page state before cy.percySnapshot(). Stabilize fixture data, wait for relevant UI activity, and remove volatile content or animation from the captured state where appropriate.
Concurrent jobs or shards do not behave as expected
Do not assume that separate app jobs or test shards automatically form one coordinated Percy build. Check current Percy documentation for the installed CLI/SDK and your account’s integration; the reviewed sources do not establish universal parallel-build behavior for this setup.
Free tools Windows power users keep installed
One-click scans. No signup required.
Assets from a second hostname are absent
Check the current asset-discovery guidance for the installed version. The older changelog example references agent.asset-discovery.allowed-hostnames and @percy/agent v0.10.0+, but its syntax should not be assumed current.
Or skip the browser setup:
If your goal is to capture rendered website screenshots outside Percy’s visual-review workflow, ScreenshotNeo is a website screenshot API and MCP server. It is not a replacement for Percy’s Cypress test integration or baseline-review process.
One GET request can return a screenshot or PDF. For a PNG capture, request an image format explicitly as appropriate to your setup; the basic API call is:
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. ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots per month are free with no card, with paid plans starting at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Recommended Free Tools
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.
