Workflow:Cypress io Cypress Local Development Environment
| Knowledge Sources | |
|---|---|
| Domains | Developer_Workflow, Monorepo_Development, Build_Systems |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
End-to-end process for setting up and working in the Cypress monorepo local development environment, from cloning the repository through building packages, running the development server, and validating changes with tests.
Description
This workflow covers the contributor experience for developing Cypress itself. The monorepo contains 30+ packages managed with Yarn workspaces, Lerna for versioning, and Nx for task orchestration. The development environment includes Gulp-orchestrated build tasks, Vite dev servers for frontend packages, Webpack builds for the runner and reporter, and GraphQL code generation. Changes are validated through unit tests (Vitest), integration tests, and Cypress-in-Cypress E2E tests.
Key outputs:
- A fully functional local Cypress development build
- Hot-reloading frontend UIs (Launchpad, App) via Vite
- Validated changes via unit, integration, and E2E test suites
- Type-checked TypeScript across all packages
Usage
Execute this workflow when contributing to the Cypress open-source project. This is appropriate for fixing bugs, adding features, or improving existing functionality within the Cypress codebase. Use this when you need to build and test Cypress locally before submitting a pull request.
Execution Steps
Step 1: Clone and Install Dependencies
Clone the Cypress repository and install all dependencies using Yarn. The monorepo uses Yarn workspaces to link internal packages, so a single yarn install at the root resolves all inter-package dependencies. The postinstall script runs environment-specific setup tasks.
Key considerations:
- The .node-version file specifies the required Node.js version (use nvm to match)
- Yarn workspaces hoist shared dependencies to the root node_modules
- The ensure-dependencies script verifies lockfile integrity
- Initial install downloads and links all 30+ workspace packages
Step 2: Build Packages
Build all packages using the Nx-orchestrated build pipeline. Each package has its own build configuration (TypeScript, Vite, Webpack, or Rollup) producing both CommonJS and ESM outputs. Build dependencies are resolved automatically via the Nx task graph.
Key considerations:
- The build script at the root triggers Nx to build all packages in dependency order
- Most packages produce dual CJS/ESM output via separate tsconfig files
- Frontend packages (app, launchpad) build with Vite
- The runner and reporter build with Webpack
- The icons package generates PNG, ICO, and SVG assets
Step 3: Run Development Server
Start the full development environment using yarn dev (gulp dev). This launches multiple concurrent processes: Vite dev servers for the App and Launchpad UIs, Webpack watch builds for the runner and reporter, GraphQL code generation in watch mode, and the Cypress server in development mode.
Key considerations:
- The gulp dev task kills any existing Cypress processes before starting
- Frontend Vite servers provide hot module replacement for Vue components
- The codegen task generates GraphQL types and barrel files automatically
- The development Cypress binary runs from the local source, not a production install
Step 4: Make and Verify Code Changes
Edit source code in the relevant packages. TypeScript provides type checking across the monorepo. Changes to frontend packages are reflected immediately via HMR. Changes to server-side packages may require a restart of the development server.
Key considerations:
- The shared tsconfig base provides consistent TypeScript settings
- GraphQL schema changes require regenerating types via the codegen task
- Changes to the driver package require a Webpack rebuild
- ESLint validates code style using the shared eslint-config package
Step 5: Run Tests
Validate changes by running the appropriate test suite. Unit tests use Vitest (migrating from Mocha) with each package having its own test configuration. Integration tests run within packages. E2E tests use Cypress-in-Cypress to test the Cypress UI itself.
Key considerations:
- Unit tests: yarn test within the specific package directory
- Integration tests: yarn test-integration in the server package
- E2E tests: cypress open within packages/app or packages/launchpad
- The type_check script runs tsc --noEmit across all packages
- System tests validate the complete build in Docker containers
Step 6: Submit Changes
Stage changes, commit with a conventional commit message, and submit a pull request. The CI pipeline (CircleCI) runs the full test suite including cross-platform builds and system tests. The PR template guides contributors through required information.
Key considerations:
- Conventional commit messages (fix:, feat:, etc.) drive automated changelog generation
- The CI pipeline runs unit tests, type checking, linting, and system tests
- Percy visual regression tests compare UI screenshots against baselines
- Pull requests require review from the Cypress team before merging