# How the Cypress Config Package Manages Settings: Inside @packages/config

> Discover how the Cypress config package manages all project settings. Learn about its role as the single source of truth for options, defaults, validation, and deprecation handling.

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

---

**The Cypress config package (`@packages/config`) serves as the single source of truth for all project settings by centralizing option definitions, default values, validation rules, and deprecation handling in a structured registry.**

The configuration system that powers the Cypress test runner is isolated within the `@packages/config` directory of the `cypress-io/cypress` monorepo. This package defines every valid configuration key, enforces type safety across the codebase, and provides the validation logic consumed by the CLI, server, and browser driver.

## Centralized Configuration Definitions in src/options.ts

All Cypress configuration options are declared in **[`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts)**. Each option is defined as an object containing a `name`, `defaultValue`, `validation` function, and metadata fields such as `overrideLevel` and `requireRestartOnChange`.

The registry splits options into two distinct categories:

- **Driver options** – Settings that affect the browser test runner (e.g., `baseUrl`, `chromeWebSecurity`, `defaultCommandTimeout`)
- **Runtime options** – Values used by the Cypress CLI and server processes (e.g., `isInteractive`, `socketId`, `video`)

### Option Structure and Metadata

Every entry in the options array follows a consistent structure that enables programmatic validation and merging. According to the source code in [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts), option objects include:

- **`defaultValue`** – The fallback value applied when a user does not specify the option (e.g., `defaultValue: 4000` for `defaultCommandTimeout`)
- **`validation`** – A reference to a validator function from [`src/validation.ts`](https://github.com/cypress-io/cypress/blob/main/src/validation.ts) (e.g., `validate.isNumber`, `validate.isFullyQualifiedUrl`)
- **`overrideLevel`** – A string indicating where overrides are permitted: `'any'`, `'suite'`, or `'never'`
- **`requireRestartOnChange`** – Boolean flag indicating if the test runner must restart when this value changes

Some defaults are dynamic and depend on the testing type (`e2e` vs `component`), expressed as functions that receive the `options` object and return context-specific values.

## Validation and Default Value Resolution

When a configuration file is loaded, the package executes **`isValidConfig`**, which iterates over the registered options and invokes each validator with the fully-qualified key (e.g., `"e2e.baseUrl"`).

### Built-in Validators

The **[`packages/config/src/validation.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/validation.ts)** module exports a collection of validation functions that enforce type safety and format requirements:

- `isNumber` – Ensures numeric values for timeouts and intervals
- `isString` – Validates text-based options
- `isFullyQualifiedUrl` – Confirms URL format for network-related settings
- `isBoolean` – Checks true/false flags

These validators throw descriptive errors when user-provided values violate the expected schema.

### Testing-Type Specific Defaults

Default values can vary based on whether the user is running `e2e` or `component` tests. The options registry uses factory functions that read `options.testingType` to return appropriate defaults, ensuring that component-specific configurations like `specPattern` receive sensible out-of-the-box values.

## Override Levels and Breaking Change Detection

The config package manages not only current options but also the lifecycle of deprecated settings.

### Suite and Test-Level Overrides

The **`overrideLevel`** field controls where configuration mutations are permitted. When set to `'any'`, the option can be modified via `Cypress.Config()` or test-specific overrides. When set to `'suite'`, changes are restricted to describe blocks. When set to `'never'`, the value is locked after initialization.

### Handling Deprecated Options

