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

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 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, 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, which exports the core cy object and command chain logic. The server initialization logic resides in 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
• @tooling/packherd – Bundles dependencies for inclusion in snapshots, defined in 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, 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

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

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

Starting the Server Programmatically

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

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

mount(<MyComponent />)

Intercepting Network Requests

// 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 defines the published npm package metadata and binary entry points
• Driver: packages/driver/src/index.ts exports the core command implementation and cy object
• Server: packages/server/lib/server.ts contains the HTTP server initialization and socket management logic
• App GUI: packages/app/src/App.vue serves as the root Vue 3 component for the desktop interface
• Proxy: packages/proxy/lib/proxy.ts handles request interception and SSL certificate management
• V8 Snapshot: tooling/v8-snapshot/src/generate.ts orchestrates snapshot generation for the Electron binary
• Packherd: tooling/packherd/src/bundle.ts creates dependency bundles optimized for snapshotting
• System Tests: 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 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, 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.

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