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

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, 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, 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, scripts/gulp/monorepoPaths.ts
system-tests/	Full end-to-end tests against built Cypress binary	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 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 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 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 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.

Critical file: scripts/gulp/monorepoPaths.ts

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

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

# 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	Workspace definitions, root scripts, private flag
yarn.lock	Exact dependency versions across entire repository
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 repository:

• AGENTS.md — High-level monorepo overview
• packages/AGENTS.md — Details of each @packages/* module
• npm/README.md — Explanation of published packages
• scripts/gulp/monorepoPaths.ts — Auto-generated path map
• 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 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 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 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 with proper naming, then run yarn gulp makePathMap to regenerate 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.

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