← Workers / workers / local-development

Environment variables and secrets

Put secrets for use in local development in either a .dev.vars file or a .env file, in the same directory as the Wrangler configuration file.

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

.dev.vars / .env

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

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)

Basic setup

Here are steps to set up environment variables for local development using either .dev.vars or .env files.

Create a .dev.vars / .env file in your project root.

Add key-value pairs:

.dev.vars/.env

API_HOST="localhost:3000"
DEBUG="true"
SECRET_TOKEN="my-local-secret-token"

Run your dev command

Wrangler
npx wrangler dev
Vite plugin
npx vite dev

Multiple local environments

To simulate different local environments, you can provide environment-specific files. For example, you might have a staging environment that requires different settings than your development environment.

Create a file named .dev.vars.<environment-name>/.env.<environment-name>. For example, we can use .dev.vars.staging/.env.staging.

Add key-value pairs:

.dev.vars.staging/.env.staging

API_HOST="staging.localhost:3000"
DEBUG="false"
SECRET_TOKEN="staging-token"

Specify the environment when running the dev command:

Wrangler
npx wrangler dev --env staging
Vite plugin
CLOUDFLARE_ENV=staging npx vite dev
- If using .dev.vars.staging, only the values from that file will be applied instead of .dev.vars.
- If using .env.staging, the values will be merged with .env files, with the most specific file taking precedence.

Learn more

To learn how to configure multiple environments in Wrangler configuration, read the documentation.
To learn how to use Wrangler environments and Vite environments together, read the Vite plugin documentation