# What Are the Main Packages in the Cypress Monorepo? Workspace Guide for Contributors

> Discover the main packages in the Cypress monorepo: cli, packages, npm, tooling, system-tests, and scripts. Understand the Cypress architecture and contribute effectively.

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

---

**The Cypress monorepo organizes its architecture into six primary workspaces—`cli/`, `packages/`, `npm/`, `tooling/`, `system-tests/`, and `scripts/`—that separate the command-line interface, core runtime engine, public npm modules, build utilities, and testing infrastructure.**

Cypress is structured as a **monorepo** that consolidates all source code, tooling, and distribution packages into a single repository. Understanding the **main packages in the Cypress monorepo** is essential for contributors and advanced users who want to extend the framework or debug internal behavior. The repository layout is defined in the top-level [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) file, which partitions the codebase into logical workspaces based on function and distribution method.

## CLI Workspace (`cli/`): Command-Line Interface

The `cli/` workspace serves as the primary entry point for the `cypress` npm package and houses the adapters that power component testing. This workspace contains the main `cypress` CLI package that users install when running `npm install cypress`, along with framework-specific mounting utilities.

Key packages in this workspace include:

- **`cypress`** – The published CLI package that provides the `cypress open` and `cypress run` commands
- **`@cypress/react`**, **`@cypress/vue`**, **`@cypress/angular`**, **`@cypress/svelte`** – Framework adapters for component testing
- **`@cypress/mount-utils`** – Shared utilities for mounting components across frameworks

