# Where to Find Cypress Internal APIs Documentation: A Developer’s Guide

> Find Cypress internal APIs documentation within the cypress-io/cypress monorepo. Explore JSDoc comments and type definitions in package index.ts files for clear insights.

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

---

**Cypress internal APIs are documented directly in the TypeScript source code within the `packages/` directory of the cypress-io/cypress monorepo, with each package exposing its public interface through top-level [`index.ts`](https://github.com/cypress-io/cypress/blob/main/index.ts) files containing JSDoc comments and type definitions.**

The cypress-io/cypress repository is organized as a monorepo where **Cypress internal APIs** live alongside the implementation code. Unlike the public user-facing documentation, these internal interfaces are not published as a separate website; instead, the source files themselves serve as the authoritative reference for developers extending or contributing to the framework.

## Core Internal API Packages

The monorepo splits functionality into self-contained npm packages under the `packages/` directory. Each package exports its internal API through a main entry point, typically [`src/index.ts`](https://github.com/cypress-io/cypress/blob/main/src/index.ts) or [`lib/index.ts`](https://github.com/cypress-io/cypress/blob/main/lib/index.ts), accompanied by TypeScript definitions and inline documentation.

### Configuration API

The **Configuration API** handles how Cypress reads, validates, and normalizes configuration objects. The primary entry point is [`packages/config/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/index.ts), which exports `defineConfig` for creating type-safe configuration objects and validation utilities for merging user settings with defaults.

### Test Driver API

Located in [`packages/driver/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/index.ts), the **Test Driver API** implements the `cy.*` command system that executes inside the browser. This package contains command registration logic, retry mechanisms, and the custom command API used to extend Cypress functionality.

### Server and Proxy API

The **Server and Proxy API** manages the HTTP server, browser launcher, proxy interception, and WebSocket communication. The main implementation resides in [`packages/server/lib/api/server.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/api/server.ts), exposing the `Server` class for handling incoming requests and socket messages.

### Network Stubbing API

For request interception and mocking, the **Network Stubbing API** in [`packages/net-stubbing/lib/adapters/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/net-stubbing/lib/adapters/index.ts) provides the underlying implementation for `cy.intercept`. This includes stubbing adapters, matcher logic, and response shaping utilities.

### Error Handling API

Centralized error management lives in [`packages/errors/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/errors/src/index.ts). The **Error Handling API** defines `CypressError` and its subclasses, along with formatting utilities used across the codebase to maintain consistent error reporting.

### Telemetry and Snapshot APIs

Additional specialized packages include the **Telemetry API** ([`packages/telemetry/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/telemetry/src/index.ts)), which wraps OpenTelemetry for internal event tracking, and the **V8 Snapshot Require API** ([`packages/v8-snapshot-require/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/v8-snapshot-require/src/index.ts)), which implements a custom `require` loader for pre-bundled V8 snapshots used by the Electron application.

## Navigating the Source Code for API Documentation

To locate **Cypress internal APIs** documentation within the repository:

1. Open the `packages/` directory to view the monorepo structure.

2. Select the relevant package based on functionality (e.g., `config`, `driver`, `server`).

3. Look for the top-level [`index.ts`](https://github.com/cypress-io/cypress/blob/main/index.ts) or [`index.js`](https://github.com/cypress-io/cypress/blob/main/index.js) file in the `src/` or `lib/` folder, which re-exports the public members of that package.

4. Read the JSDoc comments and TypeScript definitions, which serve as the primary documentation for method signatures, parameter types, and return values.

## Practical Examples: Importing Internal APIs

The following examples demonstrate how internal APIs are imported and used within Cypress's own packages. These patterns are intended for developers building plugins or contributing to the framework, not for end-users writing test specifications.

### Importing the Configuration API

```typescript
import { defineConfig, getConfig } from '@packages/config'

// Create a custom config object
const myConfig = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.ts',
    video: false,
  },
})

// Retrieve the resolved configuration (merged with defaults)
const resolved = getConfig()
console.log('Resolved config:', resolved)

```

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

### Using the Test Driver API

```typescript
import { cy } from '@packages/driver'

// Register a custom command
cy.addCommand('login', (username: string, password: string) => {
  cy.request('POST', '/login', { username, password })
    .its('status')
    .should('eq', 200)
})

// Use the command in a test (inside the AUT browser)
cy.login('alice', 'secret')

```

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

### Interacting with the Server API

```typescript
import { Server } from '@packages/server/lib/api/server'

// Create a temporary server instance for integration tests
const server = new Server({ port: 0 })   // 0 => auto-assign port
await server.start()

// Send a custom WebSocket message
server.send({ event: 'custom:event', data: { foo: 'bar' } })

```

*Source: [`packages/server/lib/api/server.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/api/server.ts)*

### Working with Network Stubbing

```typescript
import { createStub } from '@packages/net-stubbing/lib/adapters'

// Stub all GET requests to /api/users
createStub({
  method: 'GET',
  url: '/api/users',
  response: { statusCode: 200, body: [{ id: 1, name: 'Alice' }] },
})

```

*Source: [`packages/net-stubbing/lib/adapters/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/net-stubbing/lib/adapters/index.ts)*

## Summary

- **Cypress internal APIs** are not published as standalone documentation; the TypeScript source code serves as the primary reference.
- The repository follows a monorepo structure under `packages/`, with each package exposing its API through [`index.ts`](https://github.com/cypress-io/cypress/blob/main/index.ts) entry points.
- Key packages include `config` (configuration), `driver` (test commands), `server` (HTTP/proxy), and `net-stubbing` (request interception).
- JSDoc comments and TypeScript definitions in files like [`packages/config/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/index.ts) and [`packages/driver/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/index.ts) provide method signatures and usage details.
- Import paths follow the `@packages/` prefix convention when working within the Cypress codebase.

## Frequently Asked Questions

### Are Cypress internal APIs stable for third-party plugin development?

No, **Cypress internal APIs** are considered private implementation details and may change without notice between versions. Plugins should rely on the public API surface documented on the official Cypress documentation site. Use internal APIs only when contributing to the core repository or when absolutely necessary, acknowledging that future updates may require code changes.

### How do I import internal APIs when developing within the Cypress repository?

When working inside the cypress-io/cypress monorepo, import internal modules using the `@packages/` prefix followed by the package name. For example, use `import { defineConfig } from '@packages/config'` or `import { Server } from '@packages/server/lib/api/server'`. The repository's build system resolves these aliases to the corresponding `packages/` subdirectories.

### What is the difference between public and internal Cypress APIs?

Public APIs are the documented, stable interfaces exposed to end-users writing tests, such as `cy.visit()` or `Cypress.config()`, and are guaranteed to follow semantic versioning. **Cypress internal APIs** are the supporting infrastructure used by the framework itself—such as the `Server` class in [`packages/server/lib/api/server.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/api/server.ts) or configuration validators in [`packages/config/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/index.ts)—which are not covered by the public API contract and can change between releases.

### Where are TypeScript definitions for internal APIs located?

TypeScript definitions for **Cypress internal APIs** are co-located with the implementation files, typically in `*.d.ts` files or as inline JSDoc comments within the source. The main entry points—such as [`packages/config/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/index.ts), [`packages/driver/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/index.ts), and [`packages/errors/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/errors/src/index.ts)—export fully typed interfaces that serve as the authoritative documentation for function parameters, return types, and class methods.