Updates to environment variables docs (managing multiple environments)

src/content/docs/workers/configuration/environment-variables.mdx

@@ -3,16 +3,15 @@ pcx_content_type: configuration
 title: Environment variables
 head: []
 description: Environment variables are a type of binding that allow you to attach text strings or JSON values to your Worker
-
 ---
 
-import { Render, TabItem, Tabs, WranglerConfig } from "~/components"
+import { Render, TabItem, Tabs, Aside, WranglerConfig } from "~/components";
 
 ## Background
 
-Environment variables are a type of binding that allow you to attach text strings or JSON values to your Worker. Environment variables are available on the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters) passed to your Worker's [`fetch` event handler](/workers/runtime-apis/handlers/fetch/).
+Environment variables are a type of binding that allow you to attach text strings or JSON values to your Worker. They are pass in via the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters) in your Worker's [`fetch` event handler](/workers/runtime-apis/handlers/fetch/).
 
-Text strings and JSON values are not encrypted and are useful for storing application configuration.
+Text strings and JSON values are **not encrypted** and are useful for storing application configuration. If you need to store sensitive information (such as API keys or tokens), use [secrets](/workers/configuration/secrets/).
 
 ## Add environment variables via Wrangler
 
@@ -26,31 +25,37 @@ Refer to the following example on how to access the `API_HOST` environment varia
 
 ```js
 export default {
-  async fetch(request, env, ctx) {
-    return new Response(`API host: ${env.API_HOST}`);
-  }
-}
+	async fetch(request, env, ctx) {
+		return new Response(`API host: ${env.API_HOST}`);
+	},
+};
 ```
 
 </TabItem> <TabItem label="TypeScript" icon="seti:typescript">
 
 ```ts
 export interface Env {
-  API_HOST: string;
+	API_HOST: string;
 }
 
 export default {
-  async fetch(request, env, ctx): Promise<Response> {
-    return new Response(`API host: ${env.API_HOST}`);
-  }
+	async fetch(request, env, ctx): Promise<Response> {
+		return new Response(`API host: ${env.API_HOST}`);
+	},
 } satisfies ExportedHandler<Env>;
 ```
 
 </TabItem> </Tabs>
 
