{
  "doc": {
    "id": "api/node-events/configuration-api",
    "title": "Configuration API",
    "description": "Modify configuration values and environment variables from your Cypress configuration.",
    "section": "api",
    "source_path": "/llm/markdown/api/node-events/configuration-api.md",
    "version": "f60251bf707b0077a9535579c9f90d615440cc35",
    "updated_at": "2026-10-16T10:56:58.670Z",
    "headings": [
      {
        "id": "api/node-events/configuration-api#configuration-api",
        "text": "Configuration API",
        "level": 1
      },
      {
        "id": "api/node-events/configuration-api#usage",
        "text": "Usage",
        "level": 2
      },
      {
        "id": "api/node-events/configuration-api#promises",
        "text": "Promises",
        "level": 3
      },
      {
        "id": "api/node-events/configuration-api#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/node-events/configuration-api#customize-available-browsers",
        "text": "Customize available browsers",
        "level": 3
      },
      {
        "id": "api/node-events/configuration-api#switch-between-multiple-configuration-files",
        "text": "Switch between multiple configuration files",
        "level": 3
      },
      {
        "id": "api/node-events/configuration-api#test-type-specific-plugins",
        "text": "Test Type-Specific Plugins",
        "level": 3
      },
      {
        "id": "api/node-events/configuration-api#history",
        "text": "History",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "Configuration API"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress enables you to dynamically modify configuration values and environment variables from your Cypress configuration."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Usage"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "⚠️ This code is part of the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin",
            "children": [
              {
                "type": "text",
                "value": "setupNodeEvents"
              }
            ]
          },
          {
            "type": "text",
            "value": " function and thus executes in the Node environment. You cannot call `Cypress` or `cy` commands in this function, but you do have the direct access to the file system and the rest of the operating system."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To modify configuration, you return a config object from `setupNodeEvents` within this exported function."
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "cypress.config.js"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "cypress.config.ts"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const { defineConfig } = require('cypress')\n\nmodule.exports = defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      console.log(config) // see everything in here!\n\n      // modify config values\n      config.defaultCommandTimeout = 10000\n      config.baseUrl = 'https://staging.acme.com'\n\n      // modify env var value\n      config.env.ENVIRONMENT = 'staging'\n\n      // IMPORTANT return the updated config object\n      return config\n    },\n  },\n})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'\n\nexport default defineConfig({\n  // setupNodeEvents can be defined in either\n  // the e2e or component configuration\n  e2e: {\n    setupNodeEvents(on, config) {\n      console.log(config) // see everything in here!\n\n      // modify config values\n      config.defaultCommandTimeout = 10000\n      config.baseUrl = 'https://staging.acme.com'\n\n      // modify env var value\n      config.env.ENVIRONMENT = 'staging'\n\n      // IMPORTANT return the updated config object\n      return config\n    },\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Whenever you return an object from your `setupNodeEvents` function, Cypress will take this and \"diff\" it against the original configuration and automatically set the resolved values to point to what you returned."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you don't return an object, then configuration will not be modified."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The `config` object also includes the following extra values that are not part of the standard configuration. These values are read only and cannot be modified from the `setupNodeEvents` function in the Cypress configuration."
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`configFile`: The absolute path to the Cypress configuration file. See the "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/command-line.md#cypress-open",
                    "children": [
                      {
                        "type": "text",
                        "value": "--config-file"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " and "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/module-api.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "configFile"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " docs for more information on this value."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`projectRoot`: The absolute path to the root of the project (e.g. `/Users/me/dev/my-project`)."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Resolved values will show up in the \"Settings\" tab."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Promises"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Additionally, Cypress will respect and await promises you return. This enables you to perform asynchronous tasks and eventually resolve with the modified configuration object. See the "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Switch-between-multiple-configuration-files",
            "children": [
              {
                "type": "text",
                "value": "example on switching between multiple configuration files"
              }
            ]
          },
          {
            "type": "text",
            "value": " for a full example."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Customize available browsers"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The configuration includes the list of browsers found on your system that are available to Cypress. You can, for example, change or augment that list for different testing purposes."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Read our full guide on "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/launching-browsers.md",
            "children": [
              {
                "type": "text",
                "value": "Launching Browsers"
              }
            ]
          },
          {
            "type": "text",
            "value": " for more information on how this works."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Switch between multiple configuration files"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This means you can do things like store multiple configuration files and switch between them like:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cypress.qa.json`"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cypress.dev.json`"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cypress.prod.json`"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "How you choose to organize your configuration and environment variables is up to you."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// promisified fs module\nconst fs = require('fs-extra')\nconst path = require('path')\n\nfunction getConfigurationByFile(file, projectRoot) {\n  const pathToConfigFile = path.join(\n    projectRoot,\n    'cypress',\n    'config',\n    `${file}.json`\n  )\n\n  return fs.readJson(pathToConfigFile)\n}\n\n// cypress.config.js or cypress.config.ts\nmodule.exports = {\n  e2e: {\n    setupNodeEvents(on, config) {\n      // accept a environment value or use development by default\n      const file = config.env.environment || 'development'\n\n      return getConfigurationByFile(file, config.projectRoot)\n    },\n  },\n}"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You could now swap out configuration + environment variables like so:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cypress run"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cypress run --env environment=qa"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cypress run --env environment=staging"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cypress run --env environment=production"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Each of these environments would read in the configuration at these files:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cypress/config/development.json\ncypress/config/qa.json\ncypress/config/staging.json\ncypress/config/production.json"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This would enable you to do things like this:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/config/development.json\n\n{\n  \"baseUrl\": \"http://localhost:1234\",\n  \"env\": {\n    \"something\": \"development\"\n  }\n}"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/config/qa.json\n\n{\n  \"baseUrl\": \"https://qa.acme.com\",\n  \"env\": {\n    \"something\": \"qa\"\n  }\n}"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/config/staging.json\n\n{\n  \"baseUrl\": \"https://staging.acme.com\",\n  \"env\": {\n    \"something\": \"staging\"\n  }\n}"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/config/production.json\n\n{\n  \"baseUrl\": \"https://production.acme.com\",\n  \"env\": {\n    \"something\": \"production\"\n  }\n}"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This is a less complicated example. Remember - you have the full power of Node at your disposal."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "How you choose to edit the configuration is up to you. You don't have to read off of the file system - you could store them all in memory inside of "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin",
            "children": [
              {
                "type": "text",
                "value": "setupNodeEvents"
              }
            ]
          },
          {
            "type": "text",
            "value": " if you wanted."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Test Type-Specific Plugins"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can access the type of tests running via the `config.testingType` property. The testing type is either `e2e` or `component` depending on if the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/testing-types.md#What-is-E2E-Testing",
            "children": [
              {
                "type": "text",
                "value": "E2E Testing"
              }
            ]
          },
          {
            "type": "text",
            "value": " or "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/testing-types.md#What-is-Component-Testing",
            "children": [
              {
                "type": "text",
                "value": "Component Testing"
              }
            ]
          },
          {
            "type": "text",
            "value": " type was selected in the Cypress Launchpad. Use this property to configure test type-specific plugins."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "History"
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Version"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Changes"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "7.0.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `testingType` property to `config`."
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 1016
}