Document the new .env support for local development (#23837)

* Document the new .env support for local development

* fixup! Document the new .env support for local development

* fixup! Document the new .env support for local development

* update development-testing/environment-variables page

* fix caution box title

* update vite-plugin page

* update system environment variables page

* clarify env vars that control handling

---------

Co-authored-by: kodster28 <[email protected]>

Author: petebacondarwin

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
 
 <Render file="env_and_secrets" />
 
+### Local development with secrets
+
 <Render file="secrets-in-dev" />
 
 ## Related resources

src/content/docs/workers/development-testing/environment-variables.mdx

@@ -7,29 +7,21 @@ head: []
 description: Configuring environment variables and secrets for local development
 ---
 
-import { PackageManagers, Steps } from "~/components";
+import { 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.
+<Render file="secrets-in-dev" product="workers" />
 
-:::caution
-Be sure to add `.dev.vars` to your `.gitignore` so it never gets committed.
-:::
+### 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.
 
 <Steps>
 
-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
 
 </Steps>
 
-## 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.
 
 <Steps>
 
-1.  Create a file named `.dev.vars.<environment-name>` . For example, we'll use `.dev.vars.staging`.
+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:
-    ```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:
 
         <PackageManagers type="exec" pkg="vite" args="dev" prefix="CLOUDFLARE_ENV=staging" />
 
-        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.
 
 </Steps>
 

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
+
+<Render file="secrets-in-dev" />
+
 ## 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).

src/content/docs/workers/wrangler/environments.mdx

@@ -112,12 +112,16 @@ env.staging.service ={ binding = "<BINDING_NAME>", service = "worker-a-staging"
 
 </WranglerConfig>
 
-### Secrets
+### Secrets for production
 
 You may assign environment-specific [secrets](/workers/configuration/secrets/) by running the command [`wrangler secret put <KEY> -env`](/workers/wrangler/commands/#put). You can also create `dotenv` type files named `.dev.vars.<environment-name>`.
 
 Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.
 
+### Secrets in local development
+
+<Render file="secrets-in-dev" />
+
 ---
 
 ## Examples

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.<environment-name>`. When you use `wrangler <command> --env <environment-name>`, 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` <Type text="string" /> <MetaInfo text="optional" />
+
   - The [account ID](/fundamentals/account/find-account-and-zone-ids/) for the Workers related account.
 
 - `CLOUDFLARE_API_TOKEN` <Type text="string" /> <MetaInfo text="optional" />
+
   - 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` <Type text="string" /> <MetaInfo text="optional" />
+
   - The API key for your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_EMAIL=`.
 
 - `CLOUDFLARE_EMAIL` <Type text="string" /> <MetaInfo text="optional" />
+
   - The email address associated with your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_API_KEY=`.
 
 - `WRANGLER_SEND_METRICS` <Type text="string" /> <MetaInfo text="optional" />
+
   - 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_<BINDING_NAME>`<Type text="string" /> <MetaInfo text="optional" />
+
   - 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:[email protected]:5432/testdb"`. Each Hyperdrive is uniquely distinguished by the binding name.
 
 - `CLOUDFLARE_API_BASE_URL` <Type text="string" /> <MetaInfo text="optional" />
+
   - The default value is `"https://api.cloudflare.com/client/v4"`.
 
 - `WRANGLER_LOG` <Type text="string" /> <MetaInfo text="optional" />
+
   - 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` <Type text="string" /> <MetaInfo text="optional" />
+
   - 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` <Type text="string" /> <MetaInfo text="optional" />
   - 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` <Type text="string" /> <MetaInfo text="optional" />
+
   - Path to a custom HTTPS certificate key when running `wrangler dev`, to be used with `WRANGLER_HTTPS_CERT_PATH`.
 
 * `WRANGLER_HTTPS_CERT_PATH` <Type text="string" /> <MetaInfo text="optional" />

src/content/partials/workers/secrets-in-dev.mdx

@@ -2,15 +2,42 @@
 {}
 ---
 
-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.
+:::caution
+Do not use `vars` to store sensitive information in your Worker's Wrangler configuration file. Use secrets instead.
+:::
 
-The `.dev.vars` file should be formatted like a `dotenv` file, such as `KEY="VALUE"`:
+Put secrets for use in local development in either a `.dev.vars` file or a `.env` file, in the root of your project.
 
-```bash title=".dev.vars"
+:::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:
+
+```bash title=".dev.vars / .env"
 SECRET_KEY="value"
 API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
 ```
 
-To set different secrets for each environment, create files named `.dev.vars.<environment-name>`. When you use `wrangler <command> --env <environment-name>`, the corresponding environment-specific file will be loaded instead of the `.dev.vars` file.
+:::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.<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)
+
+:::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"`.
 
-Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.
+:::