How to Configure Cypress with the Configuration File

Direct answer: Create cypress.config.js or cypress.config.ts in your project root and export a configuration object. Put settings shared across testing types at the top level, E2E settings under e2e, and Component Testing settings under component. Use setupNodeEvents for Node-side hooks or configuration that must be computed when Cypress starts.

The examples below use CommonJS for JavaScript. Cypress also supports TypeScript and ECMAScript modules; choose syntax that matches your project’s Node module settings. Check the Cypress configuration reference for the exact options and defaults supported by your installed Cypress version.

1. Create the configuration file

For a simple E2E project, create cypress.config.js in the project root:

const { defineConfig } = require('cypress')

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

Replace the example URL with your application’s local or test environment URL. defineConfig() is recommended because it provides editor completion, but Cypress can parse the configuration without it.

The equivalent TypeScript/ESM shape is:

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:8080',
  },
})

Use a module format compatible with your project. In a project with "type": "module", a CommonJS config can use the .cjs extension. An ESM config in a CommonJS project can use .mjs or the project can be configured as a module.

2. Put each option at the right level

Options at the top level apply generally. Options under e2e or component are specific to that testing type. For example:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  defaultCommandTimeout: 5000,
  e2e: {
    baseUrl: 'http://localhost:8080',
    setupNodeEvents(on, config) {
      // Register Node-side event handlers here.
      return config
    },
  },
  component: {
    // Component Testing options belong here, including devServer
    // and indexHtmlFile when your component setup needs them.
  },
})

Setting scope	Examples	Use it for
Top level	defaultCommandTimeout	Values shared across testing types unless overridden.
e2e	baseUrl, specPattern, support file	Browser application end-to-end tests.
component	devServer, indexHtmlFile	Component runner and development server setup.
e2e.setupNodeEvents or component.setupNodeEvents	Event registration and dynamic config	Work that must run in Node when Cypress starts.

Do not assume an option’s default from an older project or guide. For example, the current reference describes defaults such as a null baseUrl, an E2E spec pattern, and enabled test isolation; defaults can change between versions.

3. Set baseUrl for relative application URLs

Set e2e.baseUrl when tests visit the same application origin. Cypress prefixes relative URLs passed to cy.visit() and cy.request() with this value.

const { defineConfig } = require('cypress')

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

// In a spec file
cy.visit('/')
cy.request('/api/health')

Use an absolute URL in a test when it deliberately targets a different host. A relative URL without the expected base URL often indicates that the option is missing, placed outside the e2e block, or overridden for that run.

4. Choose how to override configuration

Keep stable project defaults in the config file. Choose an override mechanism based on how broad and temporary the change is:

Mechanism	Scope	Good fit
Project config	Normal project runs	Shared defaults and checked-in settings.
--config	One CLI run	Temporarily changing one or more configuration values.
--config-file	One CLI run	Selecting a different configuration file.
CYPRESS_* OS variables	Environment or CI job	Environment-specific matching configuration values.
Runtime test overrides	Test or suite	Settings needed only for a specific test scope.

For example, change the viewport for one run or select another file:

npx cypress run --config viewportWidth=1280,viewportHeight=720
npx cypress run --config-file tests/cypress.config.js

Environment variables can also override matching config values. Cypress documents names such as CYPRESS_VIEWPORT_WIDTH and CYPRESS_VIEWPORT_HEIGHT. Check the configuration reference for precedence and supported names when combining sources.

5. Configure environment values and secrets

Cypress supports values through the config’s env object, cypress.env.json, operating-system variables, the --env CLI option, and setupNodeEvents. Use environment-specific input for secrets rather than committing credentials into a tracked config file.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:8080',
    env: {
      apiKey: process.env.API_KEY,
    },
  },
})

Provide API_KEY in the shell or CI secret store before starting Cypress. Cypress’s environment-variable guide explains the supported inputs and how values are exposed to tests: Environment variables and secrets in Cypress.

6. Use setupNodeEvents for Node-side work

