How to Set Up the Cypress Monorepo Locally: A Complete Development Guide

Clone the cypress-io/cypress repository, install Node and Yarn 1.x, run yarn and yarn dev, then launch the GUI with yarn start to begin local development.

The Cypress monorepo is a complex, multi-workspace repository containing the desktop application, CLI, internal packages, and extensive tooling. Whether you're fixing bugs, adding features, or exploring how Cypress works under the hood, this guide walks through the complete setup process based on the official source code in cypress-io/cypress.

Cypress Monorepo Architecture

Understanding the repository structure helps navigate development tasks efficiently. The project is organized into distinct workspaces, each with specific responsibilities:

Key Workspaces

• cli/ – The main cypress npm package and component-testing adapters
• packages/ – Core internal packages including driver, server, proxy, rewriter, and launcher
• npm/ – Publicly published npm packages (webpack-dev-server, vite-dev-server, plugins)
• tooling/ – Build tooling for V8 snapshots and packherd
• system-tests/ – Full end-to-end tests running against built Cypress binaries
• scripts/ – Build, release, and CI automation scripts

Each workspace operates under different runtime constraints. The CLI runs on Node, the desktop app on Electron, and the driver in browsers. The Runtime Targets section in [AGENTS.md](https://github.com/cypress-io/cypress/blob/develop/AGENTS.md) documents these constraints in detail.

Prerequisites for Cypress Monorepo Setup

Before running any commands, verify these requirements from the repository source files:

Requirement	Source Location
Node version	Root .node-version file
Yarn 1.x	[AGENTS.md Prerequisites section](https://github.com/cypress-io/cypress/blob/develop/AGENTS.md)
Git	Standard client for cloning

Critical: Cypress requires Yarn 1.x specifically (yarn@1.22.22). Using Yarn 2+ or npm will cause installation failures.

Step-by-Step Cypress Monorepo Installation

Follow this exact sequence to set up the repository locally:

# 1. Clone the repository

git clone https://github.com/cypress-io/cypress.git
cd cypress

# 2. Switch to the required Node version

nvm install
nvm use

# 3. Install dependencies across all workspaces

yarn

# 4. Build the monorepo (recommended after fresh install)

yarn build

# 5. Start development mode with live rebuilds

yarn dev

# 6. Launch the Cypress GUI

yarn start

Command Reference

Command	Purpose	Source
nvm use	Reads .node-version and sets active Node version	.node-version
yarn	Installs workspace dependencies, runs post-install hooks, patches packages, rebuilds native modules	AGENTS.md Prerequisites
yarn build	Full monorepo build via Lerna—compiles TypeScript, creates V8 snapshots, bundles Electron app	AGENTS.md Build section
yarn dev	Watch mode for @packages/app and @packages/launchpad with Vite, launches Electron runner	AGENTS.md Common Commands
yarn start	Opens Cypress Launchpad GUI using dev bundles	AGENTS.md Common Commands

The yarn command is particularly intensive. It rebuilds native modules including better-sqlite3 and generates V8 snapshots. Initial installation may take several minutes.

Running Tests in the Cypress Monorepo

The repository uses both Vitest and Mocha for different test suites. Run tests for specific packages rather than the entire repository:

# Run unit tests for the server package

yarn workspace @packages/server test-unit

# Run Vitest tests for the config package

yarn workspace @packages/config test

# Run end-to-end tests against a sample project

yarn cypress:run -- --project ./system-tests/projects/webpack5_wds4-react --browser chrome --headless

# Run component tests using built-in dev server

yarn cypress:run:ct -- --spec "cypress/component/**/*.spec.ts"

The Testing section in [AGENTS.md](https://github.com/cypress-io/cypress/blob/develop/AGENTS.md) contains the complete command reference.

Common Setup Issues and Solutions

Post-Install Hook Failures

The initial yarn runs extensive post-install scripts. Interrupting this process can corrupt the workspace. If this occurs, simply re-run yarn to resume.

Path-Dependent Test Failures

Tests in @packages/config require the workspace directory to contain the word "cypress". If you cloned into a folder with a different name, these tests fail intentionally. Either rename your folder or skip those specific tests.

Linux/macOS Xvfb Requirements

Headless Electron execution requires an X virtual framebuffer. The repository's Docker image starts Xvfb on DISPLAY=:1 automatically. For local Linux development without a display, install and run Xvfb manually.

Essential Files for Local Development

File	Purpose	Location
.node-version	Exact Node version requirement	Repository root
package.json	Workspace configuration, Lerna scripts	Repository root
AGENTS.md	Monorepo overview, commands, runtime targets	Repository root
guides/README.md	Links to per-package documentation	guides/
packages/app/README.md	Vue-based Launchpad GUI documentation	packages/app/
packages/server/README.md	HTTP server powering test runs	packages/server/
npm/vite-dev-server/README.md	Vite integration for component testing	npm/vite-dev-server/

Summary

• Clone the cypress-io/cypress repository and navigate into it
• Install the exact Node version from .node-version using nvm
• Use Yarn 1.x exclusively—other package managers are unsupported
• Run yarn to install all workspace dependencies and native module rebuilds
• Execute yarn build for full TypeScript compilation and V8 snapshot generation
• Start yarn dev for watch-mode development with live rebuilding
• Launch yarn start to open the Cypress GUI in development mode
• Test selectively using workspace-specific commands rather than monorepo-wide test runs

Frequently Asked Questions

What Node version does the Cypress monorepo require?

The required version is declared in the root .node-version file. Use nvm install and nvm use to automatically switch to this version. The repository tracks specific Node versions for compatibility with Electron and native module compilation.

Can I use npm or Yarn 2+ to install Cypress monorepo dependencies?

No. According to [AGENTS.md](https://github.com/cypress-io/cypress/blob/develop/AGENTS.md), Cypress specifically requires Yarn 1.x (yarn@1.22.22). The workspace configuration, post-install scripts, and native module rebuilds depend on Yarn 1.x behavior. Using alternatives will cause installation and build failures.

How long does the initial yarn install take?

Expect 5–15 minutes depending on hardware. The installation rebuilds native modules including better-sqlite3, applies patches via patch-package, deduplicates dependencies, and generates V8 snapshots. Do not interrupt this process; if corrupted, re-run yarn to recover.

Why do some tests fail if my folder isn't named "cypress"?

The @packages/config test suite contains path-dependent assertions that verify the workspace directory name. This is intentional behavior for testing configuration resolution. Rename your clone folder to "cypress" or exclude those specific tests from your run.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}