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

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, 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 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 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:

# 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:

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:

# 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:

# 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:

# 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:

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

Allowed prefixes from the 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 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 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 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.

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 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.

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