-`vars` is a non-inheritable key. [Non-inheritable keys](/workers/wrangler/configuration/#non-inheritable-keys) are configurable at the top-level, but cannot be inherited by environments and must be specified for each environment.
+<Aside type="note">
+
+**`vars` is a non-inheritable key**. [Non-inheritable keys](/workers/wrangler/configuration/#non-inheritable-keys) are configurable at the top-level, but cannot be inherited by environments and must be specified for each environment.
+
+</Aside>
+
+## Managing environment variables across multiple environments
 
-To define environment variables for different environments, refer to the example below:
+Since `vars` is a [non-inheritable key](/workers/wrangler/configuration/#non-inheritable-keys), you need to explicitly define your environment variables for each environment (for example, `staging` and `production`).
 
 <WranglerConfig>
 
@@ -69,15 +74,19 @@ SERVICE_X_DATA = { URL = "service-x-api.prod.example", MY_ID = 456 }
 ```
 
 </WranglerConfig>
-
-For local development with `wrangler dev`, variables in the [Wrangler configuration file](/workers/wrangler/configuration/) are automatically overridden by any values defined in a `.dev.vars` file located in the root directory of your worker. This is useful for providing values you do not want to check in to source control.
+### Overriding environment variables during local development
+When running [`wrangler dev`](/workers/wrangler/commands/#dev), variables in the [Wrangler configuration file](/workers/wrangler/configuration/) are automatically overridden by any values defined in a **`.dev.vars` file** located in the root directory of your Worker. This is useful for providing values you do not want to check in to source control.
 
 ```shell
 API_HOST = "localhost:4000"
 API_ACCOUNT_ID = "local_example_user"
 ```
 
-Alternatively, you can specify per-environment values in the [Wrangler configuration file](/workers/wrangler/configuration/) and provide an `environment` value via the `env` flag when developing locally like so `wrangler dev --env=local`.
+Alternatively, you can specify per-environment values in the [Wrangler configuration file](/workers/wrangler/configuration/) and provide an `environment` value via the `--env` flag when developing locally:
+
+```sh
+wrangler dev --env=local
+```
 
 ## Add environment variables via the dashboard
 
@@ -89,19 +98,17 @@ To add environment variables via the dashboard:
 4. Select **Settings**.
 5. Under **Variables and Secrets**, select **Add**.
 6. Select a **Type**, input a **Variable name**, and input its **Value**. This variable will be made available to your Worker.
-7. (Optional) To add multiple environment variables, select **Add variable**.
+7. (_Optional_) To add multiple environment variables, select **Add variable**.
 8. Select **Deploy** to implement your changes.
 
 :::caution[Plaintext strings and secrets]
 
-
 Select the **Secret** type if your environment variable is a [secret](/workers/configuration/secrets/).
 
-
 :::
 
 <Render file="env_and_secrets" />
 
 ## Related resources
 
-* Learn how to access environment variables in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.
+- Learn how to access environment variables in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

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

@@ -631,6 +631,10 @@ Example:
 
 <Render file="envvar-example" />
 
+:::tip
+For details on how to work with environment variables in multiple environments, see [Managing environment variables across multiple environments](/workers/configuration/environment-variables/#managing-environment-variables-across-multiple-environments).
+:::
+
 ### Hyperdrive
 
 [Hyperdrive](/hyperdrive/) bindings allow you to interact with and query any Postgres database from within a Worker.
@@ -658,7 +662,7 @@ id = "<ID>"
 
 </WranglerConfig>
 
-### Images 
+### Images
 
 [Cloudflare Images](/images/transform-images/transform-via-workers/) lets you make transformation requests to optimize, resize, and manipulate images stored in remote sources.
 
@@ -1316,17 +1320,17 @@ A common example of using a redirected configuration is where a custom build too
 
 <WranglerConfig>
 
-  ```toml title="wrangler.toml"
-  name = "my-worker"
-  main = "src/index.ts"
-  [[kv_namespaces]]
-  binding = "<BINDING_NAME1>"
-  id = "<NAMESPACE_ID1>"
-  ```
+```toml title="wrangler.toml"
+name = "my-worker"
+main = "src/index.ts"
+[[kv_namespaces]]
+binding = "<BINDING_NAME1>"
+id = "<NAMESPACE_ID1>"
+```
 
 </WranglerConfig>
 
-  Note that this configuration points `main` at the user's code entry-point.
+Note that this configuration points `main` at the user's code entry-point.
 
 - Then, the user runs a custom build, which might read the user's Wrangler configuration file to find the source code entry-point:
 

src/content/partials/workers/env_and_secrets.mdx

@@ -1,16 +1,30 @@
 ---
 {}
-
 ---
 
-## Compare secrets and environment variables
+## Secrets vs Environment Variables
 
 :::caution[Use secrets for sensitive information]
 
+**Never store sensitive information in plaintext environment variables**. Always use [secrets](/workers/configuration/secrets/) for data like passwords or API tokens.
+:::
+
+### When to use [secrets](/workers/configuration/secrets/)
 
-Do not use plaintext environment variables to store sensitive information. Use [secrets](/workers/configuration/secrets/) instead.
+If your environment variable is a secret (such as a password or API token), select the **Secret** type when adding it via the dashboard or use [Wrangler's built-in](/workers/configuration/secrets/#secrets-on-deployed-workers) command:
 
+```sh
+ wrangler secret put <KEY>
+```
 
-:::
+Secrets function similarly to environment variables in a Worker, but with crucial differences:
+
+- **Visibility:** Once you define a secret, its value is no longer visible in Wrangler or the Cloudflare dashboard.
+
+- **Security:** Sensitive data, such as passwords and tokens, should always be encrypted to prevent accidental exposure.
+
+To your Worker, **there is no difference between an environment variable and a secret.** The secret's value is passed through as defined.
+
+### When to use [plaintext environment variables](/workers/configuration/environment-variables)
 
-[Secrets](/workers/configuration/secrets/) are [environment variables](/workers/configuration/environment-variables/). The difference is secret values are not visible within Wrangler or Cloudflare dashboard after you define them. This means that sensitive data, including passwords or API tokens, should always be encrypted to prevent data leaks. To your Worker, there is no difference between an environment variable and a secret. The secret's value is passed through as defined.
+Plaintext environment variables are best for non-sensitive configuration details, such as hostnames and IDs. These are values that **do not** require encryption because leaking them does not compromise security or privacy.