wrangler: document the new "redirected" configuration feature (#18757)

* wrangler: document the new "redirected" configuration feature

See cloudflare/workers-sdk#7442

* fixup! wrangler: document the new "redirected" configuration feature

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

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

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

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

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

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

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

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

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

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

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

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

* update wording in bundling doc

* Review feedback updates

* Review feedback updates

---------

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

Author: petebacondarwin

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

@@ -79,3 +79,10 @@ Disabling bundling is not recommended in most scenarios. Use this option only wh
 If your build tooling already produces build artifacts suitable for direct deployment to Cloudflare, you can opt out of bundling by using the `--no-bundle` command line flag: `npx wrangler deploy --no-bundle`. If you opt out of bundling, Wrangler will not process your code and some features introduced by Wrangler bundling (for example minification, and polyfills injection) will not be available.
 
 Use [Custom Builds](/workers/wrangler/custom-builds/) to customize what Wrangler will bundle and upload to the Cloudflare global network when you use [`wrangler dev`](/workers/wrangler/commands/#dev) and [`wrangler deploy`](/workers/wrangler/commands/#deploy).
+
+## Generated Wrangler configuration
+
+Some framework tools, or custom pre-build processes, generate a modified Wrangler configuration to be used to deploy the Worker code.
+It is possible for Wrangler to automatically use this generated configuration rather than the original, user's configuration.
+
+See [Generated Wrangler configuration](/workers/wrangler/configuration/#generated-wrangler-configuration) for more information.

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

@@ -10,6 +10,7 @@ description: Use a configuration file to customize the
 ---
 
 import { Render, Type, MetaInfo } from "~/components";
+import { FileTree } from "@astrojs/starlight/components";
 
 Wrangler optionally uses a `wrangler.json`/`wrangler.jsonc`/`wrangler.toml` file to customize the development and deployment setup for a Worker.
 
@@ -1199,7 +1200,7 @@ upload_source_maps = true
 
 ## Workers Sites
 
-<Render file="workers_sites"/>
+<Render file="workers_sites" />
 
 [Workers Sites](/workers/configuration/sites/) allows you to host static websites, or dynamic websites using frameworks like Vue or React, on Workers.
 
@@ -1260,3 +1261,92 @@ If you change your environment variables in the Cloudflare dashboard, Wrangler w
 If you change your routes in the dashboard, Wrangler will override them in the next deploy with the routes you have set in your Wrangler configuration file. To manage routes via the Cloudflare dashboard only, remove any route and routes keys from your Wrangler configuration file. Then add `workers_dev = false` to your Wrangler configuration file. For more information, refer to [Deprecations](/workers/wrangler/deprecations/#other-deprecated-behavior).
 
 Wrangler will not delete your secrets (encrypted environment variables) unless you run `wrangler secret delete <key>`.
+
+## Generated Wrangler configuration
+
+:::note
+
+This section describes a feature that can be implemented by frameworks and other build tools that are integrating with Wrangler.
+
+It is unlikely that an application developer will need to use this feature, but it is documented here to help you understand when Wrangler is using a generated configuration rather than the original, user's configuration.
+
+:::
+
+Some framework tools, or custom pre-build processes, generate a modified Wrangler configuration to be used to deploy the Worker code.
+In this case, the tool may also create a special `.wrangler/deploy/config.json` file that redirects Wrangler to use the generated configuration rather than the original, user's configuration.
+
+Wrangler uses this generated configuration only for the following deploy and dev related commands:
+
+- `wrangler deploy`
+- `wrangler dev`
+- `wrangler versions upload`
+- `wrangler versions deploy`
+- `wrangler pages deploy`
+- `wrangler pages build`
+- `wrangler pages build-env`
+
+When running these commands, Wrangler looks up the directory tree from the current working directory for a file at the path `.wrangler/deploy/config.json`.
+This file must contain only a single JSON object of the form:
+
+```json
+{ "configPath": "../../path/to/wrangler.json" }
+```
+
+When this `config.json` file exists, Wrangler will follow the `configPath` (relative to the `.wrangler/deploy/config.json` file) to find the generated Wrangler configuration file to load and use in the current command.
+Wrangler will display messaging to the user to indicate that the configuration has been redirected to a different file than the user's configuration file.
+
+### Custom build tool example
+
+A common example of using a redirected configuration is where a custom build tool, or framework, wants to modify the user's configuration to be used when deploying, by generating a new configuration in a `dist` directory.
+
+- First, the user writes code that uses Cloudflare Workers resources, configured via a user's `wrangler.toml` file.
+
+  ```toml
+  name = "my-worker"
+  main = "src/index.ts"
+  [[kv_namespaces]]
+  binding = "<BINDING_NAME1>"
+  id = "<NAMESPACE_ID1>"
+  ```
+
+  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.toml` to find the source code entry-point:
+
+  ```bash
+  > my-tool build
+  ```
+
+- This `my-tool` generates a `dist` directory that contains both compiled code and a new generated deployment configuration file.
+  It also creates a `.wrangler/deploy/config.json` file that redirects Wrangler to the new, generated deployment configuration file:
+
+  <FileTree>
+
+  - dist
+    - index.js
+    - wrangler.json
+  - .wrangler
+    - deploy
+      - config.json
+
+  </FileTree>
+
+  The generated `dist/wrangler.json` might contain:
+
+  ```json
+  {
+  	"name": "my-worker",
+  	"main": "./index.js",
+  	"kv_namespaces": [{ "binding": "<BINDING_NAME1>", "id": "<NAMESPACE_ID1>" }]
+  }
+  ```
+
+  Note that, now, the `main` property points to the generated code entry-point.
+
+  And the `.wrangler/deploy/config.json` contains the path to the generated configuration file:
+
+  ```json
+  {
+  	"configPath": "../../dist/wrangler.json"
+  }
+  ```