Skip to content
Cloudflare Docs

Environment variables and secrets

During local development, you may need to configure environment variables (such as API URLs, feature flags) and secrets (API tokens, private keys). You can use a .dev.vars file in the root of your project to override environment variables for local development, and both Wrangler and the Vite plugin will respect this override.

Why use a .dev.vars file?

Use .dev.vars to set local overrides for environment variables that should not be checked into your repository.

If you want to manage environment-based configuration that you want checked into your repository (for example, non-sensitive or shared environment defaults), you can define environment variables as [vars] in your Wrangler configuration. Using a .dev.vars file is specifically for local-only secrets or configuration that you do not want in version control and only want to inject in local dev sessions.

Basic setup

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

  2. Add key-value pairs:

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

  3. Run your dev command

    Wrangler

    Terminal window
    npx wrangler dev

    Vite plugin

    Terminal window
    npx vite dev

Multiple local environments with .dev.vars

To simulate different local environments, you can:

  1. Create a file named .dev.vars.<environment-name> . For example, we'll use .dev.vars.staging.

  2. Add key-value pairs:

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

  3. Specify the environment when running the dev command:

    Wrangler

    Terminal window
    npx wrangler dev --env staging

    Vite plugin

    Terminal window
    CLOUDFLARE_ENV=staging npx vite dev

    Only the values from .dev.vars.staging will be applied instead of .dev.vars.

Learn more