# Cypress Architecture Explained: Key Components and Monorepo Structure

> Explore the Cypress architecture and its key components. Understand the monorepo structure, CLI, Runner, and more for efficient end-to-end and component testing.

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

---

**The Cypress architecture consists of a monorepo containing specialized packages including the CLI, Test Driver, Runner UI, Desktop GUI, Server, Proxy, and Network Stubbing modules that work together to execute end-to-end and component tests inside real browsers.**

Cypress is built as a monorepo that combines a desktop GUI, test runner, JavaScript driver, and supporting services into a unified testing framework. Understanding the **Cypress architecture** helps developers debug issues, write custom commands, and extend the framework. The source code lives in the `cypress-io/cypress` repository, where each workspace under `packages/` and `cli/` handles a specific aspect of the testing workflow.

## Core Components of the Cypress Architecture

### CLI and Distribution Layer

The `cli/` directory contains the `cypress` npm package that users install globally or locally. This layer handles command parsing for `cypress open`, `cypress run`, and `cypress install`, serving as the entry point to the entire system.

The CLI entry point is implemented in [`cli/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/cli/src/index.ts), which validates the environment and delegates to the appropriate binary.

### Test Driver

The **Test Driver** (`packages/driver`) is the heart of Cypress execution. It runs inside the browser and implements all `cy.*` commands, automatic retries, and assertions.

Key implementation files include:
- [`packages/driver/src/main.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/main.ts) – Initializes the driver and sets up the Cypress global
- [`packages/driver/src/cy/commands/navigation.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/cy/commands/navigation.ts) – Implements `cy.visit()`
- [`packages/driver/src/cy/commands/query.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/cy/commands/query.ts) – Implements `cy.get()` and querying logic

### Runner UI

The **Runner** (`packages/runner`) is a Webpack-bundled web application that hosts the Application-Under-Test (AUT) iframe. It wires the driver to the AUT and provides the visual interface showing tests running in real-time.

The main entry point is [`packages/runner/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/runner/src/index.ts), which coordinates between the driver and the browser environment.

### Desktop GUI and Launchpad

The **Desktop GUI** consists of two Vue 3 applications:

- **`packages/app`** – The main Desktop application (Launchpad) where users select projects, browsers, and specs
- **`packages/launchpad`** – The project scaffolding UI for onboarding and generating test files

Entry points include [`packages/app/src/App.vue`](https://github.com/cypress-io/cypress/blob/main/packages/app/src/App.vue) and [`packages/launchpad/src/Launchpad.vue`](https://github.com/cypress-io/cypress/blob/main/packages/launchpad/src/Launchpad.vue).

### Reporter

The **Reporter** (`packages/reporter`) renders test results including the pass/fail tree and log panels. Implemented in [`packages/reporter/src/Reporter.vue`](https://github.com/cypress-io/cypress/blob/main/packages/reporter/src/Reporter.vue), this component displays the command log and error messages during test execution.

### Server and Proxy

The **Server** (`packages/server`) orchestrates the test run by:
- Serving test files over HTTP
- Launching browsers via the launcher
- Managing WebSocket connections between the driver and GUI

The **Proxy** (`packages/proxy`) intercepts all HTTP/S traffic from the browser, enabling network stubbing and request modification. Both components are initialized through [`packages/server/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/src/index.ts) and [`packages/proxy/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/proxy/src/index.ts).

### Network Stubbing

The **Net-Stubbing** package (`packages/net-stubbing`) implements `cy.intercept()` functionality, handling request matching and response manipulation. The core logic resides in [`packages/net-stubbing/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/net-stubbing/src/index.ts), which works with the proxy to intercept and modify network traffic.

### Code Rewriter

The **Rewriter** (`packages/rewriter`) transforms test and application code on the fly, injecting instrumentation, polyfills, and Cypress-specific modifications. This ensures the AUT can communicate with the driver and that test code runs correctly in the browser context.

Main entry: [`packages/rewriter/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/rewriter/src/index.ts).

### Configuration System

The **Config** package (`packages/config`) provides TypeScript definitions, default values, validation logic, and the public `defineConfig` API. This ensures type safety and consistent configuration across the monorepo.

Source: [`packages/config/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/index.ts).

### Data Context

The **Data Context** (`packages/data-context`) implements a GraphQL layer that stores project state, spec files, run history, and UI settings. This enables the Desktop GUI to query and mutate application state efficiently.

