How to Fork and Modify Cypress Code: A Complete Guide to Contributing

Fork and modify Cypress code by cloning the monorepo, installing dependencies with yarn, running yarn dev for hot-reload development, editing packages in packages/, and testing changes with yarn test-unit --scope @packages/<name> before submitting a PR to the develop branch.

Cypress is an open-source, end-to-end testing framework structured as a monorepo. If you want to fork and modify Cypress code—whether to fix bugs, add features, or customize behavior—you need to understand its workspace architecture and build workflow. This guide walks through the entire process based on the actual cypress-io/cypress source code.

Understanding the Cypress Monorepo Structure

Cypress organizes its codebase into distinct layers. Knowing where functionality lives prevents wasted time hunting through the wrong directories.

Layer	Location	Purpose
CLI	cli/	The cypress npm package users install; handles cypress open and cypress run commands
App & UI	packages/app/	Vue-based front-end running inside the Electron process
Core Libraries	packages/*	Private packages like @packages/driver, @packages/server, @packages/proxy that implement the test runner, network stack, and file rewriting
Network Stubbing	packages/net-stubbing/	Request interception and stubbing logic
Public npm Packages	npm/*	Standalone adapters (@cypress/react, @cypress/vue, @cypress/webpack-dev-server) published independently
Tooling	tooling/*	Build utilities including the V8 snapshot creator and dependency packherd
System Tests	system-tests/	End-to-end tests validating the complete Cypress binary

The root README.md serves as the entry point, while CONTRIBUTING.md contains detailed contributor requirements.

Forking and Cloning the Repository

To fork and modify Cypress code, start with these steps:

1. Fork the repository on GitHub through the web interface.

2. Clone your fork locally:

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

3. Checkout the develop branch, which contains the latest pre-release code:

git checkout develop

The Cypress team uses the develop branch as their integration branch—unlike many projects where main is primary.

Installing Dependencies

Cypress uses Yarn 1 workspaces with Lerna to orchestrate builds across all packages. Run this single command from the repository root:

yarn

This post-install step automatically:

• Installs all workspace dependencies
• Builds native modules
• Generates V8 snapshots
• Prepares the development environment

If you hit the known Yarn workspace bug, add the -W flag or temporarily downgrade Yarn as documented in CONTRIBUTING.md.

Running Cypress in Development Mode

Two primary commands launch the application:

Command	Behavior
yarn dev	Development mode with fast rebuilds and hot-reload for rapid iteration
yarn start	Full start through the CLI path, closer to production behavior

Both eventually invoke yarn cypress:run or yarn cypress:open, launching the Electron UI with the compiled @packages/app front-end. Use yarn dev when actively editing code.

Modifying Cypress Code: Step-by-Step

1. Locate the Relevant Package

Before editing, identify where your target functionality lives:

• Command behavior changes → packages/driver/src/commands.ts or related files
• Network interception logic → packages/net-stubbing/lib/adapters/
• Server-side orchestration → packages/server/
• UI components → packages/app/ (Vue-based)
• Public plugin extensions → npm/<package-name>/

2. Follow the Code Style

The Cypress codebase enforces strict ESLint rules defined in npm/eslint-plugin-dev:

• Single quotes
• No semicolons
• 2-space indentation

Your IDE should pick up these rules automatically from the root configuration.

3. Edit and Test Incrementally

After making changes, run tests for the specific package only—this dramatically speeds up feedback:

# Test only the driver package

yarn test-unit --scope @packages/driver

# Test network stubbing changes

yarn test-unit --scope @packages/net-stubbing

Unit, integration, and component tests live alongside each package. System tests in system-tests/ validate the full binary but run slower.

Complete Workflow Example

# 1. Fork, clone, and enter the repo

git clone https://github.com/<you>/cypress.git
cd cypress
git checkout develop

# 2. Install all workspace dependencies

yarn

# 3. Launch development mode with hot-reload

yarn dev

# 4. In another terminal, edit driver commands

code packages/driver/src/commands.ts

# 5. Run driver-specific unit tests

yarn test-unit --scope @packages/driver

# 6. Commit with semantic-release prefix

git add .
git commit -m "feat: add custom command support for X"

# 7. Push and open PR

git push origin HEAD

# Then open PR against upstream develop branch on GitHub

Submitting Your Changes Back

When ready to contribute your modifications:

1. Create a feature branch: git checkout -b feature/my-change

2. Commit with semantic prefixes: feat:, fix:, chore:, docs:, refactor: — these drive automated changelog generation

3. Open a Pull Request against the develop branch of cypress-io/cypress

The PR template enforces:

• A changelog entry in cli/CHANGELOG.md
• At least two maintainer approvals

CI runs on CircleCI (see .circleci/), executing the full test matrix, V8 snapshot builds, and lint validation.

Key Files for Deep Modifications

File	Why It Matters
CONTRIBUTING.md	Complete workflow, dependency installation, and style guidelines
packages/driver/README.md	Core command implementation and driver architecture
packages/server/README.md	Test run orchestration, browser launching, socket communication
packages/net-stubbing/README.md	Request interception and stubbing internals
npm/react/README.md	Example public npm package for extending component-testing adapters
tooling/v8-snapshot/README.md	V8 snapshot generation for the Electron binary
system-tests/README.md	End-to-end validation of the complete Cypress binary

Summary

• Fork and modify Cypress code by understanding its monorepo structure: cli/, packages/, npm/, and tooling/ directories serve distinct purposes
• Use yarn from the root to install all workspace dependencies at once
• Run yarn dev for rapid development with hot-reload, or yarn start for CLI-equivalent behavior
• Target specific packages with yarn test-unit --scope @packages/<name> for fast feedback loops
• Follow strict ESLint rules defined in npm/eslint-plugin-dev
• Submit PRs to the develop branch with semantic commit prefixes and changelog entries

Frequently Asked Questions

Do I need to build before running tests?

No—yarn dev and yarn test-unit handle compilation automatically. The build process integrates into the development commands through the Yarn workspace configuration.

Can I modify just the CLI without touching other packages?

Yes. The CLI lives in cli/ as a standalone package. Changes here affect how users invoke cypress commands, though core functionality typically requires edits to packages/driver/ or packages/server/ as well.

Why does my PR need two approvals?

Cypress maintains high code quality standards for a testing tool used by millions of developers. The two-approval requirement ensures maintainers from different areas review cross-cutting changes, particularly for security-sensitive code in packages/proxy/ and packages/server/.

How do I test changes to the network stubbing functionality?

Modify files in packages/net-stubbing/lib/adapters/, then run yarn test-unit --scope @packages/net-stubbing. For full validation, also run affected system tests in system-tests/ that exercise request interception end-to-end.

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