# Where Are Cypress Configuration Files Located? A Complete Guide to Config Discovery and Loading

> Find your Cypress configuration files. Learn where cypress.config.{js,ts,mjs,cjs} are located and how Cypress loads them automatically in your project root.

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

---

**Cypress configuration files are located in the project root as `cypress.config.{js,ts,mjs,cjs}`, which Cypress automatically discovers and loads at runtime.**

In the `cypress-io/cypress` open-source repository, **Cypress configuration files** serve as the single source of truth for test behavior, project settings, and plugin registration. These files reside in your project's root directory and control everything from base URLs to component testing frameworks. Understanding where these files live and how Cypress processes them is essential for customizing your testing workflow.

## What Are Cypress Configuration Files?

A **Cypress configuration file** is a project-level file that exports an object defining your testing environment. According to the Cypress source code, this file can be written in JavaScript, TypeScript, or their ES module variants, allowing you to choose the syntax that matches your project's stack.

## Where Cypress Looks for Configuration Files

Cypress searches for a single configuration file named `cypress.config` in your project root. The framework supports multiple extensions to accommodate different module systems and type preferences.

### Supported File Extensions

Cypress detects the following file patterns in order of preference:

- [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js) - CommonJS or ES modules JavaScript
- [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts) - TypeScript with type safety  
- `cypress.config.mjs` - ES modules explicitly
- `cypress.config.cjs` - CommonJS explicitly

The detection logic resides in [`packages/scaffold-config/src/detect.ts`](https://github.com/cypress-io/cypress/blob/main/packages/scaffold-config/src/detect.ts), which determines the file's language based on its extension before attempting to load it.

## How Cypress Loads Configuration Files Internally

The Cypress server employs a multi-stage process to safely load and validate your configuration. This architecture prevents configuration errors from crashing the main test runner process.

### File Discovery and Language Detection

First, the system invokes the detector in [`packages/scaffold-config/src/detect.ts`](https://github.com/cypress-io/cypress/blob/main/packages/scaffold-config/src/detect.ts) to identify whether your config uses JavaScript or TypeScript. This module resolves the absolute path to your configuration file based on the discovered extension.

### Isolated Configuration Evaluation

To protect the main process from malformed JavaScript, Cypress loads the configuration in a separate Node process. The logic in [`packages/server/lib/plugins/child/run_require_async_child.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/plugins/child/run_require_async_child.ts) handles this **require-async-child** IPC mechanism, evaluating the exported configuration object in isolation before passing it back to the parent process.

### Validation and Merging

Once retrieved, the configuration flows to [`packages/server/lib/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/config.ts), which serves as the central hub for configuration management. This module parses the user-provided settings, validates them against the internal schema defined in [`packages/types/src/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/types/src/config.ts), and merges them with Cypress's built-in defaults. If no configuration file exists, the system falls back entirely to these internal defaults.

### UI-Driven Configuration Updates

When you modify settings through the Cypress UI, the application uses [`packages/data-context/src/util/config-file-updater.ts`](https://github.com/cypress-io/cypress/blob/main/packages/data-context/src/util/config-file-updater.ts) to write changes back to your `cypress.config` file on disk, ensuring the filesystem remains in sync with interactive adjustments.

## Creating Your First Cypress Configuration File

To establish your testing environment, create a [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js) or [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts) file in your project root. The file must export a configuration object containing your desired settings.

For **end-to-end testing**, create a JavaScript configuration:

```javascript
// cypress.config.js
module.exports = {
  e2e: {
    baseUrl: 'http://localhost:3000',
    supportFile: false,
  },
}

```

For **component testing** with TypeScript:

```typescript
// cypress.config.ts
export default {
  component: {
    devServer: {
      framework: 'react',
      bundler: 'webpack',
    },
  },
}

```

## Programmatically Loading Configuration

You can load configuration files using the same internal methods that Cypress employs during test runs. This approach is useful for custom scripts or tooling that needs to access the resolved configuration.

```typescript
import { loadConfig } from '@packages/server/lib/config'

async function getConfiguration() {
  // Assumes current working directory is the project root
  const fullConfig = await loadConfig({ projectRoot: process.cwd() })
  return fullConfig
}

```

This programmatic interface mirrors the behavior of the CLI, executing the detection logic from [`packages/scaffold-config/src/detect.ts`](https://github.com/cypress-io/cypress/blob/main/packages/scaffold-config/src/detect.ts) and the validation routines in [`packages/server/lib/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/config.ts) to produce the final configuration object.

## Summary

- **Cypress configuration files** reside in the project root as `cypress.config.{js,ts,mjs,cjs}` and are automatically discovered at runtime.
- The [`packages/scaffold-config/src/detect.ts`](https://github.com/cypress-io/cypress/blob/main/packages/scaffold-config/src/detect.ts) module handles file extension detection to determine whether to parse JavaScript or TypeScript.
- Configuration loading is isolated via the **require-async-child** mechanism in [`packages/server/lib/plugins/child/run_require_async_child.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/plugins/child/run_require_async_child.ts) for process safety.
- Validation and merging occur in [`packages/server/lib/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/config.ts), which combines user settings with internal defaults defined in [`packages/types/src/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/types/src/config.ts).
- The [`packages/data-context/src/util/config-file-updater.ts`](https://github.com/cypress-io/cypress/blob/main/packages/data-context/src/util/config-file-updater.ts) utility manages disk writes when configuration changes originate from the Cypress UI.

## Frequently Asked Questions

### What happens if no configuration file exists?

If Cypress cannot locate a `cypress.config` file in the project root, it falls back to internal defaults defined in [`packages/server/lib/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/config.ts). The test runner will execute using these default settings, though you will miss project-specific customizations such as custom base URLs or plugin registrations.

### Can I use both JavaScript and TypeScript configuration files?

No, Cypress expects only a single configuration file per project. The detection logic in [`packages/scaffold-config/src/detect.ts`](https://github.com/cypress-io/cypress/blob/main/packages/scaffold-config/src/detect.ts) searches for one file matching the supported extensions and uses the first match found. You cannot split configuration across multiple files; instead, import shared configuration objects into your single root config if needed.

### Where is the configuration file validation logic located?

Validation and schema enforcement occur in [`packages/server/lib/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/config.ts), which merges user-provided settings with Cypress's built-in defaults. Type definitions that inform both the validation logic and IDE autocompletion are exported from [`packages/types/src/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/types/src/config.ts), ensuring type safety for TypeScript users.

### How does Cypress handle configuration updates from the UI?

When you modify configuration through the interactive Cypress UI, the application invokes [`packages/data-context/src/util/config-file-updater.ts`](https://github.com/cypress-io/cypress/blob/main/packages/data-context/src/util/config-file-updater.ts) to write changes directly to your `cypress.config` file on disk. This ensures that interactive adjustments persist across test runs and remain version-controlled alongside your source code.