How to Build and Test React Apps with Nx and Cypress
Configure Cypress end-to-end and component tests in an Nx React workspace, run them locally and in CI, and fix common setup problems.
To test a React app in an Nx workspace with Cypress, choose the test layer you need: use Nx’s Cypress configuration generator for end-to-end (E2E) tests, and its React component-testing generator for isolated component tests. For E2E, run nx g @nx/cypress:configuration --project=your-app-name, then nx e2e your-e2e-project. For component tests, run nx g @nx/react:cypress-component-configuration --project=your-project, then nx component-test your-project. Replace placeholders with the project names in your workspace. See the Nx Cypress guide and React generator documentation.
1. Choose E2E tests, component tests, or both
E2E tests exercise an application flow through the configured app URL or a server target. They fit checks that cross routes, application state, and user-visible behavior. Component tests focus Cypress on React components with a dedicated component setup. Nx provides separate generators and targets for these workflows.
| Question | E2E | Component |
|---|---|---|
| What is under test? | An app flow through the configured application | A React component and its behavior |
| Setup generator | @nx/cypress:configuration |
@nx/react:cypress-component-configuration |
| Run target | nx e2e <e2e-project> |
nx component-test <react-project> |
| Server setup | Use the configured application server or base URL | Cypress creates its component dev server; generated Nx target uses skipServe: true |
You can configure both. They answer different questions and have different server setup. The best choice depends on what behavior you need to verify and how the workspace is configured.
2. Add Cypress E2E testing to an Nx React app
Generate the configuration
nx g @nx/cypress:configuration --project=my-react-appUse the actual Nx project name, which may differ from the directory or package name. The generator configures an E2E test project and its target. If Cypress should visit an already-running app at a known address instead of using the configured serve target, provide a base URL:
nx g @nx/cypress:configuration --project=my-react-app --baseUrl=http://localhost:4200Choose the URL and port that your app actually uses. When you do not supply --baseUrl, review the generated configuration and target to confirm how the app is served for the test.
Run the generated target
nx e2e my-react-app-e2eThe E2E project name is generated from your workspace and may not match this example. Inspect the project configuration or list workspace projects to find the exact target name. Nx documents headless execution by default.
Run a focused spec or open Cypress
During development, select a spec using the E2E target’s --spec option. For example, adapt the path to a real spec in your repository:
nx e2e my-react-app-e2e --spec=src/e2e/app.cy.tsTo iterate interactively, use the generated target’s open mode or the Cypress open command configured for your project. Check the generated target and installed Nx/Cypress versions for the accepted flags; Nx’s guide also documents watch mode and production configuration.
3. Add Cypress component testing for React
Generate component-test configuration
nx g @nx/react:cypress-component-configuration --project=my-react-appThe generator can infer a build target from the React project. If inference selects the wrong target or cannot find one, pass the intended target explicitly:
nx g @nx/react:cypress-component-configuration --project=my-react-app --build-target=my-react-app:buildFor a particular configuration, include it in the target, for example my-react-app:build:production. Use a build target that matches the project’s real bundler and configuration. To have the generator add starter tests for existing components, use --generate-tests:
nx g @nx/react:cypress-component-configuration --project=my-react-app --generate-testsUnderstand skipServe: true
The generated component-test target uses skipServe: true. Cypress owns the component dev server for this workflow, so Nx should not start a separate server target. Nx still uses the selected build target to prepare the Cypress configuration. Keep this distinction in mind if you customize the generated target: removing or changing the setting can cause Nx to try to serve the app in a way component testing does not expect. See the Nx Cypress executor documentation.
Run component tests
nx component-test my-react-appFor a single component spec, use the component-test target’s --spec option with a path that exists in your project. The generated target and installed versions determine the available options; inspect them before copying flags from another workspace.
4. Write tests that fit the target
Keep E2E specs focused on meaningful app journeys, such as a route loading and a user completing a key action. Use component specs to exercise a component’s states and responses without making every isolated behavior depend on the full application flow. The exact test commands and configuration depend on the Cypress files and targets generated in your workspace.
Check these details when adding or moving specs:
- The file path matches the configured Cypress spec pattern.
- The E2E project points to the intended application URL or serve target.
- Component tests use the React project and the intended build target.
- Tests do not depend on an assumed port, environment variable, or service that CI does not provide.
5. Run locally and in CI
A practical workflow is to run one changed spec while editing, use watch or interactive mode to diagnose behavior, and then run the full Nx target before merging. In CI, invoke the same E2E and component-test targets so Nx can apply the workspace’s task configuration.
The Nx Cypress plugin documents inferred target names for E2E and component testing, task caching, and tracking Cypress screenshot and video outputs. These capabilities depend on the plugin and workspace configuration. Review the project’s actual target names and outputs rather than assuming every workspace uses the same defaults.
For CI task splitting of E2E tests, Nx documents setting ciWebServerCommand in cypress.config.ts. Configure it for the server command and environment your CI job actually uses. Do not assume that local server startup or a developer’s base URL is available in a clean CI worker. See the Nx guide for Cypress workflows.
6. Configuration choices and edge cases
Project names and inferred targets
Nx commands address project names in the workspace graph, not necessarily folder names. A generated E2E project commonly has a separate name from the React app. Confirm the generated target before putting it into scripts or CI.
Base URL versus serving the app
Use --baseUrl when the test should target a URL you manage separately, such as an app started by another process. Ensure the app is reachable before Cypress starts. If you want Nx’s configured target to handle serving, review the generated E2E configuration rather than supplying an unrelated URL.
Build target and bundler
Component setup relies on the React project’s build configuration. If the workspace has multiple build targets or configurations, specify the correct one. A target name that exists but uses an incompatible setup can still lead to Cypress configuration or compilation problems.
Version and repository differences
Generator flags, inferred targets, and bundler behavior can vary with installed Nx and Cypress versions. Before applying a command, check the workspace’s package versions and run the generator’s help or consult the documentation matching those versions. The available documentation does not establish one compatibility matrix for every combination.
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Nx says the project cannot be found | The command uses a directory name or guessed project name | Use the exact app or E2E project name registered in the Nx workspace. |
| E2E test cannot load the page | The configured base URL is wrong, or the app server is not running or not reachable | Check the URL and port. Start the app when using an external base URL, or review the generated serve target. |
| A spec is not found | The --spec path does not match a file or the configured spec pattern |
Use a repository-relative path to an existing spec and check Cypress configuration. |
| Component generator cannot infer a build target | The project has no unambiguous build target | Pass --build-target=project:target, adding a configuration when needed. |
| Component test tries to start an unexpected server | The generated component-test target was customized and no longer has skipServe: true |
Restore the generated setting and let Cypress own its component dev server. |
| Component test fails during bundling | The selected build target or bundler setup does not match the app | Choose the React project’s correct build target and compare the generated Cypress configuration with the installed tool versions. |
| Works locally, fails in CI | CI lacks the local server, environment, or URL assumed by the spec | Configure the CI server command and environment explicitly; for task splitting, review ciWebServerCommand in cypress.config.ts. |
| Expected Nx target name is unavailable | Project configuration or plugin inference differs from the example | Inspect generated project configuration and installed Nx plugin setup, then run the target that exists. |
8. Performance, reliability, and cost
There is no single runtime or speed improvement that applies to all Nx and Cypress workspaces. Keep local iteration focused with a spec selection or watch workflow; run the full target in CI. Nx documents caching for Cypress E2E and component-test tasks, but whether a task is reusable depends on its declared inputs, outputs, and task configuration. Make sure tests that rely on changing external state are represented correctly in that configuration.
For reliable CI runs, make the app startup command, base URL, environment, and required services explicit. Nx documents CI splitting support with a configured ciWebServerCommand; the exact setup depends on the repository and CI environment. Cypress and Nx are software dependencies, so account for their versions and CI execution resources in your project’s own cost planning; the research sources provide no universal runtime or cost figures.
9. Or skip the browser setup
If the goal is to capture a rendered page for a visual reference or artifact rather than exercise app behavior, ScreenshotNeo offers a website screenshot API and MCP server. It does not replace Cypress tests. One GET request returns an image or PDF; this example saves a WebP screenshot of your deployed app. Read the ScreenshotNeo API documentation for options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://your-app.example -o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. 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 per month with no card; paid plans start at $5 for 3,000. Sign up for free and capture 1,000 screenshots a month with no card.
10. FAQ
Can I use E2E and component tests in the same Nx app?
Yes. They have separate generators and targets, so configure and run each workflow you need.
Does component testing replace E2E testing?
No. Component tests focus on component behavior; E2E tests exercise flows through the configured application.
Why does the component target need a build target if Cypress starts its own server?
Nx uses the build target to prepare Cypress configuration. Cypress owns the component dev server, which is why the generated target uses skipServe: true.
Can I use ScreenshotNeo to verify that a React interaction works?
No. It captures a rendered page; use Cypress to assert interactive behavior and application flows.