setupNodeEvents(on, config) runs in Node. Use it to register event handlers or read Node-accessible resources and adjust the configuration dynamically. It is not browser-side test code: do not call Cypress or cy commands inside it. Return the config object so Cypress can apply changes.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      if (process.env.CI) {
        config.video = false
      }

      return config
    },
  },
})

The example shows where dynamic logic belongs; choose options supported by your installed Cypress version. See the Configuration API for the callback contract and details.

7. Configure Component Testing separately

Component Testing has its own configuration block. Put its dev server and component runner settings there rather than under e2e. The exact dev server configuration depends on the framework and bundler used by the project, so use the matching Cypress Component Testing setup guide and current reference rather than copying an unrelated server example.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    // Add the framework-appropriate devServer configuration here.
    // Add indexHtmlFile here if your setup requires a custom one.
  },
})

8. Migrate older plugin configuration

Older Cypress projects may have a cypress/plugins/index.js file. The migration guide says that file is no longer loaded automatically; move plugin behavior into setupNodeEvents in the config. Review the migration guide for the specific version you are upgrading from: Cypress migration guide.

9. Troubleshoot common configuration problems

Symptom	Likely cause	Fix
Cypress does not load the file	The file is not at the expected project location, its name or extension is wrong, or its module syntax conflicts with package settings.	Check the project root and configured config-file path. Match CommonJS/ESM syntax to the project; use .cjs or .mjs where appropriate.
cy.visit('/') goes to the wrong place or fails	baseUrl is missing, misspelled, overridden, or outside e2e.	Set e2e.baseUrl, confirm the app is running at that address, and inspect CLI and environment overrides.
A setting works for E2E but not Component Testing	The option was placed in the wrong testing-type block.	Move it to the relevant e2e or component block, or to the top level only if it is shared.
A plugin file no longer runs	An older plugins file is not automatically loaded in current Cypress versions.	Move its Node event handlers into setupNodeEvents and return the config if modified.
Cypress or cy is undefined in setupNodeEvents	Node-side setup was written as if it were browser test code.	Use Node APIs and the provided on and config arguments; reserve cy commands for specs and support code.
A secret is missing in a test	The variable was not defined in the shell/CI environment, or it was read from a different supported env source than expected.	Define it before Cypress starts, check the variable name and chosen input path, and avoid placing secrets in committed files.
Editing config closes the browser	Cypress restarts after a configuration file change.	Expect the open browser to close and Cypress to reboot after edits, then rerun the relevant spec.

10. Keep runs predictable and efficient

• Keep stable settings in one shared config. Use overrides for genuinely different environments or one-off runs; this makes the effective value easier to trace.
• Inspect all configuration sources. A checked-in value may be superseded by a CLI option or environment variable, especially in CI.
• Use the narrowest appropriate scope. A test-only need belongs in a test or suite override; a project-wide default belongs in config.
• Keep secrets out of source control. Read them from the environment or another managed secret input.
• Link version-sensitive decisions to the live reference. Defaults and supported options change; confirm against the Cypress version installed in the project.

Configuration itself does not make a slow test faster. It can prevent wasted work by targeting the right app URL and specs, and by avoiding conflicting values that cause retries or failed setup. For reliable CI, make the app endpoint and required environment values explicit for each job.

Or skip the browser setup

If the task is to capture a page rather than run browser tests, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF; see the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' })
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`)

• Cookie banners are accepted and removed before capture; known consent platforms, newsletter popups, and chat widgets can also be removed.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Response headers report the page verdict and billing status.
• An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
• 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000.

Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does Cypress require defineConfig()?

No. Cypress recommends it for editor completion, but it is not required to parse the configuration.

Can I use separate config files for local and CI runs?

Yes. Select another file with --config-file, or keep a shared file and apply environment or CLI overrides.

Where do I find the full list of options?

Use the live Cypress configuration reference for options, defaults, and version-sensitive behavior.

Sources

• Configuration in Cypress
• Environment variables and secrets in Cypress
• Configuration API
• Effective E2E testing in Cypress
• Cypress migration guide