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

Cypress configuration files are stored in the project root directory and must be named cypress.config.{js,ts,cjs,mjs} (or legacy 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—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
• 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
This file contains the helper that decides which configuration file to read. It checks for the existence of cypress.config.js, cypress.config.ts, cypress.config.cjs, or cypress.config.mjs in the project root, falling back to the legacy cypress.json if necessary.

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
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 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:

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)

// 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)

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

CLI with Custom Config Path

# 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).
• The framework automatically detects cypress.config.{js,ts,cjs,mjs} using logic in packages/scaffold-config/src/detect.ts.
• Detection order prioritizes the modern config format, with legacy cypress.json as a fallback.
• The server loads the resolved file via packages/server/lib/util/settings.ts and processes it through 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. The framework automatically searches this directory for cypress.config.js, 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 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 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 or cypress.config.ts with the defineConfig export pattern.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}