Cloudflare Environments

A Worker config file may contain configuration for multiple Cloudflare environments. With the Cloudflare Vite plugin, you select a Cloudflare environment at dev or build time by providing the CLOUDFLARE_ENV environment variable. Consider the following example Worker config file:

wrangler.jsonc

{
  "name": "my-worker",
  "compatibility_date": "2025-04-03",
  "main": "./src/index.ts",
  "vars": {
    "MY_VAR": "Top-level var"
  },
  "env": {
    "staging": {
      "vars": {
        "MY_VAR": "Staging var"
      }
    },
    "production": {
      "vars": {
        "MY_VAR": "Production var"
      }
    }
  }
}

wrangler.toml

name = "my-worker"
compatibility_date = "2025-04-03"
main = "./src/index.ts"

vars = { MY_VAR = "Top-level var" }

[env.staging]
vars = { MY_VAR = "Staging var" }

[env.production]
vars = { MY_VAR = "Production var" }

If you run CLOUDFLARE_ENV=production vite build then the output wrangler.json file generated by the build will be a flattened configuration for the 'production' Cloudflare environment, as shown in the following example:

dist/wrangler.json

{
  "name": "my-worker",
  "compatibility_date": "2025-04-03",
  "main": "index.js",
  "vars": { "MY_VAR": "Production var" }
}

Notice that the value of MY_VAR is Production var. This flattened configuration combines top-level only, inheritable, and non-inheritable keys.

Note

The default Vite environment name for a Worker is always the top-level Worker name. This enables you to reference the Worker consistently in your Vite config when using multiple Cloudflare environments. See Vite Environments for more information.

Cloudflare environments can also be used in development. For example, you could run CLOUDFLARE_ENV=development vite dev. It is common to use the default top-level environment as the development environment and then add additional environments as necessary.

Note

Running vite dev or vite build without providing CLOUDFLARE_ENV will use the default top-level Cloudflare environment. As Cloudflare environments are applied at dev and build time, specifying CLOUDFLARE_ENV when running vite preview or wrangler deploy will have no effect.

Secrets in local development

Warning

Do not use vars to store sensitive information in your Worker's Wrangler configuration file. Use secrets instead.

Put secrets for use in local development in either a .dev.vars file or a .env file, in the root of your project.

Choose to use either .dev.vars or .env but not both. If you define a .dev.vars file, then values in .env files will not be included in the env object during local development.

These files should be formatted using the dotenv ↗ syntax. For example:

.dev.vars / .env

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

Do not commit secrets to git

The .dev.vars and .env files should not committed to git. Add .dev.vars* and .env* to your project's .gitignore file.

To set different secrets for each Cloudflare environment, create files named .dev.vars.<environment-name> or .env.<environment-name>.

When you select a Cloudflare environment in your local development, the corresponding environment-specific file will be loaded ahead of the generic .dev.vars (or .env) file.

• When using .dev.vars.<environment-name> files, all secrets must be defined per environment. If .dev.vars.<environment-name> exists then only this will be loaded; the .dev.vars file will not be loaded.
• In contrast, all matching .env files are loaded and the values are merged. For each variable, the value from the most specific file is used, with the following precedence:
  • .env.<environment-name>.local (most specific)
  • .env.local
  • .env.<environment-name>
  • .env (least specific)

Controlling .env handling

It is possible to control how .env files are loaded in local development by setting environment variables on the process running the tools.

• To disable loading local dev vars from .env files without providing a .dev.vars file, set the CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV environment variable to "false".
• To include every environment variable defined in your system's process environment as a local development variable, ensure there is no .dev.vars and then set the CLOUDFLARE_INCLUDE_PROCESS_ENV environment variable to "true".

Combining Cloudflare environments and Vite modes

You may wish to combine the concepts of Cloudflare environments and Vite modes ↗. With this approach, the Vite mode can be used to select the Cloudflare environment and a single method can be used to determine environment specific configuration and code. Consider again the previous example:

wrangler.jsonc

{
  "name": "my-worker",
  "compatibility_date": "2025-04-03",
  "main": "./src/index.ts",
  "vars": {
    "MY_VAR": "Top-level var"
  },
  "env": {
    "staging": {
      "vars": {
        "MY_VAR": "Staging var"
      }
    },
    "production": {
      "vars": {
        "MY_VAR": "Production var"
      }
    }
  }
}

wrangler.toml

# wrangler.toml

name = "my-worker"
compatibility_date = "2025-04-03"
main = "./src/index.ts"

vars = { MY_VAR = "Top-level var" }

[env.staging]
vars = { MY_VAR = "Staging var" }

[env.production]
vars = { MY_VAR = "Production var" }

Next, provide .env.staging and .env.production files:

.env.staging

CLOUDFLARE_ENV=staging

.env.production

CLOUDFLARE_ENV=production

By default, vite build uses the 'production' Vite mode. Vite will therefore load the .env.production file to get the environment variables that are used in the build. Since the .env.production file contains CLOUDFLARE_ENV=production, the Cloudflare Vite plugin will select the 'production' Cloudflare environment. The value of MY_VAR will therefore be 'Production var'. If you run vite build --mode staging then the 'staging' Vite mode will be used and the 'staging' Cloudflare environment will be selected. The value of MY_VAR will therefore be 'Staging var'.

For more information about using .env files with Vite, see the relevant documentation ↗.