From a1370e2c5acb5ad4287f417ed40c2b5c87d9f13f Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 21 Jul 2025 14:45:34 +0100 Subject: [PATCH 1/8] Document the new .env support for local development --- .../configuration/environment-variables.mdx | 2 ++ .../partials/workers/secrets-in-dev.mdx | 21 ++++++++++++++----- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/src/content/docs/workers/configuration/environment-variables.mdx b/src/content/docs/workers/configuration/environment-variables.mdx index 5942620b9b16c4d..29263e8caf83e7b 100644 --- a/src/content/docs/workers/configuration/environment-variables.mdx +++ b/src/content/docs/workers/configuration/environment-variables.mdx @@ -95,6 +95,8 @@ Select the **Secret** type if your environment variable is a [secret](/workers/c +### Local development with secrets + ## Related resources diff --git a/src/content/partials/workers/secrets-in-dev.mdx b/src/content/partials/workers/secrets-in-dev.mdx index 26718bb522de66c..9a8b47f21a924ed 100644 --- a/src/content/partials/workers/secrets-in-dev.mdx +++ b/src/content/partials/workers/secrets-in-dev.mdx @@ -2,15 +2,26 @@ {} --- -When developing your Worker or Pages Function, create a `.dev.vars` file in the root of your project to define secrets that will be used when running `wrangler dev` or `wrangler pages dev`, as opposed to using environment variables in the [Wrangler configuration file](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables). This works both in local and remote development modes. +To define variables to use in local development that you do not want to store in Wrangler config (for example secrets that are defined for production deployment in [Wrangler configuration file](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables)), create either a `.dev.vars` file, or a `.env` file in the root of your project. +You should use either `.dev.vars` or `.env` but not both. If you define a `.dev.vars` file, then values in `.env` files will be ignored for local development. -The `.dev.vars` file should be formatted like a `dotenv` file, such as `KEY="VALUE"`: +The `.dev.vars` and `.env` files should be formatted using the `dotenv` syntax, such as `KEY="VALUE"`: -```bash title=".dev.vars" +```bash title=".dev.vars / .env" SECRET_KEY="value" API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" ``` -To set different secrets for each environment, create files named `.dev.vars.`. When you use `wrangler --env `, the corresponding environment-specific file will be loaded instead of the `.dev.vars` file. +To set different secrets for each Cloudflare environment, create files named `.dev.vars.` or `.env.`. +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. -Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment. +- When using `.dev.vars.` files, all secrets must be defined per environment. If `.dev.vars.` 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..local` (most specific) + - `.env.local` + - `.env.` + - `.env` (least specific) + +:::note +To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `true`. +::: From 5db8688394db95213c114e7cae07cdb6f87d8ed7 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Wed, 23 Jul 2025 16:16:45 +0100 Subject: [PATCH 2/8] fixup! Document the new .env support for local development --- .../partials/workers/secrets-in-dev.mdx | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/src/content/partials/workers/secrets-in-dev.mdx b/src/content/partials/workers/secrets-in-dev.mdx index 9a8b47f21a924ed..888850fc7bccc1a 100644 --- a/src/content/partials/workers/secrets-in-dev.mdx +++ b/src/content/partials/workers/secrets-in-dev.mdx @@ -2,10 +2,19 @@ {} --- -To define variables to use in local development that you do not want to store in Wrangler config (for example secrets that are defined for production deployment in [Wrangler configuration file](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables)), create either a `.dev.vars` file, or a `.env` file in the root of your project. -You should use either `.dev.vars` or `.env` but not both. If you define a `.dev.vars` file, then values in `.env` files will be ignored for local development. +Put secrets for use in local development in either a `.dev.vars` file or a `.env` file, in the root of your project. -The `.dev.vars` and `.env` files should be formatted using the `dotenv` syntax, such as `KEY="VALUE"`: +:::note +Do not add secrets as `vars` in your Worker's 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 be ignored for local development. + +:::note +The `.dev.vars` and `.env` files should not committed to git. Add `.dev.vars*` and `.env*` to your project's `.gitignore` file. +::: + +These files should be formatted using the [dotenv](https://hexdocs.pm/dotenvy/dotenv-file-format.html) syntax. For example: ```bash title=".dev.vars / .env" SECRET_KEY="value" @@ -13,6 +22,7 @@ API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" ``` To set different secrets for each Cloudflare environment, create files named `.dev.vars.` or `.env.`. + 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.` files, all secrets must be defined per environment. If `.dev.vars.` exists then only this will be loaded; the `.dev.vars` file will not be loaded. @@ -23,5 +33,7 @@ When you select a Cloudflare environment in your local development, the correspo - `.env` (least specific) :::note -To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `true`. +To disable loading local dev vars from `.env` files without providing a `.dev.vars` file, set the `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV` environment variable to `"false"`. + +To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `"true"`. ::: From f4bb9b5cb630f668cff7b6f0de0455cf64683b20 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Wed, 30 Jul 2025 14:15:33 +0100 Subject: [PATCH 3/8] fixup! Document the new .env support for local development --- .../docs/workers/wrangler/environments.mdx | 6 +++++- .../partials/workers/secrets-in-dev.mdx | 18 +++++++++++------- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/src/content/docs/workers/wrangler/environments.mdx b/src/content/docs/workers/wrangler/environments.mdx index 4e118875a586bed..b1802db100c5e5e 100644 --- a/src/content/docs/workers/wrangler/environments.mdx +++ b/src/content/docs/workers/wrangler/environments.mdx @@ -112,12 +112,16 @@ env.staging.service ={ binding = "", service = "worker-a-staging" -### Secrets +### Secrets for production You may assign environment-specific [secrets](/workers/configuration/secrets/) by running the command [`wrangler secret put -env`](/workers/wrangler/commands/#put). You can also create `dotenv` type files named `.dev.vars.`. Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment. +### Secrets in local development + + + --- ## Examples diff --git a/src/content/partials/workers/secrets-in-dev.mdx b/src/content/partials/workers/secrets-in-dev.mdx index 888850fc7bccc1a..6424648cebf01c4 100644 --- a/src/content/partials/workers/secrets-in-dev.mdx +++ b/src/content/partials/workers/secrets-in-dev.mdx @@ -2,16 +2,14 @@ {} --- -Put secrets for use in local development in either a `.dev.vars` file or a `.env` file, in the root of your project. - -:::note -Do not add secrets as `vars` in your Worker's Wrangler configuration file. +:::caution +Do not use `vars` to store sensitive information in your Worker's Wrangler configuration file. Use secrets instead. ::: -Choose to use either `.dev.vars` or `.env` but not both. If you define a `.dev.vars` file, then values in `.env` files will be ignored for local development. +Put secrets for use in local development in either a `.dev.vars` file or a `.env` file, in the root of your project. -:::note -The `.dev.vars` and `.env` files should not committed to git. Add `.dev.vars*` and `.env*` to your project's `.gitignore` file. +:::info +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](https://hexdocs.pm/dotenvy/dotenv-file-format.html) syntax. For example: @@ -21,6 +19,10 @@ SECRET_KEY="value" API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" ``` +:::caution [Do not commit secrets to git] +The `.dev.vars` and `.env` files should not committed to git. Add `.dev.vars*` and `.env*` to your project's `.gitignore` file. +::: + To set different secrets for each Cloudflare environment, create files named `.dev.vars.` or `.env.`. 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. @@ -34,6 +36,8 @@ When you select a Cloudflare environment in your local development, the correspo :::note To disable loading local dev vars from `.env` files without providing a `.dev.vars` file, set the `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV` environment variable to `"false"`. +::: +:::note To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `"true"`. ::: From 6c1bbead9f44610c5643506b01640241a4c9c139 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Wed, 30 Jul 2025 15:07:32 +0100 Subject: [PATCH 4/8] update development-testing/environment-variables page --- .../environment-variables.mdx | 34 ++++++++----------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/src/content/docs/workers/development-testing/environment-variables.mdx b/src/content/docs/workers/development-testing/environment-variables.mdx index fb87831bb69fc8a..a402bc13de222ff 100644 --- a/src/content/docs/workers/development-testing/environment-variables.mdx +++ b/src/content/docs/workers/development-testing/environment-variables.mdx @@ -7,29 +7,21 @@ head: [] description: Configuring environment variables and secrets for local development --- -import { Aside, PackageManagers, Steps } from "~/components"; +import { Aside, PackageManagers, Render, Steps } from "~/components"; -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](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables) and the [Vite plugin](/workers/vite-plugin/reference/secrets/) will respect this override. + - +### Basic setup -### 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]`](/workers/wrangler/environments/#_top) 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 +Here are steps to set up environment variables for local development using either `.dev.vars` or `.env` files. -1. Create a `.dev.vars` file in your project root. +1. Create a `.dev.vars` / `.env` file in your project root. 2. Add key-value pairs: - ```ini title=".dev.vars" + ```ini title=".dev.vars/.env" API_HOST="localhost:3000" DEBUG="true" SECRET_TOKEN="my-local-secret-token" @@ -46,20 +38,23 @@ If you want to manage environment-based configuration that you **want checked in -## Multiple local environments with `.dev.vars` +## Multiple local environments -To simulate different local environments, you can: +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.` . For example, we'll use `.dev.vars.staging`. +1. Create a file named `.dev.vars.`/`.env.`. For example, we can use `.dev.vars.staging`/`.env.staging`. 2. Add key-value pairs: - ```ini title=".dev.vars.staging" + + ```ini title=".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** @@ -70,7 +65,8 @@ To simulate different local environments, you can: - Only the values from `.dev.vars.staging` will be applied instead of `.dev.vars`. + - 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. From 383ff79a233e7bf496d557bf75d2a0ec9a45c543 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Wed, 30 Jul 2025 16:35:26 +0100 Subject: [PATCH 5/8] fix caution box title --- src/content/partials/workers/secrets-in-dev.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/partials/workers/secrets-in-dev.mdx b/src/content/partials/workers/secrets-in-dev.mdx index 6424648cebf01c4..4df00723aa11f28 100644 --- a/src/content/partials/workers/secrets-in-dev.mdx +++ b/src/content/partials/workers/secrets-in-dev.mdx @@ -19,7 +19,7 @@ SECRET_KEY="value" API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" ``` -:::caution [Do not commit secrets to git] +:::caution[Do not commit secrets to git] The `.dev.vars` and `.env` files should not committed to git. Add `.dev.vars*` and `.env*` to your project's `.gitignore` file. ::: From 9ed8dfb6881b6a4af3a6218fe915fb3c63f4c511 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Wed, 30 Jul 2025 16:44:32 +0100 Subject: [PATCH 6/8] update vite-plugin page --- .../vite-plugin/reference/cloudflare-environments.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/vite-plugin/reference/cloudflare-environments.mdx b/src/content/docs/workers/vite-plugin/reference/cloudflare-environments.mdx index a242f2f845d867e..a497d84dc3fe69c 100644 --- a/src/content/docs/workers/vite-plugin/reference/cloudflare-environments.mdx +++ b/src/content/docs/workers/vite-plugin/reference/cloudflare-environments.mdx @@ -6,7 +6,7 @@ sidebar: description: Using Cloudflare environments with the Vite plugin --- -import { PackageManagers, WranglerConfig } from "~/components"; +import { PackageManagers, Render, WranglerConfig } from "~/components"; A Worker config file may contain configuration for multiple [Cloudflare environments](/workers/wrangler/environments/). With the Cloudflare Vite plugin, you select a Cloudflare environment at dev or build time by providing the `CLOUDFLARE_ENV` environment variable. @@ -32,7 +32,7 @@ vars = { MY_VAR = "Production var" } If you run `CLOUDFLARE_ENV=production vite build` then the output `wrangler.json` file generated by the build will be a flattened configuration for the 'production' Cloudflare environment, as shown in the following example: -```json title=wrangler.json +```json title=dist/wrangler.json { "name": "my-worker", "compatibility_date": "2025-04-03", @@ -59,6 +59,10 @@ Running `vite dev` or `vite build` without providing `CLOUDFLARE_ENV` will use t As Cloudflare environments are applied at dev and build time, specifying `CLOUDFLARE_ENV` when running `vite preview` or `wrangler deploy` will have no effect. ::: +## Secrets in local development + + + ## Combining Cloudflare environments and Vite modes You may wish to combine the concepts of [Cloudflare environments](/workers/wrangler/environments/) and [Vite modes](https://vite.dev/guide/env-and-mode.html#modes). From 382757c62dc63075ed3700a5b0168e6254b29b95 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Wed, 30 Jul 2025 16:51:07 +0100 Subject: [PATCH 7/8] update system environment variables page --- .../wrangler/system-environment-variables.mdx | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/system-environment-variables.mdx b/src/content/docs/workers/wrangler/system-environment-variables.mdx index 14eff0b92d38b6c..d24c93dacafc7c0 100644 --- a/src/content/docs/workers/wrangler/system-environment-variables.mdx +++ b/src/content/docs/workers/wrangler/system-environment-variables.mdx @@ -16,45 +16,66 @@ System environment variables are local environment variables that can change Wra 3. Set the values in your shell environment. For example, if you are using Z shell, adding `export CLOUDFLARE_API_TOKEN=...` to your `~/.zshrc` file will set this token as part of your shell configuration. :::note - To set different system environment variables for each environment, create files named `.env.`. When you use `wrangler --env `, the corresponding environment-specific file will be loaded instead of the `.env` file, so the two files are not merged. ::: +:::note +During local development, the values in `.env` files are also loaded into the `env` object in your Worker, so you can access them in your Worker code. + +For example, if you set `API_HOST="localhost:3000"` in your `.env` file, you can access it in your Worker like this: + +```js +const apiHost = env.API_HOST; +``` + +See the [Environment variables and secrets](/workers/development-testing/environment-variables/) page for more information on how to use `.env` files in local development. +::: + ## Supported environment variables Wrangler supports the following environment variables: - `CLOUDFLARE_ACCOUNT_ID` + - The [account ID](/fundamentals/account/find-account-and-zone-ids/) for the Workers related account. - `CLOUDFLARE_API_TOKEN` + - The [API token](/fundamentals/api/get-started/create-token/) for your Cloudflare account, can be used for authentication for situations like CI/CD, and other automation. - `CLOUDFLARE_API_KEY` + - The API key for your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_EMAIL=`. - `CLOUDFLARE_EMAIL` + - The email address associated with your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_API_KEY=`. - `WRANGLER_SEND_METRICS` + - Options for this are `true` and `false`. Defaults to `true`. Controls whether Wrangler can send anonymous usage data to Cloudflare for this project. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md). - `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_` + - The [local connection string](/hyperdrive/configuration/local-development/) for your database to use in local development with [Hyperdrive](/hyperdrive/). For example, if the binding for your Hyperdrive is named `PROD_DB`, this would be `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_PROD_DB="postgres://user:password@127.0.0.1:5432/testdb"`. Each Hyperdrive is uniquely distinguished by the binding name. - `CLOUDFLARE_API_BASE_URL` + - The default value is `"https://api.cloudflare.com/client/v4"`. - `WRANGLER_LOG` + - Options for Logging levels are `"none"`, `"error"`, `"warn"`, `"info"`, `"log"` and `"debug"`. Levels are case-insensitive and default to `"log"`. If an invalid level is specified, Wrangler will fallback to the default. Logs can include requests to Cloudflare's API, any usage data being collected, and more verbose error logs. - `WRANGLER_LOG_PATH` + - A file or directory path where Wrangler will write debug logs. If the path ends in `.log`, Wrangler will consider this the path to a file where all logs will be written. Otherwise, Wrangler will treat the path as a directory where it will write one or more log files using a timestamp for the filenames. - `FORCE_COLOR` - By setting this to `0`, you can disable Wrangler's colorised output, which makes it easier to read with some terminal setups. For example, `FORCE_COLOR=0`. * `WRANGLER_HTTPS_KEY_PATH` + - Path to a custom HTTPS certificate key when running `wrangler dev`, to be used with `WRANGLER_HTTPS_CERT_PATH`. * `WRANGLER_HTTPS_CERT_PATH` From d83e2bf0fd041c4bb90975fc6adb5d29a5f08c02 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Fri, 1 Aug 2025 09:26:48 +0100 Subject: [PATCH 8/8] clarify env vars that control handling --- src/content/partials/workers/secrets-in-dev.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/partials/workers/secrets-in-dev.mdx b/src/content/partials/workers/secrets-in-dev.mdx index 4df00723aa11f28..5df82da8271fa24 100644 --- a/src/content/partials/workers/secrets-in-dev.mdx +++ b/src/content/partials/workers/secrets-in-dev.mdx @@ -34,10 +34,10 @@ When you select a Cloudflare environment in your local development, the correspo - `.env.` - `.env` (least specific) -:::note -To disable loading local dev vars from `.env` files without providing a `.dev.vars` file, set the `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV` environment variable to `"false"`. -::: +:::note[Controlling `.env` handling] +It is possible to control how `.env` files are loaded in local development by setting environment variables on the process running the tools. + +- To disable loading local dev vars from `.env` files without providing a `.dev.vars` file, set the `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV` environment variable to `"false"`. +- To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `"true"`. -:::note -To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `"true"`. :::