# How to Navigate the Cypress Monorepo Structure: A Complete Guide for Contributors

> Master the Cypress monorepo structure with this guide. Understand the six primary workspaces and their roles to contribute effectively to the Cypress project.

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

---

**The Cypress monorepo is organized into six primary workspaces—`cli/`, `packages/`, `npm/`, `scripts/`, `system-tests/`, and `tooling/`—each containing self-contained npm packages that either power the internal Cypress binary or are published to npm for external use.**

Understanding how to navigate the Cypress monorepo structure is essential for anyone contributing to the codebase, debugging issues, or extending Cypress functionality. This guide maps the repository's layout based on the actual source code in [cypress-io/cypress](https://github.com/cypress-io/cypress), showing you exactly where to find critical components and how to work efficiently across workspaces.

## Top-Level Workspace Overview

The repository uses Yarn workspaces to manage dozens of inter-dependent packages. Here's how the directories break down:

| Directory | Purpose | Key Entry Points |
|-----------|---------|------------------|
| **`cli/`** | Public `cypress` npm package and bundled component-testing adapters | [`cli/package.json`](https://github.com/cypress-io/cypress/blob/main/cli/package.json), [`cli/README.md`](https://github.com/cypress-io/cypress/blob/main/cli/README.md) |
| **`packages/`** | Core internal packages (`@packages/*`)—driver, server, Electron runtime, telemetry, types | `packages/driver`, `packages/server`, `packages/electron` |
| **`npm/`** | Packages published to npm under `@cypress` scope | `npm/vite-dev-server`, `npm/webpack-dev-server` |
| **`scripts/`** | Build, release, and CI automation | [`scripts/gulp/gulpfile.ts`](https://github.com/cypress-io/cypress/blob/main/scripts/gulp/gulpfile.ts), [`scripts/gulp/monorepoPaths.ts`](https://github.com/cypress-io/cypress/blob/main/scripts/gulp/monorepoPaths.ts) |
| **`system-tests/`** | Full end-to-end tests against built Cypress binary | [`system-tests/README.md`](https://github.com/cypress-io/cypress/blob/main/system-tests/README.md) |
| **`tooling/`** | V8 snapshots, dependency bundling, and low-level utilities | `tooling/v8-snapshot`, `tooling/packherd` |

The high-level description of these workspaces is documented in [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) at the repository root, which serves as your starting reference for monorepo orientation.

## The `cli/` Workspace: Public Entry Point

The `cli/` directory contains the **public `cypress` npm package**—what users install with `npm install cypress`—along with component-testing adapters for React, Vue, and other frameworks.

Key details you need to know:

- [`cli/package.json`](https://github.com/cypress-io/cypress/blob/main/cli/package.json) marks the package as **private** within the monorepo; the actual published package is generated by CI scripts
- Component-testing adapters (`@cypress/react`, `@cypress/vue`, etc.) live here and are symlinked into the monorepo root when building the binary

This is where you start if you're investigating CLI behavior, npm package configuration, or component-testing adapter issues.

## The `packages/` Workspace: Core Implementation

The `packages/` directory contains the heart of Cypress. Each subdirectory is a standalone npm package scoped as `@packages/*`. Here are the most critical ones:

| Package | Role |
|---------|------|
| **`@packages/driver`** | JavaScript driver that executes `cy.*` commands inside the browser |
| **`@packages/server`** | HTTP server, WebSocket communication, and test run orchestration |
| **`@packages/electron`** | Electron wrapper and binary-building utilities |
| **`@packages/telemetry`** | OpenTelemetry instrumentation used across the repository |
| **`@packages/types`** | Shared TypeScript definitions for browsers, config, and internal APIs |
| **`@packages/web-config`** | Shared webpack/Vite configuration helpers |
| **`@packages/eslint-config`** | Central ESLint configuration for the entire monorepo |

For detailed descriptions of each package, check [`packages/AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/packages/AGENTS.md) in the source tree.

## The `npm/` Workspace: Published External Packages

Packages in `npm/` are **dual-purpose**: they build inside the monorepo but also publish independently to npm under the `@cypress` scope. Common examples include:

- **`@cypress/vite-dev-server`** — Vite dev-server integration for component testing
- **`@cypress/webpack-dev-server`** — Webpack dev-server counterpart

The [`npm/README.md`](https://github.com/cypress-io/cypress/blob/main/npm/README.md) file explains the relationship between these packages and the broader monorepo architecture.

## The `scripts/` Workspace: Build and CI Automation

All build, release, and CI automation logic lives under `scripts/`. The directory uses **Gulp tasks** orchestrated from [`scripts/gulp/gulpfile.ts`](https://github.com/cypress-io/cypress/blob/main/scripts/gulp/gulpfile.ts).

Critical file: **[`scripts/gulp/monorepoPaths.ts`](https://github.com/cypress-io/cypress/blob/main/scripts/gulp/monorepoPaths.ts)**

This file contains an **auto-generated map of all workspace paths** used by build scripts. It's generated by running:

```bash
yarn gulp makePathMap

```

You must re-run this command whenever you:
- Add a new package to the monorepo
- Rename an existing package
- Move packages between directories

## The `system-tests/` Workspace: Binary-Level Validation

System tests compile the **full Cypress binary** and run realistic end-to-end scenarios across multiple browsers (Electron, Chrome, Firefox, WebKit). These differ from unit tests in that they verify complete integration of all monorepo packages.

Use these when your changes affect:
- Binary packaging
- Cross-browser compatibility
- Full test lifecycle behavior

See [`system-tests/README.md`](https://github.com/cypress-io/cypress/blob/main/system-tests/README.md) for setup and execution instructions.

## The `tooling/` Workspace: Low-Level Infrastructure

This directory contains specialized build tools:

- **`tooling/v8-snapshot`** — Builds the V8 snapshot used by the Electron process for faster startup
- **`tooling/packherd`** — Bundles dependencies into single artifacts for the binary

You typically won't modify these unless you're working on Electron app performance or binary size optimization.

## Essential Navigation Commands

Use these Yarn workspace commands to move efficiently through the Cypress monorepo:

```bash

# List all workspaces defined in root package.json

yarn workspaces list

# Open any package in your editor

code packages/driver

# Run tests for a specific package only

yarn workspace @packages/driver test
yarn workspace @packages/server test

# Start development mode with watch and rebuild

yarn dev

# Regenerate monorepo path map after structural changes

yarn gulp makePathMap

```

## Key Configuration Files at Root

| File | Purpose |
|------|---------|
| `.node-version` | Required Node version for development (use with `nvm`) |
| [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) | Workspace definitions, root scripts, private flag |
| `yarn.lock` | Exact dependency versions across entire repository |
| [`lerna.json`](https://github.com/cypress-io/cypress/blob/main/lerna.json) | Lerna configuration for workspace builds (CI usage) |

## Direct Source File References

For hands-on navigation, bookmark these files in the [cypress-io/cypress](https://github.com/cypress-io/cypress) repository:

- [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) — High-level monorepo overview
- [`packages/AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/packages/AGENTS.md) — Details of each `@packages/*` module
- [`npm/README.md`](https://github.com/cypress-io/cypress/blob/main/npm/README.md) — Explanation of published packages
- [`scripts/gulp/monorepoPaths.ts`](https://github.com/cypress-io/cypress/blob/main/scripts/gulp/monorepoPaths.ts) — Auto-generated path map
- [`system-tests/README.md`](https://github.com/cypress-io/cypress/blob/main/system-tests/README.md) — System test execution guide

## Summary

- The **Cypress monorepo structure** revolves around six workspaces: `cli/`, `packages/`, `npm/`, `scripts/`, `system-tests/`, and `tooling/`
- **`packages/`** contains internal core code (`@packages/driver`, `@packages/server`, `@packages/electron`)
- **`npm/`** contains packages published to the `@cypress` npm scope
- **[`scripts/gulp/monorepoPaths.ts`](https://github.com/cypress-io/cypress/blob/main/scripts/gulp/monorepoPaths.ts)** auto-generates stable import paths—regenerate it with `yarn gulp makePathMap` when adding packages
- Use **`yarn workspace @packages/<name>`** commands to run isolated tests and builds
- Reference **[`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md)** and workspace-specific README files for authoritative documentation

## Frequently Asked Questions

### What is the difference between `packages/` and `npm/` in the Cypress monorepo?

The `packages/` directory contains **internal-only** packages scoped as `@packages/*`—these power the Cypress binary but are not published separately. The `npm/` directory contains packages that are **both used internally and published** to npm under the `@cypress` scope, such as `@cypress/vite-dev-server`. If you're adding functionality that external users need to install, place it in `npm/`; if it's purely internal infrastructure, use `packages/`.

### Where is the actual `cypress` npm package source code located?

The source lives in `cli/`, but with an important caveat: [`cli/package.json`](https://github.com/cypress-io/cypress/blob/main/cli/package.json) is marked **private** within the monorepo. The actual published `cypress` package is generated by CI scripts that bundle the CLI with built artifacts from other workspaces. For CLI behavior issues, start with `cli/lib/`; for packaging problems, investigate `scripts/gulp/` tasks.

### How do I add a new package to the Cypress monorepo?

Create your package directory in the appropriate workspace (`packages/` or `npm/`), add a [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) with proper naming, then run `yarn gulp makePathMap` to regenerate [`scripts/gulp/monorepoPaths.ts`](https://github.com/cypress-io/cypress/blob/main/scripts/gulp/monorepoPaths.ts). This updates the auto-generated path map so build scripts and other packages can import your new module via stable paths.