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.

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.

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

2. Add key-value pairs:

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

3. Run your dev command

   Wrangler

   • npm
   • pnpm
   • yarn

   npx wrangler dev

   Vite plugin

   • npm
   • pnpm
   • yarn

   npx vite dev

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:

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

3. Specify the environment when running the dev command:

   Wrangler

   • npm
   • pnpm
   • yarn

   npx wrangler dev --env staging

   Vite plugin

   • npm
   • pnpm
   • yarn

   CLOUDFLARE_ENV=staging npx vite dev

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

• 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