# Where Are Cypress Configuration Files Stored? Project Root and Detection Logic

> Discover where Cypress configuration files are stored in your project root. Learn about cypress.config.js, cypress.json, and their detection logic for seamless setup.

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

---

**Cypress configuration files are stored in the project root directory and must be named `cypress.config.{js,ts,cjs,mjs}` (or legacy [`cypress.json`](https://github.com/cypress-io/cypress/blob/main/cypress.json)), with detection logic implemented in the `scaffold-config` package.**

The `cypress-io/cypress` repository expects Cypress configuration files to reside in a specific location for automatic discovery. By default, Cypress searches the project root—the directory containing your [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json)—and loads the first matching configuration file it finds using the detection utilities in `packages/scaffold-config`.

## Default Location and File Naming Convention

Cypress configuration files must live in the **project root directory**. The framework searches for a single configuration file using a specific naming pattern and imports it with `export default` (ES modules) or `module.exports` (CommonJS).

### Supported File Extensions

The modern, preferred filename accepts four extensions:

- [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js)
- [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts)
- `cypress.config.cjs`
- `cypress.config.mjs`

When Cypress starts, it walks the project root and loads the first file that matches one of these names. All variants are imported dynamically using `require` or dynamic `import` depending on the file type.

## How Detection Works in the Source Code

The detection and loading process involves three key areas of the Cypress codebase:

**[`packages/scaffold-config/src/detect.ts`](https://github.com/cypress-io/cypress/blob/main/packages/scaffold-config/src/detect.ts)**  
This file contains the helper that decides which configuration file to read. It checks for the existence of [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js), [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts), `cypress.config.cjs`, or `cypress.config.mjs` in the project root, falling back to the legacy [`cypress.json`](https://github.com/cypress-io/cypress/blob/main/cypress.json) if necessary.

**[`packages/server/lib/util/settings.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/util/settings.ts)**  
Once detected, the server resolves the absolute path to the configuration file and loads it via `require` or dynamic `import`.

**[`packages/server/lib/project-base.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/project-base.ts)**  
This module combines the user-provided configuration with Cypress defaults and makes the merged configuration available to the rest of the system.

## Legacy Support for cypress.json

While the modern configuration format uses `cypress.config.*`, Cypress still recognizes the legacy [`cypress.json`](https://github.com/cypress-io/cypress/blob/main/cypress.json) file for backward compatibility. However, this legacy format is **ignored by the new `defineConfig` flow** and will be removed in a future major release. New projects should migrate to the JavaScript or TypeScript configuration format.

## Custom Configuration File Paths

If you need to store your configuration file outside the project root or use a custom filename, use the `--config-file` CLI flag:

```bash
cypress run --config-file=custom/config/my-config.cjs

```

This overrides the default detection logic and points Cypress directly to your specified file.

## Configuration File Examples

### TypeScript Configuration (Recommended)

```typescript
// cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.{js,ts,jsx,tsx}',
  },
})

```

### JavaScript Configuration (CommonJS)

```javascript
// cypress.config.js
module.exports = {
  component: {
    devServer: {
      framework: 'react',
      bundler: 'webpack',
    },
  },
}

```

### CLI with Custom Config Path

```bash

# Explicitly point Cypress at a different config file

cypress run --config-file=custom/config/my-config.cjs

```

## Summary

- **Cypress configuration files** must be stored in the project root directory (alongside [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json)).
- The framework automatically detects `cypress.config.{js,ts,cjs,mjs}` using logic in [`packages/scaffold-config/src/detect.ts`](https://github.com/cypress-io/cypress/blob/main/packages/scaffold-config/src/detect.ts).
- Detection order prioritizes the modern config format, with legacy [`cypress.json`](https://github.com/cypress-io/cypress/blob/main/cypress.json) as a fallback.
- The server loads the resolved file via [`packages/server/lib/util/settings.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/util/settings.ts) and processes it through [`packages/server/lib/project-base.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/project-base.ts).
- Use the `--config-file` CLI flag to specify non-standard locations or filenames.

## Frequently Asked Questions

### What is the default location for Cypress configuration files?

By default, Cypress configuration files are stored in the **project root directory**, which is the same folder containing your [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json). The framework automatically searches this directory for [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js), [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts), `cypress.config.cjs`, or `cypress.config.mjs`.

### What file extensions are supported for Cypress configuration files?

Cypress supports four extensions for the modern configuration format: `.js`, `.ts`, `.cjs`, and `.mjs`. The detection logic in [`packages/scaffold-config/src/detect.ts`](https://github.com/cypress-io/cypress/blob/main/packages/scaffold-config/src/detect.ts) checks for these files in order, and the server loads the first match it finds using the appropriate import method for the file type.

### How do I use a custom path for my Cypress configuration file?

Use the `--config-file` CLI flag to specify a custom path. For example, `cypress run --config-file=custom/config/my-config.cjs` tells Cypress to look for the configuration file at that specific location rather than in the project root, bypassing the automatic detection logic.

### Is cypress.json still supported in Cypress v10+?

Yes, [`cypress.json`](https://github.com/cypress-io/cypress/blob/main/cypress.json) is still recognized for backward compatibility, but it is considered deprecated. The legacy format is ignored by the new `defineConfig` helper and will be removed in a future major release. New projects should use [`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) with the `defineConfig` export pattern.