From d850131ed49ffa3f7459acc66b67a7494b4db29c Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 16 Dec 2024 11:48:04 +0000 Subject: [PATCH 01/11] wrangler: document the new "redirected" configuration feature See https://github.com/cloudflare/workers-sdk/pull/7442 --- .../docs/workers/wrangler/configuration.mdx | 89 ++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 88ad60b87c9346..ae4cd956a1b92a 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1191,7 +1191,7 @@ upload_source_maps = true ## Workers Sites - + [Workers Sites](/workers/configuration/sites/) allows you to host static websites, or dynamic websites using frameworks like Vue or React, on Workers. @@ -1252,3 +1252,90 @@ 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 `. + +## 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 a user's configuration. + +::: + +When using a framework or a custom pre-build process, some tools need to generate a modified Wrangler configuration alongside the generated 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 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 approach that a build tool might choose to implement is to output code and configuration in a `dist` directory. + +- The user writes code that uses Cloudflare Workers resources, configured via a user `wrangler.toml` file. + + ```toml + name = "my-worker" + main = "src/index.ts" + [[kv_namespaces]] + binding = "" + id = "" + ``` + + Note that this configuration points `main` at the user code entry-point. + +- 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 deployment configuration file. + It also generates a `.wrangler/deploy/config.json` file that redirects Wrangler to the new generated deployment configuration file: + + ```plain + - dist + - index.js + - wrangler.json + - .wrangler + - deploy + - config.json + ``` + + The generated `dist/wrangler.json` might contain: + + ```json + { + "name": "my-worker", + "main": "./index.js", + "kv_namespaces": [{ "binding": "", "id": "" }] + } + ``` + + 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" + } + ``` From 97857ae5393a224e8783d9b210c77d6b23869850 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Thu, 9 Jan 2025 11:17:44 +0000 Subject: [PATCH 02/11] fixup! wrangler: document the new "redirected" configuration feature --- src/content/docs/workers/wrangler/bundling.mdx | 6 ++++++ src/content/docs/workers/wrangler/configuration.mdx | 11 +++++++---- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/src/content/docs/workers/wrangler/bundling.mdx b/src/content/docs/workers/wrangler/bundling.mdx index 0ff514d702a703..a249bd0088c62d 100644 --- a/src/content/docs/workers/wrangler/bundling.mdx +++ b/src/content/docs/workers/wrangler/bundling.mdx @@ -79,3 +79,9 @@ 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 + +When using a framework or a custom pre-build process, some tools need to generate a modified Wrangler configuration alongside the generated code. + +See [Generated Wrangler configuration](/workers/wrangler/configuration/#generated-wrangler-configuration) for more information. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index ae4cd956a1b92a..4f044d94ef8e23 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/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.toml` file to customize the development and deployment setup for a Worker. @@ -1311,14 +1312,16 @@ A common approach that a build tool might choose to implement is to output code - This `my-tool` generates a `dist` directory that contains both compiled code and a new deployment configuration file. It also generates a `.wrangler/deploy/config.json` file that redirects Wrangler to the new generated deployment configuration file: - ```plain + + - dist - index.js - - wrangler.json + - wrangler.json - .wrangler - deploy - - config.json - ``` + - config.json + + The generated `dist/wrangler.json` might contain: From 888d08b2f1b9d573cb506ece549d4e0203231c37 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 10 Jan 2025 14:15:34 +0000 Subject: [PATCH 03/11] Update src/content/docs/workers/wrangler/configuration.mdx Co-authored-by: ToriLindsay --- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 4f044d94ef8e23..da96bc49766830 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1284,7 +1284,7 @@ This file must contain only a single JSON object of the form: { "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. +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 From d928e801b954c4c96084fd92222ecda16901111b Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 10 Jan 2025 14:15:55 +0000 Subject: [PATCH 04/11] Update src/content/docs/workers/wrangler/configuration.mdx Co-authored-by: ToriLindsay --- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index da96bc49766830..48bc7371f2f117 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1260,7 +1260,7 @@ Wrangler will not delete your secrets (encrypted environment variables) unless y 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 a user's configuration. +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. ::: From 146c8c2eab301a95ecd203d23601ecec193fd905 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 10 Jan 2025 14:17:36 +0000 Subject: [PATCH 05/11] Update src/content/docs/workers/wrangler/configuration.mdx Co-authored-by: ToriLindsay --- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 48bc7371f2f117..0fb6946af3e985 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1265,7 +1265,7 @@ It is unlikely that an application developer will need to use this feature, but ::: When using a framework or a custom pre-build process, some tools need to generate a modified Wrangler configuration alongside the generated 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 configuration. +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: From 387f3d06941638e2989d887341297f7193a8c084 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 10 Jan 2025 14:19:00 +0000 Subject: [PATCH 06/11] Update src/content/docs/workers/wrangler/configuration.mdx Co-authored-by: ToriLindsay --- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 0fb6946af3e985..b222a13953a917 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1291,7 +1291,7 @@ Wrangler will display messaging to the user to indicate that the configuration h A common approach that a build tool might choose to implement is to output code and configuration in a `dist` directory. -- The user writes code that uses Cloudflare Workers resources, configured via a user `wrangler.toml` file. +- First, the user writes code that uses Cloudflare Workers resources, configured via a user `wrangler.toml` file. ```toml name = "my-worker" From 58e25247f82518a176e2cc214c27334f781f98a6 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 10 Jan 2025 14:19:10 +0000 Subject: [PATCH 07/11] Update src/content/docs/workers/wrangler/configuration.mdx Co-authored-by: ToriLindsay --- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index b222a13953a917..3c60fb1a49a7c4 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1303,7 +1303,7 @@ A common approach that a build tool might choose to implement is to output code Note that this configuration points `main` at the user code entry-point. -- The user runs a custom build, which might read the user's `wrangler.toml` to find the source 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 From 645d9a78393290b56b570f850ad936d5cacd8077 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 10 Jan 2025 14:19:28 +0000 Subject: [PATCH 08/11] Update src/content/docs/workers/wrangler/configuration.mdx Co-authored-by: ToriLindsay --- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 3c60fb1a49a7c4..a2782dac8f2ed3 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1310,7 +1310,7 @@ A common approach that a build tool might choose to implement is to output code ``` - This `my-tool` generates a `dist` directory that contains both compiled code and a new deployment configuration file. - It also generates a `.wrangler/deploy/config.json` file that redirects Wrangler to the new generated deployment configuration file: + It also generates a `.wrangler/deploy/config.json` file that redirects Wrangler to the new, generated deployment configuration file: From 8f31334f85e207fc4defca6199c2b28ecf3ab925 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Fri, 10 Jan 2025 14:25:54 +0000 Subject: [PATCH 09/11] update wording in bundling doc --- src/content/docs/workers/wrangler/bundling.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/bundling.mdx b/src/content/docs/workers/wrangler/bundling.mdx index a249bd0088c62d..f58f45279b7358 100644 --- a/src/content/docs/workers/wrangler/bundling.mdx +++ b/src/content/docs/workers/wrangler/bundling.mdx @@ -82,6 +82,7 @@ Use [Custom Builds](/workers/wrangler/custom-builds/) to customize what Wrangler ## Generated Wrangler configuration -When using a framework or a custom pre-build process, some tools need to generate a modified Wrangler configuration alongside the generated code. +Some frameworks, or a custom pre-build processes, generate a modified Wrangler configuration alongside the compiled 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. From 0286767812c8eb8c4d2ec3e4232719b50962e35c Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Fri, 10 Jan 2025 14:47:22 +0000 Subject: [PATCH 10/11] Review feedback updates --- src/content/docs/workers/wrangler/bundling.mdx | 2 +- src/content/docs/workers/wrangler/configuration.mdx | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/workers/wrangler/bundling.mdx b/src/content/docs/workers/wrangler/bundling.mdx index f58f45279b7358..3a7acb2e080d76 100644 --- a/src/content/docs/workers/wrangler/bundling.mdx +++ b/src/content/docs/workers/wrangler/bundling.mdx @@ -82,7 +82,7 @@ Use [Custom Builds](/workers/wrangler/custom-builds/) to customize what Wrangler ## Generated Wrangler configuration -Some frameworks, or a custom pre-build processes, generate a modified Wrangler configuration alongside the compiled code. +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. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index a2782dac8f2ed3..8cd12d27061e12 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1289,9 +1289,9 @@ Wrangler will display messaging to the user to indicate that the configuration h ### Custom build tool example -A common approach that a build tool might choose to implement is to output code and configuration in a `dist` directory. +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 `wrangler.toml` file. +- First, the user writes code that uses Cloudflare Workers resources, configured via a user's `wrangler.toml` file. ```toml name = "my-worker" @@ -1301,7 +1301,7 @@ A common approach that a build tool might choose to implement is to output code id = "" ``` - Note that this configuration points `main` at the user 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.toml` to find the source code entry-point: @@ -1309,8 +1309,8 @@ A common approach that a build tool might choose to implement is to output code > my-tool build ``` -- This `my-tool` generates a `dist` directory that contains both compiled code and a new deployment configuration file. - It also generates a `.wrangler/deploy/config.json` file that redirects Wrangler to the new, generated deployment configuration file: +- 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: From da1e0bf3787d2f5f5787a60f842ffabeb1d461f1 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Fri, 10 Jan 2025 14:55:18 +0000 Subject: [PATCH 11/11] Review feedback updates --- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 8cd12d27061e12..21a366284a94bf 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1264,7 +1264,7 @@ It is unlikely that an application developer will need to use this feature, but ::: -When using a framework or a custom pre-build process, some tools need to generate a modified Wrangler configuration alongside the generated code. +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: