update development-testing/environment-variables page

Author: petebacondarwin

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.
+<Render file="secrets-in-dev" product="workers" />
 
-<Aside type="caution">
-	Be sure to add `.dev.vars` to your `.gitignore` so it never gets committed.
-</Aside>
+### 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>