Static lists of deprecated and removed options live in **`breakingOptions`**, **`breakingRootOptions`**, and **`testingTypeBreakingOptions`** within [`src/options.ts`](https://github.com/cypress-io/cypress/blob/main/src/options.ts). When a config file contains one of these keys, the package throws or logs a warning with the appropriate error key (e.g., `EXPERIMENTAL_SESSION_AND_ORIGIN_REMOVED`). This mechanism ensures users receive immediate feedback when upgrading to breaking versions.

## Public API and Programmatic Utilities

The **[`packages/config/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/index.ts)** file re-exports a public API consumed by other monorepo packages, including utilities for AST manipulation and configuration coercion.

### AST Manipulation Helpers

For programmatic configuration updates, the package exposes functions like **`addToCypressConfig`** and **`addTestingTypeToCypressConfig`** from [`src/ast-utils/addToCypressConfig.ts`](https://github.com/cypress-io/cypress/blob/main/src/ast-utils/addToCypressConfig.ts). These utilities mutate existing Cypress config objects to inject new properties while preserving the file structure.

```typescript
import { addToCypressConfig } from '@packages/config'

// Inject plugin configuration into an existing Cypress config object
const pluginConfig = { env: { NODE_ENV: 'test' } }
addToCypressConfig('e2e', pluginConfig, existingConfig)

```

### Utility Functions

The **[`src/utils.ts`](https://github.com/cypress-io/cypress/blob/main/src/utils.ts)** module provides general-purpose helpers:

- **`hideKeys`** – Filters sensitive configuration values from logs
- **`coerce`** – Type coercion for CLI argument parsing
- **`isResolvedConfigPropDefault`** – Checks if a configuration value remains at its default setting

```typescript
import { isResolvedConfigPropDefault } from '@packages/config'

if (isResolvedConfigPropDefault(cypressConfig, 'watchForFileChanges')) {
  // Value is still default – safe to modify at runtime
}

```

## Integration Across the Cypress Monorepo

The options array defined in `@packages/config` is imported by the server (`@packages/server`), the driver (`@packages/driver`), and the CLI (`cli/`). These consumers call `config.get()` to retrieve the merged configuration, which is built from the defaults, the user's `cypress.config.{js,ts}` file, and any runtime overrides.

TypeScript types are generated from the same source definitions, and the package's [`index.ts`](https://github.com/cypress-io/cypress/blob/main/index.ts) re-exports them for downstream packages (e.g., `Cypress.ConfigOptions`). This guarantees that the public `defineConfig` API remains synchronized with the internal validation logic.

## Summary

- **Single source of truth**: All configuration options are defined in [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts) with strict schemas.
- **Validation pipeline**: The `isValidConfig` function runs validators from [`src/validation.ts`](https://github.com/cypress-io/cypress/blob/main/src/validation.ts) against every user-provided value.
- **Override control**: The `overrideLevel` metadata determines whether settings can be modified at suite, test, or runtime levels.
- **Deprecation handling**: Static lists in `breakingOptions` trigger warnings when removed or experimental options are detected.
- **Public API**: Utilities like `addToCypressConfig` and `isResolvedConfigPropDefault` enable programmatic configuration management across the monorepo.

## Frequently Asked Questions

### Where are Cypress configuration options defined?

All configuration options are defined in **[`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts)**. This file contains the canonical registry of every valid setting, including driver options that affect the browser and runtime options used by the CLI and server.

### How does Cypress validate configuration values?

Validation occurs through the **`isValidConfig`** function, which iterates over registered options and calls specific validators from **[`src/validation.ts`](https://github.com/cypress-io/cypress/blob/main/src/validation.ts)**. These validators check types, formats (like URLs), and ranges, throwing errors with descriptive keys when validation fails.

### What is the difference between driver options and runtime options?

**Driver options** (such as `baseUrl` and `defaultCommandTimeout`) control the behavior of the browser-based test runner. **Runtime options** (such as `video` and `isInteractive`) are processed by the Node.js CLI and server processes before the browser launches.

### How does Cypress handle deprecated configuration options?

Deprecated and removed options are tracked in **`breakingOptions`**, **`breakingRootOptions`**, and **`testingTypeBreakingOptions`** arrays within [`src/options.ts`](https://github.com/cypress-io/cypress/blob/main/src/options.ts). When a user includes one of these keys in their configuration, the package emits a warning or throws an error using standardized error keys like `EXPERIMENTAL_SESSION_AND_ORIGIN_REMOVED`.