The CLI package configuration is defined in [`cli/package.json`](https://github.com/cypress-io/cypress/blob/main/cli/package.json), which specifies the binary entry points and dependencies for the globally installed command-line tool.

## Core Internal Packages (`packages/`): Runtime and Infrastructure

The `packages/` workspace contains the **core internal packages** that constitute the Cypress runtime, including the test driver, HTTP server, network proxy, and graphical user interface. These packages are prefixed with `@packages/` in the source code and handle everything from browser automation to request interception.

Critical packages in this workspace include:

- **`@packages/driver`** – The test driver that implements `cy.visit()`, `cy.get()`, and all Cypress commands
- **`@packages/server`** – HTTP server, browser launching logic, and socket communication layer
- **`@packages/app`** – Vue 3-based GUI for the Cypress desktop application
- **`@packages/launchpad`** – Project scaffolding and onboarding UI
- **`@packages/runner`** – Webpack-bundled runner UI that displays test results
- **`@packages/proxy`** – Request interception and modification layer
- **`@packages/net-stubbing`** – Network stubbing and route handling for `cy.intercept()`
- **`@packages/network`** and **`@packages/https-proxy`** – Low-level networking utilities
- **`@packages/rewriter`** – JavaScript rewriting for test isolation
- **`@packages/launcher`** – Browser detection and launching abstraction
- **`@packages/extension`** – Browser extension injection
- **`@packages/types`** – Shared TypeScript definitions
- **`@packages/errors`** – Error formatting and handling
- **`@packages/socket`** – WebSocket communication between runner and driver
- **`@packages/telemetry`** – Usage analytics and error reporting
- **`@packages/icons`** – UI assets and iconography
- **`@packages/stderr-filtering`** – Log filtering utilities

The driver implementation lives in [`packages/driver/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/index.ts), which exports the core `cy` object and command chain logic. The server initialization logic resides in [`packages/server/lib/server.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/server.ts), handling the HTTP server startup and socket binding.

## Public NPM Packages (`npm/`): Framework Adapters and Dev Servers

The `npm/` workspace publishes packages to the public npm registry for end-user consumption. Unlike the internal `@packages/` scope, these modules use the `@cypress/` scope and are imported directly into users' test files and configuration.

Available public packages include:

- **`@cypress/react`**, **`@cypress/vue`**, **`@cypress/angular`**, **`@cypress/angular-zoneless`**, **`@cypress/svelte`** – Component testing mount adapters
- **`@cypress/mount-utils`** – Framework-agnostic mounting utilities
- **`@cypress/webpack-dev-server`** and **`@cypress/vite-dev-server`** – Development server integrations for component testing
- **`@cypress/webpack-preprocessor`** and **`@cypress/webpack-batteries-included-preprocessor`** – File preprocessing for webpack
- **`@cypress/vite-plugin-cypress-esm`** – Vite plugin for ES module support
- **`@cypress/grep`** – Test filtering by tags and titles
- **`@cypress/puppeteer`** – Puppeteer integration for browser automation
- **`@cypress/schematic`** – Angular CLI schematic support
- **`@cypress/eslint-plugin-dev`** – Internal ESLint rules

## Build Tooling (`tooling/`): Snapshots and Bundling

The `tooling/` workspace contains build-time utilities that generate V8 snapshots, bundle dependencies, and handle Electron-specific compilation tasks. These packages optimize the final binary distribution by creating memory snapshots of the JavaScript heap.

Key tooling packages include:

- **`@tooling/v8-snapshot`** – Generates V8 heap snapshots to speed up Electron app startup, implemented in [`tooling/v8-snapshot/src/generate.ts`](https://github.com/cypress-io/cypress/blob/main/tooling/v8-snapshot/src/generate.ts)
- **`@tooling/packherd`** – Bundles dependencies for inclusion in snapshots, defined in [`tooling/packherd/src/bundle.ts`](https://github.com/cypress-io/cypress/blob/main/tooling/packherd/src/bundle.ts)
- **`@tooling/electron-mksnapshot`** – Creates platform-specific snapshot binaries for Electron

## System Tests (`system-tests/`): Integration Verification

The `system-tests/` workspace houses the full end-to-end test suite that runs against a built Cypress binary. These tests spin up the actual compiled application and exercise the entire stack, verifying that the CLI, server, driver, and UI work together correctly.

Test specifications in this workspace, such as [`system-tests/test/visit_spec.js`](https://github.com/cypress-io/cypress/blob/main/system-tests/test/visit_spec.js), launch real browser instances and validate complete user workflows rather than mocking internal dependencies.

## Development Scripts (`scripts/`): Automation

The `scripts/` workspace contains internal Node.js scripts for continuous integration, releases, and development automation. These scripts handle tasks like `yarn dev` (starting the development environment), `yarn build` (compiling the binary), and publishing workflows.

## Practical Code Examples

Below are practical implementations showing how these packages are imported and used across the codebase.

### Importing the Driver Directly

```typescript
// From @packages/driver - Core test commands
import { cy } from '@packages/driver'

cy.visit('https://example.com')
cy.get('button').click()

```

### Starting the Server Programmatically

```javascript
// From @packages/server - Programmatic server control
const { start } = require('@packages/server')

start({
  projectRoot: '/my/project',
  config: { video: true },
}).then(server => {
  console.log('Cypress server listening on', server.port)
})

```

### Mounting React Components

```typescript
// From @cypress/react - Component testing
import { mount } from '@cypress/react'
import MyComponent from './MyComponent'

mount(<MyComponent />)

```

### Intercepting Network Requests

```javascript
// From @packages/proxy - Network interception
const { getIntercept } = require('@packages/proxy')

getIntercept().then(intercept => {
  intercept.on('request', req => {
    if (req.url.includes('api')) req.reply({ body: '{"mock":true}' })
  })
})

```

## Key Source Files by Package

Understanding the relationship between packages and their entry points helps navigate the codebase:

- **CLI**: [`cli/package.json`](https://github.com/cypress-io/cypress/blob/main/cli/package.json) defines the published npm package metadata and binary entry points
- **Driver**: [`packages/driver/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/index.ts) exports the core command implementation and `cy` object
- **Server**: [`packages/server/lib/server.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/server.ts) contains the HTTP server initialization and socket management logic
- **App GUI**: [`packages/app/src/App.vue`](https://github.com/cypress-io/cypress/blob/main/packages/app/src/App.vue) serves as the root Vue 3 component for the desktop interface
- **Proxy**: [`packages/proxy/lib/proxy.ts`](https://github.com/cypress-io/cypress/blob/main/packages/proxy/lib/proxy.ts) handles request interception and SSL certificate management
- **V8 Snapshot**: [`tooling/v8-snapshot/src/generate.ts`](https://github.com/cypress-io/cypress/blob/main/tooling/v8-snapshot/src/generate.ts) orchestrates snapshot generation for the Electron binary
- **Packherd**: [`tooling/packherd/src/bundle.ts`](https://github.com/cypress-io/cypress/blob/main/tooling/packherd/src/bundle.ts) creates dependency bundles optimized for snapshotting
- **System Tests**: [`system-tests/test/visit_spec.js`](https://github.com/cypress-io/cypress/blob/main/system-tests/test/visit_spec.js) demonstrates full-stack testing against the compiled binary

## Summary

The Cypress monorepo divides its functionality into distinct workspaces that separate concerns between user-facing APIs and internal implementation:

- **`cli/`** provides the global `cypress` command and component testing adapters
- **`packages/`** contains the core runtime including the driver, server, proxy, and Vue 3 GUI
- **`npm/`** distributes public framework adapters and development server integrations
- **`tooling/`** generates V8 snapshots and bundles dependencies for the Electron binary
- **`system-tests/`** validates the complete integrated product against built binaries
- **`scripts/`** automates development, building, and release processes

## Frequently Asked Questions

### What is the difference between `@packages/` and `@cypress/` modules?

**`@packages/` modules are internal dependencies** that live in the `packages/` directory and are never published to npm separately; they are bundled into the final Cypress binary. **`@cypress/` modules are public npm packages** that live in the `npm/` directory and are published to the registry for users to install directly, such as `@cypress/react` for component testing or `@cypress/grep` for test filtering.

### Which package contains the implementation of Cypress commands like `cy.visit()`?

The **`@packages/driver`** package contains all Cypress command implementations, including `cy.visit()`, `cy.get()`, and `cy.intercept()`. According to the cypress-io/cypress source code, the entry point at [`packages/driver/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/index.ts) initializes the command chain and automation APIs that communicate with the browser.

### How does the `tooling/` workspace affect the final Cypress application?

The **`tooling/` workspace generates V8 heap snapshots** that drastically reduce the startup time of the Electron-based Cypress application. Tools like `@tooling/v8-snapshot` and `@tooling/packherd` bundle and snapshot the JavaScript code during the build process, as implemented in [`tooling/v8-snapshot/src/generate.ts`](https://github.com/cypress-io/cypress/blob/main/tooling/v8-snapshot/src/generate.ts), creating a memory image that loads faster than parsing raw JavaScript at runtime.

### Where are the component testing adapters for React and Vue located?

Component testing adapters are located in **both the `cli/` and `npm/` workspaces**. The source code lives in `npm/` (e.g., `@cypress/react`, `@cypress/vue`), while the `cli/` workspace also contains copies or references to these adapters. These packages export `mount` functions that bridge framework components into the Cypress test runner environment.