Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

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.

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"

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.

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

  2. Add key-value pairs:

    .dev.vars/.env
    API_HOST="localhost:3000"
    DEBUG="true"
    SECRET_TOKEN="my-local-secret-token"

  3. 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.

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

  2. Add key-value pairs:

    .dev.vars.staging/.env.staging
    API_HOST="staging.localhost:3000"
    DEBUG="false"
    SECRET_TOKEN="staging-token"

  3. 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