{
  "doc": {
    "id": "api/node-events/configuration-api",
    "title": "Configuration API in Node Events",
    "description": "Modify configuration values and environment variables from your Cypress configuration.",
    "section": "api",
    "source_path": "/llm/markdown/api/node-events/configuration-api.md",
    "version": "29b099a83033817a9072f7deec58409720b52bc4",
    "updated_at": "2026-05-03T15:21:58.370Z",
    "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')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      console.log(config) // see everything in here!      // modify config values      config.defaultCommandTimeout = 10000      config.baseUrl = 'https://staging.acme.com'      // modify env var value      config.env.ENVIRONMENT = 'staging'      // IMPORTANT return the updated config object      return config    },  },})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      console.log(config) // see everything in here!      // modify config values      config.defaultCommandTimeout = 10000      config.baseUrl = 'https://staging.acme.com'      // modify env var value      config.env.ENVIRONMENT = 'staging'      // IMPORTANT return the updated config object      return config    },  },})"
      },
      {
        "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 moduleconst fs = require('fs-extra')const path = require('path')function getConfigurationByFile(file, projectRoot) {  const pathToConfigFile = path.join(    projectRoot,    'cypress',    'config',    `${file}.json`  )  return fs.readJson(pathToConfigFile)}// cypress.config.js or cypress.config.tsmodule.exports = {  e2e: {    setupNodeEvents(on, config) {      // accept a environment value or use development by default      const file = config.env.environment || 'development'      return getConfigurationByFile(file, config.projectRoot)    },  },}"
      },
      {
        "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.jsoncypress/config/qa.jsoncypress/config/staging.jsoncypress/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{  \"baseUrl\": \"http://localhost:1234\",  \"env\": {    \"something\": \"development\"  }}"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/config/qa.json{  \"baseUrl\": \"https://qa.acme.com\",  \"env\": {    \"something\": \"qa\"  }}"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/config/staging.json{  \"baseUrl\": \"https://staging.acme.com\",  \"env\": {    \"something\": \"staging\"  }}"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// cypress/config/production.json{  \"baseUrl\": \"https://production.acme.com\",  \"env\": {    \"something\": \"production\"  }}"
      },
      {
        "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. This allows you 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": 987
}