--- id: api/cypress-api/expose title: Cypress.expose | Cypress Documentation description: >- Read and write public configuration values in Cypress using Cypress.expose(). Learn syntax, examples, security considerations, and how it differs from cy.env(). section: api source_path: docs/api/cypress-api/expose.mdx version: 29b099a83033817a9072f7deec58409720b52bc4 updated_at: '2026-05-03T15:21:58.370Z' --- # Cypress.expose Get and set public configuration in your tests. `Cypress.expose()` provides synchronous access to configuration that is safe to expose in the browser context. It may be used for feature flags, plugin configuration, and other public values that need to be available outside of Cypress command chains. **Security considerations** `Cypress.expose()` is intended for **public/non-sensitive** configuration values only. Values set with `Cypress.expose()` are accessible in the browser context, including to application code, third-party scripts, and browser extensions. **Do NOT** store sensitive data (API keys, passwords, tokens, etc.) using `Cypress.expose()`. Use [`cy.env()`](/llm/markdown/api/commands/env.md) for sensitive values. ## Syntax ``` Cypress.expose()Cypress.expose(key)Cypress.expose(key, value)Cypress.expose(object) ``` ### Arguments **key _(String)_** The name of the exposed configuration variable to get or set. **value _(any)_** The value of the exposed configuration variable to set. Can be any serializable type (string, number, boolean, object, etc.). **object _(Object)_** Set multiple exposed configuration variables with an object literal. Values are merged with existing values. ## Examples ### Get all exposed configuration variables * cypress.config.js * cypress.config.ts ``` const { defineConfig } = require('cypress')module.exports = defineConfig({ expose: { pluginConfig: 'value1', featureFlag: true, apiVersion: 2, },}) ``` ``` import { defineConfig } from 'cypress'export default defineConfig({ expose: { pluginConfig: 'value1', featureFlag: true, apiVersion: 2, },}) ``` ``` Cypress.expose() // => {pluginConfig: 'value1', featureFlag: true, apiVersion: 2} ``` ### Get a single exposed configuration variable * cypress.config.js * cypress.config.ts ``` const { defineConfig } = require('cypress')module.exports = defineConfig({ expose: { pluginConfig: 'my-plugin-config', featureFlag: true, },}) ``` ``` import { defineConfig } from 'cypress'export default defineConfig({ expose: { pluginConfig: 'my-plugin-config', featureFlag: true, },}) ``` ``` Cypress.expose('pluginConfig') // => "my-plugin-config"Cypress.expose('featureFlag') // => trueCypress.expose('nonExistent') // => undefined ``` ### Set a single exposed configuration variable Changes made with `Cypress.expose()` apply only for the remainder of the _current spec file_. * cypress.config.js * cypress.config.ts ``` const { defineConfig } = require('cypress')module.exports = defineConfig({ expose: { pluginConfig: 'initial-value', },}) ``` ``` import { defineConfig } from 'cypress'export default defineConfig({ expose: { pluginConfig: 'initial-value', },}) ``` ``` Cypress.expose('pluginConfig', 'updated-value')Cypress.expose('pluginConfig') // => "updated-value" ``` #### Set multiple exposed values * cypress.config.js * cypress.config.ts ``` const { defineConfig } = require('cypress')module.exports = defineConfig({ expose: { pluginConfig: 'initial-value', featureFlag: false, },}) ``` ``` import { defineConfig } from 'cypress'export default defineConfig({ expose: { pluginConfig: 'initial-value', featureFlag: false, },}) ``` ``` Cypress.expose({ pluginConfig: 'updated-value', featureFlag: true,})Cypress.expose() // => {pluginConfig: 'updated-value', featureFlag: true} ``` ## Configuration sources Read the [Environment Variables & Secrets](/llm/markdown/app/guides/environment-variables.md) guide for more details. ### Cypress configuration file Exposed configuration variables can be set in your [Cypress configuration](/llm/markdown/app/references/configuration.md) file: * cypress.config.js * cypress.config.ts ``` const { defineConfig } = require('cypress')module.exports = defineConfig({ expose: { pluginConfig: 'foo', featureFlag: true, apiVersion: 1, },}) ``` ``` import { defineConfig } from 'cypress'export default defineConfig({ expose: { pluginConfig: 'foo', featureFlag: true, apiVersion: 1, },}) ``` ``` // In your test or support fileconst pluginConfig = Cypress.expose('pluginConfig') // => "foo"const featureFlag = Cypress.expose('featureFlag') // => trueconst apiVersion = Cypress.expose('API_VERSION') // => 1 ``` ### CLI Flags You can set exposed configuration variables using the `--expose` or `-x` CLI flags. CLI values override configuration file values. ``` cypress run --expose pluginConfig=foo,featureFlag=true,API_VERSION=1 ``` Or using the short form: ``` cypress run -x pluginConfig=foo,featureFlag=true,API_VERSION=1 ``` ## Common use cases ### Use Cypress.expose() in plugins or support files `Cypress.expose()` is ideal when configuration is needed outside of Cypress command chains: ``` // cypress/support/commands.js or plugin codeconst pluginConfig = Cypress.expose('pluginConfig')if (pluginConfig === 'enabled') { initializePlugin(pluginConfig)} ``` ## Migrate from Cypress.env() to Cypress.expose() If you're migrating a plugin from `Cypress.env()` to `Cypress.expose()`, the API is similar: **Before (using deprecated `Cypress.env()`):** ``` const config = Cypress.env('PLUGIN_CONFIG') ``` **After (using `Cypress.expose()`):** ``` const config = Cypress.expose('PLUGIN_CONFIG') ``` Update your configuration file: **Before:** ``` { env: { PLUGIN_CONFIG: 'value', },} ``` **After:** ``` { expose: { PLUGIN_CONFIG: 'value', },} ``` ## Notes ### When to use `cy.env()` vs `Cypress.expose()` Both [`cy.env()`](/llm/markdown/api/commands/env.md) and [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md) provide access to configuration values in Cypress, but they serve different security and execution needs. Choosing the right API helps avoid accidental exposure of sensitive data and keeps configuration intent clear. #### Use Cypress.expose() for public configuration Recommended when: * **Values are public or non-sensitive** - Examples include feature flags, API versions, environment labels, or plugin configuration that is safe to appear in browser state. * **Synchronous access is needed** - `Cypress.expose()` returns values immediately, without requiring Cypress command chaining. #### Use `cy.env()` for sensitive or secret values Choose `cy.env()` when security, scoping, and controlled access matter. Recommended when: * **Values are sensitive** - API keys, passwords, tokens, or any data that should not be broadly exposed to the browser. * **Security is a priority** - `cy.env()` only exposes the variables you explicitly request and does not automatically serialize them into browser state. * **You're already working within Cypress command chains**: `cy.env()` is asynchronous and designed to be used inside Cypress tests and hooks. **Example: choosing the right API** ``` // ✅ Use cy.env() for sensitive valuescy.env(['apiKey']).then(({ apiKey }) => { cy.request({ url: 'https://api.example.com/users', headers: { Authorization: `Bearer ${apiKey}` }, })})// ✅ Use Cypress.expose() for public configurationconst apiVersion = Cypress.expose('apiVersion') // Synchronous, public valueconst featureFlag = Cypress.expose('featureFlag') // Safe to expose in browser ``` See [`cy.env()`](/llm/markdown/api/commands/env.md) for more details. ### Scope and lifecycle limitations * Exposed values persist only while the browser is open. * Runtime changes apply only within the current spec file * Values do not propagate back to Node.js contexts such as `setupNodeEvents` ## History | Version | Changes | | --- | --- | | [15.10.0](/llm/markdown/app/references/changelog.md#15-10-0) | `Cypress.expose()` API introduced | ## See also * [`cy.env()`](/llm/markdown/api/commands/env.md) * [`Cypress.env()`](/llm/markdown/api/cypress-api/env.md) - Deprecated API * [Migration Guide to `cy.env()`](/llm/markdown/app/references/migration-guide.md#Migrating-away-from-Cypressenv) - Guide for migrating from `Cypress.env()` * [Configuration options](/llm/markdown/app/references/configuration.md)