Update docs on Wrangler environments (#20873)

* update wrangler environments page

* update environment variables page

* update environments section in wrangler configuration page

* fixup

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

Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>

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

* Update environment-variables.mdx

* Update environment-variables.mdx

* more fixups..

---------

Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>

Author: 2 people

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

@@ -3,10 +3,9 @@ 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, WranglerConfig } from "~/components";
 
 ## Background
 
@@ -26,58 +25,56 @@ 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.
+### Configuring different environments in Wrangler
+
+[Environments in Wrangler](/workers/wrangler/environments) let you specify different configurations for the same Worker, including different values for `vars` in each environment.
+As `vars` is a [non-inheritable key](/workers/wrangler/configuration/#non-inheritable-keys), they are not inherited by environments and must be specified for each environment.
 
-To define environment variables for different environments, refer to the example below:
+The example below sets up two environments, `staging` and `production`, with different values for `API_HOST`.
 
 <WranglerConfig>
 
 ```toml
 name = "my-worker-dev"
 
+# top level environment
+[vars]
+API_HOST = "api.example.com"
+
 [env.staging.vars]
 API_HOST = "staging.example.com"
-API_ACCOUNT_ID = "staging_example_user"
-SERVICE_X_DATA = { URL = "service-x-api.dev.example", MY_ID = 123 }
 
 [env.production.vars]
 API_HOST = "production.example.com"
-API_ACCOUNT_ID = "production_example_user"
-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.
+To run Wrangler commands in specific environments, you can pass in the `--env` or `-e` flag. For example, you can develop the Worker in an environment called `staging` by running `npx wrangler dev --env staging`, and deploy it with `npx wrangler deploy --env staging`.
 
-```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`.
+Learn about [environments in Wrangler](/workers/wrangler/environments).
 
 ## Add environment variables via the dashboard
 
@@ -94,14 +91,14 @@ To add environment variables via the dashboard:
 
 :::caution[Plaintext strings and secrets]
 
-
 Select the **Secret** type if your environment variable is a [secret](/workers/configuration/secrets/).
 
-
 :::
 
 <Render file="env_and_secrets" />
 
+<Render file="secrets-in-dev" />
+
 ## Related resources
 
-* Learn how to access environment variables in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.
+- Migrating environment variables from [Service Worker format to ES modules syntax](/workers/reference/migrate-to-module-workers/#environment-variables).

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

@@ -52,10 +52,10 @@ kv_namespaces = [
 
 ## Environments
 
-The configuration for a Worker can become complex when you define different [environments](/workers/wrangler/environments/), and each environment has its own configuration.
-There is a default (top-level) environment and named environments that provide environment-specific configuration.
+You can define different configurations for a Worker using Wrangler [environments](/workers/wrangler/environments/).
+There is a default (top-level) environment and you can create named environments that provide environment-specific configuration.
 
-These are defined under `[env.name]` keys, such as `[env.staging]` which you can then preview or deploy with the `-e` / `--env` flag in the `wrangler` commands like `npx wrangler deploy --env staging`.
+These are defined under `[env.<name>]` keys, such as `[env.staging]` which you can then preview or deploy with the `-e` / `--env` flag in the `wrangler` commands like `npx wrangler deploy --env staging`.
 
 The majority of keys are inheritable, meaning that top-level configuration can be used in environments. [Bindings](/workers/runtime-apis/bindings/), such as `vars` or `kv_namespaces`, are not inheritable and need to be defined explicitly.
 
@@ -646,7 +646,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.
 
@@ -867,6 +867,7 @@ To bind other Workers to your Worker, assign an array of the below object to the
 - `service` <Type text="string" /> <MetaInfo text="required" />
 
   - The name of the Worker.
+  - To bind to a Worker in a specific [environment](/workers/wrangler/environments), you need to append the environment name to the Worker name. This should be in the format `<worker-name>-<environment-name>`. For example, to bind to a Worker called `worker-name` in its `staging` environment, `service` should be set to `worker-name-staging`.
 
 - `entrypoint` <Type text="string" /> <MetaInfo text="optional" />
 
@@ -1304,17 +1305,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/docs/workers/wrangler/environments.mdx

@@ -2,38 +2,37 @@
 pcx_content_type: concept
 title: Environments
 head: []
-description: Deploy the same Worker application with different configuration for
-  each environment.
+description: Use environments to create different configurations for the same Worker application.
 ---
 
 import { WranglerConfig } from "~/components";
 
-## Background
-
-Wrangler allows you to deploy the same Worker application with different configuration for each environment. You must configure environments in your Worker application's Wrangler file.
+Wrangler allows you to use environments to create different configurations for the same Worker application. Environments are configured in the Worker's [Wrangler configuration file](/workers/wrangler/configuration/).
+There is a default (top-level) environment and you can create named environments that provide environment-specific configuration.
 
 Review the following environments flow:
 
-1. You have created a Worker application named `my-worker`.
-2. You create an environment, for example, `dev`, in the Worker's [Wrangler configuration file](/workers/wrangler/configuration/).
-3. In the Wrangler configuration file, you configure the `dev` environment by [adding bindings](/workers/runtime-apis/bindings/) and/or [routes](/workers/configuration/routing/routes/).
-4. You deploy the Worker using `npx wrangler deploy -e dev`.
-5. In the background, Wrangler creates a new Worker named `my-worker-dev`.
-6. You can now change your `my-worker` Worker code and configuration, and choose which environment to deploy your changes to.
-
-Environments are used with the `--env` or `-e` flag on `wrangler dev`, `npx wrangler deploy`, and `wrangler secret`.
+1. Create a Worker, named `my-worker` for example.
+2. Create an environment, for example `dev`, in the Worker's [Wrangler configuration file](/workers/wrangler/configuration/), by adding a `[env.<ENV_NAME>]` section.
 
-## Configuration
+<WranglerConfig>
 
-To create an environment:
+```json
+{
+	"name": "my-worker",
+	"env": {
+		"<ENV_NAME>": {
+			// environment-specific configuration goes here
+		}
+	}
+}
+```
 
-1. Open your Worker's Wrangler file.
-2. Add `[env.<NAME>]` and change `<NAME>` to the desired name of your environment.
-3. Repeat step 2 to create multiple environments.
+</WranglerConfig>
 
-Be careful when naming your environments that they do not contain sensitive information, such as, `migrating-service-from-company1-to-company2` or `company1-acquisition-load-test`.
+3. You can configure the `dev` environment with different values to the top-level environment. Refer [here](/workers/wrangler/configuration/#environments) for how different options are inherited - or not inherited - between environments.
 
-Review the layout of an example `[env.dev]` environment that sets up a custom `dev.example.com` route:
+For example, to set a different route for a Worker in the `dev` environment:
 
 <WranglerConfig>
 
@@ -46,23 +45,21 @@ route = "dev.example.com"
 ```
 
 </WranglerConfig>
+4. Environments are used with the `--env` or `-e` flag on Wrangler commands. For example, you can develop the Worker in the `dev` environment by running `npx wrangler dev -e=dev`, and deploy it with `npx wrangler deploy -e=dev`.
 
-You cannot specify multiple environments with the same name.
-
-Wrangler appends the environment name to the top-level name to deploy a Worker. For example, a Worker project named `my-worker` with an environment `[env.dev]` would deploy a Worker named `my-worker-dev`.
+:::note
 
-After you have configured your environment, run `npx wrangler deploy` in your Worker project directory for the changes to take effect.
+Cloudflare effectively creates a new Worker for you when you create a Worker with an environment. Wrangler appends the environment name to the top-level name. For example, a Worker project named `my-worker` with an environment `dev` would deploy a Worker named `my-worker-dev`. You must use this name when referencing a Worker in a particular environment, for example in a [service binding](/workers/wrangler/configuration/#service-bindings).
+:::
 
 ## Non-inheritable keys and environments
 
 [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.
 
-[Bindings](/workers/runtime-apis/bindings/) and [environment variables](/workers/configuration/environment-variables/) must be specified per each [environment](/workers/wrangler/environments/) in your [Wrangler configuration file](/workers/wrangler/configuration/).
+For example, [bindings](/workers/runtime-apis/bindings/) and [environment variables](/workers/configuration/environment-variables/) are non-inheritable, and must be specified per [environment](/workers/wrangler/environments/) in your [Wrangler configuration file](/workers/wrangler/configuration/).
 
 Review the following example Wrangler file:
 
-
-
 <WranglerConfig>
 
 ```toml
@@ -85,7 +82,41 @@ kv_namespaces = [
 
 </WranglerConfig>
 
-You may assign environment-specific [secrets](/workers/configuration/secrets/) by running the command [`wrangler secret put <KEY> -env`](/workers/wrangler/commands/#put).
+### Service bindings
+
+To use a [service binding](/workers/wrangler/configuration/#service-bindings) that targets a Worker in a specific environment, you need to append the environment name to the target Worker name in the `service` field. This should be in the format `<worker-name>-<environment-name>`.
+In the example below, we have two Workers, both with a `staging` environment. `worker-b` has a service binding to `worker-a`. Note how the `service` field in the `staging` environment points to `worker-a-staging`, whereas the top-level service binding points to `worker-a`.
+
+<WranglerConfig>
+
+```toml
+name = "worker-a"
+
+vars = { FOO = "<top-level-var>" }
+[env.staging.vars]
+FOO = "<staging-var>"
+```
+
+</WranglerConfig>
+
+<WranglerConfig>
+
+```toml
+name = "worker-b"
+
+services = { binding = "<BINDING_NAME>", service = "worker-a" }
+
+# Note how `service = "worker-a-staging"`
+env.staging.service ={ binding = "<BINDING_NAME>", service = "worker-a-staging" }
+```
+
+</WranglerConfig>
+
+### Secrets
+
+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.
 
 ---
 
@@ -95,8 +126,6 @@ You may assign environment-specific [secrets](/workers/configuration/secrets/) b
 
 The following Wrangler file adds two environments, `[env.staging]` and `[env.production]`, to the Wrangler file. If you are deploying to a [Custom Domain](/workers/configuration/routing/custom-domains/) or [route](/workers/configuration/routing/routes/), you must provide a [`route` or `routes` key](/workers/wrangler/configuration/) for each environment.
 
-
-
 <WranglerConfig>
 
 ```toml
@@ -118,7 +147,7 @@ routes = [
 
 </WranglerConfig>
 
-In order to use environments with this configuration, you can pass the name of the environment via the `--env` flag.
+You can pass the name of the environment via the `--env` flag to run commands in a specific environment.
 
 With this configuration, Wrangler will behave in the following manner:
 
@@ -168,8 +197,6 @@ if (ENVIRONMENT === "staging") {
 
 To deploy your code to your `*.workers.dev` subdomain, include `workers_dev = true` in the desired environment. Your Wrangler file may look like this:
 
-
-
 <WranglerConfig>
 
 ```toml
@@ -206,6 +233,6 @@ Published my-worker
 
 :::caution
 
-When you create a Worker via an environment, Cloudflare automatically creates an SSL certification for it. SSL certifications are discoverable and a matter of public record.
+When you create a Worker via an environment, Cloudflare automatically creates an SSL certification for it. SSL certifications are discoverable and a matter of public record. Be careful when naming your environments that they do not contain sensitive information, such as, `migrating-service-from-company1-to-company2` or `company1-acquisition-load-test`.
 
 :::

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

@@ -1,6 +1,5 @@
 ---
 {}
-
 ---
 
 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.
@@ -12,6 +11,6 @@ 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, so the two files are not merged.
+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.
 
 Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.