Cypress App

Cypress Configuration

Launching Cypress for the first time, you will be guided through a wizard that will create a Cypress configuration file for you. This file will be cypress.config.js for JavaScript apps or cypress.config.ts for TypeScript apps. This file is used to store any configuration specific to Cypress.

Cypress additionally supports config files with .mjs and .cjs extensions.

A .mjs file supports ESM syntax in your config without the need of a transpiler step.

A .cjs file uses CommonJS module syntax, which is the default for JavaScript files. All JavaScript config examples in our docs use the CommonJS format.

For TypeScript config files (.ts, .mts, .cts), see TypeScript Support.

If you configure your tests to record the results to Cypress Cloud the projectId will be stored in the config file as well.

ESM vs CommonJS

Starting in Cypress 15.17.0, Cypress determines whether your config loads as ESM or CommonJS before running it, using the same rules as Node.js. Cypress then loads the file with only import() (ESM) or require() (CommonJS) and does not fall back to the other format if loading fails.

The same rules apply to plugin code in setupNodeEvents — Cypress evaluates your config and plugins in a Node.js child process, so the module system for that file determines which APIs are available (for example import.meta.resolve in ESM or require() in CommonJS).

Config file extension	Nearest package.json "type"	Loaded as
.mjs	(any)	ESM
.cjs	(any)	CommonJS
.js	"module"	ESM
.js	omitted or "commonjs"	CommonJS

Cypress walks up from the config file to find the nearest package.json. If a parent directory has its own package.json without "type": "module", that scope wins over an ancestor that is ESM-only.

Use the file extension and package.json "type" that match how the config is written:

• ESM config — use import / export default and ESM-only APIs such as import.meta.resolve and import.meta.dirname:

cypress.config.js (ESM project)

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // import.meta is available in ESM configs
      return config
    },
  },
})

• CommonJS config — use require() and module.exports:

cypress.config.js (CommonJS project)

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // require() is available in CommonJS configs
      return config
    },
  },
})

If your project has "type": "module" but you need CommonJS syntax in the config, rename the file to cypress.config.cjs. If your project is CommonJS but you want ESM syntax, use cypress.config.mjs or set "type": "module" in package.json.

To call CommonJS-only dependencies from an ESM config (or the reverse), use Node's interoperability helpers — for example createRequire(import.meta.url) to require() from an ESM file.

caution

Configs that previously loaded only because Cypress retried the alternate module format may now fail with a clear load error. That behavior is intentional: it matches Node.js and ensures ESM-only APIs such as import.meta.resolve work reliably in config and plugin code.

Intelligent Code Completion

The defineConfig helper function is exported by Cypress, and it provides automatic code completion for configuration in many popular code editors. While it's not strictly necessary for Cypress to parse your configuration, we recommend wrapping your config object with defineConfig() like this:

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:1234',
  },
})

cypress.config.ts

import { defineConfig