# How to Contribute to the Cypress Monorepo: A Complete Developer's Guide

> Learn how to contribute to the Cypress monorepo. Follow our guide for Nodejs, Yarn, and CircleCI integration to submit your first pull request.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: how-to-guide
- Published: 2026-08-06

---

**Contributing to the Cypress monorepo requires Node.js ≥22.19.0, Yarn 1.22.22, and a workflow involving `yarn dev` for development, semantic-release commit conventions, and CircleCI-validated pull requests targeting the `develop` branch.**

The Cypress project is one of the largest open-source testing monorepos, containing the test runner, desktop Electron application, driver, internal packages, and published npm modules. This guide walks you through the complete contribution workflow based on the official source code in `cypress-io/cypress`.

## Monorepo Structure and Architecture

Understanding the **Cypress monorepo layout** helps you navigate where to make changes. According to [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md), the repository is organized into distinct workspaces:

- **`cli/`** – The public CLI that users install via `npm install cypress`
- **`packages/`** – Core internal packages including the driver, app, and server
- **`npm/`** – Published npm packages (e.g., `@cypress/webpack-preprocessor`)
- **`tooling/`** – Build tooling and shared configurations
- **`system-tests/`** – Full binary-level integration tests
- **`scripts/`** – Automation and release scripts

The build system uses **Yarn 1** for dependency management with **Lerna** orchestrating scripts across workspaces. The entry point `yarn dev` in [`scripts/gulp/gulpfile.ts`](https://github.com/cypress-io/cypress/blob/main/scripts/gulp/gulpfile.ts) builds the Electron GUI and starts Vite for hot-reloading the UI.

## Prerequisites and Environment Setup

Before contributing to the Cypress monorepo, ensure your environment matches these requirements as specified in the [`README.md`](https://github.com/cypress-io/cypress/blob/main/README.md) and `.node-version` files:

| Requirement | Version | Installation |
|-------------|---------|--------------|
| Node.js | ≥22.19.0 | `nvm use` or download from nodejs.org |
| Yarn | 1.22.22 | `npm install -g yarn@1` |
| Chrome (optional) | Stable release | For headless browser testing |

For **Linux headless environments**, CI already runs Xvfb on `DISPLAY=:1`. macOS and Windows contributors can skip Xvfb configuration.

## Fork, Clone, and Install

Start your contribution with the standard fork-and-clone workflow:

```bash

# Fork the repository on GitHub, then clone your fork

git clone https://github.com/<your-username>/cypress.git
cd cypress

# Install all dependencies across workspaces

yarn

```

The `yarn` command triggers multiple post-install hooks: installing every workspace, applying patches via `patch-package`, rebuilding native modules, and generating the V8 snapshot required for the Electron binary.

Create a feature branch with a descriptive name:

```bash
git checkout -b my-feature

```

## Code Style and Quality Checks

The **Cypress monorepo enforces strict code style** through ESLint. Key rules include no semicolons, single quotes, and 2-space indentation.

Run linting commands from the repository root:

```bash

# Check for style violations

yarn lint

# Auto-fix many common issues

yarn lint:fix

```

For **type checking**, use `yarn type-check` to validate the entire repository. Individual packages offer faster targeted checks via `yarn workspace @packages/<pkg> test`.

## Testing Your Changes

Each workspace maintains its own test runner—either **Vitest** or **Mocha**. Run targeted tests for faster feedback:

```bash

# Unit tests for the driver package (cy.* API implementation)

yarn workspace @packages/driver test-unit

# Full test suite across all packages (several minutes)

yarn test

```

After making changes, verify the build succeeds:

```bash

# Produce the Electron application binary

yarn build

# Start the development GUI with hot-reloading

yarn dev

```

## Commit Conventions and Semantic Release

Cypress uses **semantic-release** for automated publishing. Your commit messages must follow conventional commit format:

```bash
git add .
git commit -m "feat: add new cy.intercept matcher"
git push origin my-feature

```

**Allowed prefixes** from the [`CONTRIBUTING.md`](https://github.com/cypress-io/cypress/blob/main/CONTRIBUTING.md) guide:
- `feat:` – New features
- `fix:` – Bug fixes
- `chore:` – Maintenance tasks
- `docs:` – Documentation changes
- `test:` – Test additions or fixes
- `refactor:` – Code restructuring without behavior change

## Submitting a Pull Request

Open your pull request against the **`develop`** branch (or a package-specific branch if indicated). The **pull request template** at [`.github/PULL_REQUEST_TEMPLATE.md`](https://github.com/cypress-io/cypress/blob/main/.github/PULL_REQUEST_TEMPLATE.md) requires:

1. Reference to an open issue
2. Description of the change and motivation
3. Confirmation that `yarn lint` passes
4. Confirmation that relevant tests pass
5. Documentation updates if applicable

The **Code Review Checklist** in [`CONTRIBUTING.md`](https://github.com/cypress-io/cypress/blob/main/CONTRIBUTING.md) adds requirements for changelog entries and breaking change documentation.

CircleCI runs the full test matrix across Linux, macOS, and Windows, plus V8 snapshot validation. All checks must pass before merge.

## Post-Merge and Release Process

Once your PR merges to `develop`, **semantic-release automatically publishes** updated `@cypress/*` npm packages. No manual release action is required.

Documentation changes may need a separate PR to the `cypress-documentation` repository. Links to the docs contribution guide are in the main [`CONTRIBUTING.md`](https://github.com/cypress-io/cypress/blob/main/CONTRIBUTING.md) file.

## Summary

- **Environment**: Node.js ≥22.19.0 and Yarn 1.22.22 are mandatory for contributing to the Cypress monorepo
- **Development**: Use `yarn dev` to build the Electron app and start the Vite-powered UI
- **Quality**: Run `yarn lint`, `yarn type-check`, and `yarn test` before submitting
- **Commits**: Follow semantic-release conventions (`feat:`, `fix:`, `chore:`) for automated publishing
- **Target**: Open pull requests against the `develop` branch and complete the PR template checklist

## Frequently Asked Questions

### What Node.js version does Cypress require?

Cypress requires **Node.js ≥22.19.0** as defined in the `.node-version` file. Use `nvm use` if you have Node Version Manager installed, or download directly from nodejs.org. This version requirement ensures compatibility with the V8 snapshot generation and Electron build pipeline.

### How do I run tests for a specific package?

Use the `yarn workspace` command with the package name. For example, `yarn workspace @packages/driver test-unit` runs unit tests for the driver package containing the `cy.*` API. Each package in `packages/` and `npm/` has its own test scripts defined in its local [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json).

### Why does `yarn install` take so long?

The `yarn` command in the Cypress monorepo installs dependencies across all workspaces, rebuilds native modules, applies patches via `patch-package`, and generates the V8 snapshot for the Electron binary. This comprehensive setup ensures the development environment matches production builds but requires several minutes on first run.

### What branch should I target for my pull request?

Target the **`develop`** branch for most contributions. The [`CONTRIBUTING.md`](https://github.com/cypress-io/cypress/blob/main/CONTRIBUTING.md) guide specifies that `develop` is the main integration branch, and semantic-release publishes from there. Some package-specific features may use dedicated branches—check the pull request template for current guidance.