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?

While .dev.vars is commonly used for storing secrets, the file is really just a local override for any environment variable — secret or otherwise. This allows you to avoid polluting environment variables in your Wrangler configuration, and provide a way to set local-only values.

You can also define environment variables as [vars] in your Wrangler configuration (for development, staging, production, etc). This is a good way to manage environment-based configuration that you want checked into your repository (for example, non-sensitive or shared environment defaults). 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
    npm run 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. Run your dev command with an --env flag:

    Wrangler

    Terminal window
    npx wrangler dev --env staging

    Vite plugin

    Terminal window
    npm run dev --env staging

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

Learn more