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

> Learn how to fork and modify Cypress code. Clone the monorepo, install dependencies, and run yarn dev for hot-reloading. Contribute to Cypress today.

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

---

**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`](https://github.com/cypress-io/cypress/blob/main/README.md) serves as the entry point, while [`CONTRIBUTING.md`](https://github.com/cypress-io/cypress/blob/main/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:

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

```

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

```bash
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:

```bash
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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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:

```bash

# 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

```bash

# 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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/CONTRIBUTING.md) | Complete workflow, dependency installation, and style guidelines |
| [`packages/driver/README.md`](https://github.com/cypress-io/cypress/blob/main/packages/driver/README.md) | Core command implementation and driver architecture |
| [`packages/server/README.md`](https://github.com/cypress-io/cypress/blob/main/packages/server/README.md) | Test run orchestration, browser launching, socket communication |
| [`packages/net-stubbing/README.md`](https://github.com/cypress-io/cypress/blob/main/packages/net-stubbing/README.md) | Request interception and stubbing internals |
| [`npm/react/README.md`](https://github.com/cypress-io/cypress/blob/main/npm/react/README.md) | Example public npm package for extending component-testing adapters |
| [`tooling/v8-snapshot/README.md`](https://github.com/cypress-io/cypress/blob/main/tooling/v8-snapshot/README.md) | V8 snapshot generation for the Electron binary |
| [`system-tests/README.md`](https://github.com/cypress-io/cypress/blob/main/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.