Entry point: [`packages/data-context/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/data-context/src/index.ts).

### Browser Launcher and Electron Runtime

The **Launcher** (`packages/launcher`) detects installed browsers (Chrome, Firefox, Edge, WebKit) and manages their launch parameters. The **Electron** package (`packages/electron`) wraps the Electron runtime, handling binary building and auto-updates.

Key files:
- [`packages/launcher/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/launcher/src/index.ts)
- [`packages/electron/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/electron/src/index.ts)

### WebExtension

The **Extension** (`packages/extension`) is injected into browsers to enable cross-origin features and automation hooks required for Cypress to control the browser securely.

Background script: [`packages/extension/src/background.ts`](https://github.com/cypress-io/cypress/blob/main/packages/extension/src/background.ts).

### Component Testing Adapters

Under `npm/@cypress/`, the architecture includes adapters for component testing:
- `@cypress/react`, `@cypress/vue` – Provide `mount` APIs for framework-specific component testing
- `@cypress/webpack-dev-server`, `@cypress/vite-dev-server` – Launch development servers for component tests

These adapters bridge the gap between the driver and modern frontend frameworks.

## How the Cypress Architecture Works Together

When you run `cypress open` or `cypress run`, the following execution flow occurs:

1. **CLI** parses commands and loads configuration via `defineConfig` from `packages/config`
2. **Server** spins up an HTTP server, starts the **Proxy**, and opens a browser via the **Launcher**
3. Inside the browser, the **Driver** executes user test code, exposing the `cy.*` API
4. The **Runner UI** hosts the AUT iframe and communicates with the driver via WebSockets
5. The **Rewriter** patches source files on the fly to inject Cypress instrumentation
6. Network traffic is intercepted by the **Proxy**; `cy.intercept` logic executes via **Net-Stubbing**
7. Test results stream back to the **Reporter** UI in the Desktop App (**App** package)
8. All components share common **Types** and **Error** handling libraries for consistency

## Practical Code Examples

### End-to-End Test Implementation

This example demonstrates how the driver commands execute inside the browser:

```javascript
// cypress/e2e/spec.cy.js
describe('Navigation', () => {
  it('visits the home page', () => {
    // Implemented in packages/driver/src/cy/commands/navigation.ts
    cy.visit('https://example.cypress.io')
    
    // Implemented in packages/driver/src/cy/commands/query.ts
    cy.get('h1').should('contain', 'Kitchen Sink')
  })
})

```

### Network Interception

The `cy.intercept` command leverages the net-stubbing architecture:

```javascript
// cypress/e2e/network.cy.js
describe('API Stubbing', () => {
  it('mocks user data', () => {
    // Implemented in packages/net-stubbing/src/index.ts
    cy.intercept('GET', '/api/users', { fixture: 'users.json' })
    
    cy.visit('/users')
    cy.get('.user').should('have.length', 3)
  })
})

```

### Component Testing with React Adapter

Component tests use the same driver but mount components instead of visiting pages:

```javascript
// MyButton.spec.jsx
import MyButton from '../../src/MyButton'

describe('MyButton', () => {
  it('renders with label', () => {
    // Provided by npm/@cypress/react/src/index.tsx
    cy.mount(<MyButton label="Submit" />)
    cy.contains('Submit').should('be.visible')
  })
})

```

### CLI Usage

```bash

# Entry point: cli/src/index.ts

cypress run --spec "cypress/e2e/login.cy.js"
cypress open --browser chrome

```

## Summary

- **Cypress architecture** is organized as a monorepo with distinct packages under `packages/` and `cli/`
- The **Driver** (`packages/driver`) runs inside the browser and implements all `cy.*` commands
- The **Server** (`packages/server`) and **Proxy** (`packages/proxy`) handle file serving and network interception
- **Net-Stubbing** (`packages/net-stubbing`) powers the `cy.intercept()` API for mocking HTTP requests
- The **Rewriter** (`packages/rewriter`) transforms code to enable Cypress instrumentation
- **Desktop GUI** components (`packages/app`, `packages/launchpad`) provide the Vue 3-based user interface
- Component testing extends the architecture through framework-specific adapters in `npm/@cypress/`

## Frequently Asked Questions

### What is the Cypress driver and where does it run?

The **Cypress driver** is the JavaScript library that executes inside the browser alongside your application. Located in [`packages/driver/src/main.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/main.ts), it implements all `cy.*` commands, assertion logic, and retry mechanisms. Unlike Selenium-based tools that run outside the browser, the driver operates within the same event loop as the Application-Under-Test, enabling native access to DOM and network events.

### How does Cypress proxy and intercept network requests?

Cypress uses the **Proxy** package ([`packages/proxy/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/proxy/src/index.ts)) to intercept all HTTP/S traffic between the browser and external servers. When you call `cy.intercept()`, the **Net-Stubbing** package ([`packages/net-stubbing/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/net-stubbing/src/index.ts)) matches requests against your patterns and can modify responses or requests in real-time. This architecture allows Cypress to stub network traffic without modifying your application's code.

### What is the difference between the App and Launchpad packages?

The **App** package (`packages/app`) contains the main Desktop GUI where users select projects, browsers, and specs during active testing. The **Launchpad** package (`packages/launchpad`) handles project scaffolding, onboarding flows, and initial project setup. While [`app/src/App.vue`](https://github.com/cypress-io/cypress/blob/main/app/src/App.vue) manages the test-running interface, [`launchpad/src/Launchpad.vue`](https://github.com/cypress-io/cypress/blob/main/launchpad/src/Launchpad.vue) manages the pre-test configuration and project creation workflows.

### How does Cypress support component testing?

Cypress extends its architecture for component testing through adapter packages in `npm/@cypress/`. These adapters (like `@cypress/react` and `@cypress/vue`) provide a `mount` function that renders components in isolation using the same driver infrastructure. The **Webpack** and **Vite** dev server packages (`npm/@cypress/webpack-dev-server`, `npm/@cypress/vite-dev-server`) compile components on the fly, allowing the driver to interact with them using the same `cy.*` commands used for end-to-end tests.