From eed960b548cc1f77bd1d516497a3b6b1b415dd05 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Tue, 25 Mar 2025 16:50:05 +0000 Subject: [PATCH 01/11] aliasing as example --- src/content/docs/workers/wrangler/configuration.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 4841af1240518ea..0861a43d2c6f760 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -9,7 +9,7 @@ description: Use a configuration file to customize the Platform products. --- -import { Render, Type, MetaInfo, WranglerConfig } from "~/components"; +import { Render, Type, MetaInfo, WranglerConfig, Details } from "~/components"; import { FileTree } from "@astrojs/starlight/components"; Wrangler optionally uses a configuration file to customize the development and deployment setup for a Worker. @@ -1117,6 +1117,11 @@ local_protocol = "http" ## Module Aliasing +
+ This is replaced "resolve.alias" in Vite - refer to the Vite documentation for + usage: https://vite.dev/config/shared-options.html#resolve-alias". +
+ You can configure Wrangler to replace all calls to import a particular package with a module of your choice, by configuring the `alias` field: From a2178afe8ec38a1d8e81e85d0f0186f1b0459d43 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Tue, 25 Mar 2025 23:31:40 +0000 Subject: [PATCH 02/11] note when not applicable to vite plugin --- .../docs/workers/wrangler/configuration.mdx | 36 ++++++++++++++++--- .../partials/workers/workers_sites.mdx | 3 +- 2 files changed, 33 insertions(+), 6 deletions(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 0861a43d2c6f760..3ca9f8bab16f05b 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -61,6 +61,8 @@ The majority of keys are inheritable, meaning that top-level configuration can b Further, there are a few keys that can _only_ appear at the top-level. +With the [Cloudflare Vite plugin](/workers/local-development/vite/), you select a Wrangler environment at dev or build time via the `CLOUDFLARE_ENV` environment variable. Otherwise, environments are defined in your Wrangler config file as usual. For more detail on using Wrangler environments with the Cloudflare Vite plugin, refer to the [plugin documentation](/workers/local-development/vite#environments). + ## Top-level only keys Top-level keys apply to the Worker as a whole (and therefore all environments). They cannot be defined within named environments. @@ -80,6 +82,7 @@ Top-level keys apply to the Worker as a whole (and therefore all environments). - `site` - See the [Workers Sites](#workers-sites) section below for more information. Cloudflare Pages and Workers Assets is preferred over this approach. + - This is not supported by the [Cloudflare Vite plugin](/workers/local-development/vite/). ## Inheritable keys @@ -129,6 +132,7 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d - `tsconfig` - Path to a custom `tsconfig`. + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). - `triggers` @@ -137,14 +141,17 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d - `rules` - An ordered list of rules that define which modules to import, and what type to import them as. You will need to specify rules to use `Text`, `Data` and `CompiledWasm` modules, or when you wish to have a `.js` file be treated as an `ESModule` instead of `CommonJS`. + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). - `build` - Configures a custom build step to be run by Wrangler when building your Worker. Refer to [Custom builds](#custom-builds). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). - `no_bundle` - Skip internal build steps and directly deploy your Worker script. You must have a plain JavaScript Worker with no dependencies. + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). - `find_additional_modules` @@ -152,20 +159,25 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d Any files that match `rules` will be included in the deployed Worker. Defaults to true if `no_bundle` is true, otherwise false. Can only be used with Module format Workers (not Service Worker format). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). - `base_dir` - The directory in which module "rules" should be evaluated when including additional files (via `find_additional_modules`) into a Worker deployment. Defaults to the directory containing the `main` entry point of the Worker if not specified. + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). - `preserve_file_names` - Determines whether Wrangler will preserve the file names of additional modules bundled with the Worker. The default is to prepend filenames with a content hash. For example, `34de60b44167af5c5a709e62a4e20c4f18c9e3b6-favicon.ico`. + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). - `minify` - Minify the Worker script before uploading. + - If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), `minify` is replaced by Vite's `build.minify` - refer to the [Vite + documentation](https://vite.dev/config/build-options.html#build-minify). - `logpush` @@ -189,6 +201,8 @@ Non-inheritable keys are configurable at the top-level, but cannot be inherited - `define` - A map of values to substitute when deploying your Worker. + - If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), this is replaced by Vite's `define` - refer to the [Vite + documentation](https://vite.dev/config/shared-options.html#define). - `vars` @@ -369,6 +383,10 @@ head_sampling_rate = 0.1 # 10% of requests are logged ## Custom builds +::: note +Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). +::: + You can configure a custom build step that will be run before your Worker is deployed. Refer to [Custom builds](/workers/wrangler/custom-builds/). - `command` @@ -988,6 +1006,7 @@ The following options are available under the `assets` key. - `directory` - Folder of static assets to be served. + - Not required if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), which will automatically point to the client build output. - `binding` @@ -1017,6 +1036,10 @@ assets = { directory = "./public", binding = "ASSETS", html_handling = "force-tr ## Bundling +::: note +Wrangler bundling is not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). +::: + Wrangler can operate in two modes: the default bundling mode and `--no-bundle` mode. In bundling mode, Wrangler will traverse all the imports of your code and generate a single JavaScript "entry-point" file. Imported source code is "inlined/bundled" into this entry-point file. @@ -1074,6 +1097,8 @@ See https://developers.cloudflare.com/workers/wrangler/bundling/ for more detail ## Local development settings +Q: is this replaced by vite's server options? + You can configure various aspects of local development, such as the local protocol or port. - `ip` @@ -1117,10 +1142,10 @@ local_protocol = "http" ## Module Aliasing -
- This is replaced "resolve.alias" in Vite - refer to the Vite documentation for - usage: https://vite.dev/config/shared-options.html#resolve-alias". -
+:::note +If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), `alias` is replaced Vite's `resolve.alias` - refer to the [Vite +documentation](https://vite.dev/config/shared-options.html#resolve-alias). +::: You can configure Wrangler to replace all calls to import a particular package with a module of your choice, by configuring the `alias` field: @@ -1198,6 +1223,7 @@ In many cases, this allows you to work provide just enough of an API to make a d - `upload_source_maps` - When `upload_source_maps` is set to `true`, Wrangler will automatically generate and upload source map files when you run [`wrangler deploy`](/workers/wrangler/commands/#deploy) or [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). Example: @@ -1282,6 +1308,8 @@ This section describes a feature that can be implemented by frameworks and other 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. +For example, when you are using the [Cloudflare Vite plugin](/workers/local-development/vite/), it will generate a Wrangler configuration file when you run `vite build`, which is then used for preview and deployment. + ::: Some framework tools, or custom pre-build processes, generate a modified Wrangler configuration to be used to deploy the Worker code. diff --git a/src/content/partials/workers/workers_sites.mdx b/src/content/partials/workers/workers_sites.mdx index 0c32b6f127ba498..1b522b729ab965d 100644 --- a/src/content/partials/workers/workers_sites.mdx +++ b/src/content/partials/workers/workers_sites.mdx @@ -1,9 +1,8 @@ --- {} - --- :::caution[Use Workers Static Assets Instead] -You should use [Workers Static Assets](/workers/static-assets/) to host full-stack applications instead of Workers Sites. Do not use Workers Sites for new projects. +You should use [Workers Static Assets](/workers/static-assets/) to host full-stack applications instead of Workers Sites. It has been deprecated in Wrangler v4, and the [Cloudflare Vite plugin](/workers/local-development/vite) does not support Workers Sites. Do not use Workers Sites for new projects. ::: From e072c153a5c808b3bfcfc2e3770552a8eb27da48 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Wed, 26 Mar 2025 15:49:07 +0000 Subject: [PATCH 03/11] fixups --- .../docs/workers/wrangler/configuration.mdx | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 3ca9f8bab16f05b..36fa0384c7daa08 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -176,8 +176,7 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d - `minify` - Minify the Worker script before uploading. - - If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), `minify` is replaced by Vite's `build.minify` - refer to the [Vite - documentation](https://vite.dev/config/build-options.html#build-minify). + - If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), `minify` is replaced by Vite's [`build.minify`](https://vite.dev/config/build-options.html#build-minify). - `logpush` @@ -201,8 +200,7 @@ Non-inheritable keys are configurable at the top-level, but cannot be inherited - `define` - A map of values to substitute when deploying your Worker. - - If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), this is replaced by Vite's `define` - refer to the [Vite - documentation](https://vite.dev/config/shared-options.html#define). + - If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), this is replaced by Vite's [`define`](https://vite.dev/config/shared-options.html#define). - `vars` @@ -383,7 +381,7 @@ head_sampling_rate = 0.1 # 10% of requests are logged ## Custom builds -::: note +:::note Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). ::: @@ -1036,7 +1034,7 @@ assets = { directory = "./public", binding = "ASSETS", html_handling = "force-tr ## Bundling -::: note +:::note Wrangler bundling is not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). ::: @@ -1097,7 +1095,9 @@ See https://developers.cloudflare.com/workers/wrangler/bundling/ for more detail ## Local development settings -Q: is this replaced by vite's server options? +:::note +If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), you should use Vite's [server options]](https://vite.dev/config/server-options.html) instead. +::: You can configure various aspects of local development, such as the local protocol or port. @@ -1143,8 +1143,7 @@ local_protocol = "http" ## Module Aliasing :::note -If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), `alias` is replaced Vite's `resolve.alias` - refer to the [Vite -documentation](https://vite.dev/config/shared-options.html#resolve-alias). +If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), `alias` is replaced Vite's [`resolve.alias`](https://vite.dev/config/shared-options.html#resolve-alias). ::: You can configure Wrangler to replace all calls to import a particular package with a module of your choice, by configuring the `alias` field: From a674d70b361d669f8a15c31640286083e560e7e0 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Thu, 3 Apr 2025 14:44:19 +0100 Subject: [PATCH 04/11] revert notice about upload_source_maps --- src/content/docs/workers/wrangler/configuration.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 36fa0384c7daa08..091a09c771aafbc 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1222,7 +1222,6 @@ In many cases, this allows you to work provide just enough of an API to make a d - `upload_source_maps` - When `upload_source_maps` is set to `true`, Wrangler will automatically generate and upload source map files when you run [`wrangler deploy`](/workers/wrangler/commands/#deploy) or [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2). - - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). Example: From fb44a1435cd8812d65010b9d22b630b53b9278ca Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Thu, 3 Apr 2025 19:23:36 +0100 Subject: [PATCH 05/11] shorten asset routing summary --- .../workers/workers-assets-routing-summary.mdx | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/src/content/partials/workers/workers-assets-routing-summary.mdx b/src/content/partials/workers/workers-assets-routing-summary.mdx index 0054a38e6a99684..6ba9e0b6a2e4006 100644 --- a/src/content/partials/workers/workers-assets-routing-summary.mdx +++ b/src/content/partials/workers/workers-assets-routing-summary.mdx @@ -2,12 +2,6 @@ {} --- -When using Workers Assets, Cloudflare will first attempt to serve any static assets which match the incoming request. +By default, Cloudflare first tries to serve a static asset, and failing that, invokes a Worker if one is present. If there is no Worker, or the Worker uses the asset binding (e.g. `env.ASSETS.fetch(request)`), then Cloudflare will fallback to the behaviour set by [`not_found_handling`](/workers/static-assets/routing/#not_found_handling). -For example, if you have requests for `/logo.png` and `/blog/hello-world.html` in your assets directory, and make requests for `/logo.png` and `/blog/hello-world`, those files will be served respectively. The [`html_handling`](/workers/static-assets/routing/#html_handling) option allows you to customize the serving of HTML files if you have specific needs around redirects and trailing slashes. - -If a request does not match a static asset, Cloudflare will then invoke your Worker script module, if one is present. This can be configured with the [`main`](/workers/wrangler/configuration/#inheritable-keys) property in the [Wrangler configuration file](/workers/wrangler/configuration/). - -Finally, if a request does not match any static assets, and either a Worker script module is not present, or from within that Worker script module, the [asset binding](/workers/static-assets/binding/)'s `fetch` method is called (e.g. `env.ASSETS.fetch(request)`), Cloudflare will fall back to evaluating the [`not_found_handling`](/workers/static-assets/routing/#not_found_handling) behavior. By default, it will serve a null-body 404-status response, but this can be configured to instead serve custom HTML 404 pages, or to serve a single-page application (SPA). - -At present, there is no way to customize this routing behavior beyond the `html_handling` and `not_found_handling` options. We plan to offer additional configuration controls, such as allowing you to always run the Worker script modules for certain paths, in the future. +Refer to the [routing documentation](/workers/static-assets/routing/#routing-configuration) for more information on how to routing works with Workers Assets, and how to customize this behavior. From 22f1a2bb8733e5ddec23d5ead3d4ae97ce574765 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Thu, 3 Apr 2025 19:27:22 +0100 Subject: [PATCH 06/11] some assets updates --- src/content/docs/workers/static-assets/index.mdx | 6 +++++- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/static-assets/index.mdx b/src/content/docs/workers/static-assets/index.mdx index f9060d13184c52b..c1fbc5b8ca61e9e 100644 --- a/src/content/docs/workers/static-assets/index.mdx +++ b/src/content/docs/workers/static-assets/index.mdx @@ -59,6 +59,10 @@ The **assets directory** specified in your [Wrangler configuration file](/worker +:::note +With some build/development tools, including the Cloudflare Vite plugin, you don't need to specify `assets.directory`. This field is functionally equivalent to the build output folder. +::: + By adding an [**assets binding**](/workers/static-assets/binding/#binding), you can directly fetch and serve assets within your Worker code. ```js {13} @@ -83,7 +87,7 @@ export default { By default, if a requested URL matches a file in the static assets directory, that file will always be served — without running Worker code. If no matching asset is found and a Worker is configured, the request will be processed by the Worker instead. -- If no Worker is set up, the [`not_found_handling`](/workers/static-assets/routing/#2-not_found_handling-1) setting in your Wrangler configuration determines what happens next. By default, a `404 Not Found` response is returned. +- If no Worker is set up, the [`not_found_handling`](/workers/static-assets/routing/#not_found_handling-1) setting in your Wrangler configuration determines what happens next. By default, a `404 Not Found` response is returned. - If a Worker is configured and a request does not match a static asset, the Worker will handle the request. The Worker can choose to pass the request to the asset binding (through `env.ASSETS.fetch()`), following the `not_found_handling` rules. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 091a09c771aafbc..3bc77283d6cefe5 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1001,7 +1001,7 @@ You can only configure one collection of assets per Worker. The following options are available under the `assets` key. -- `directory` +- `directory` - Folder of static assets to be served. - Not required if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), which will automatically point to the client build output. From 669886f851792e02b7d9d4e641a70f3982c05b61 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Fri, 4 Apr 2025 14:41:35 +0100 Subject: [PATCH 07/11] update links and env notes --- .../docs/workers/static-assets/index.mdx | 2 +- .../docs/workers/wrangler/commands.mdx | 5 ++ .../docs/workers/wrangler/configuration.mdx | 34 +++++------ .../docs/workers/wrangler/environments.mdx | 58 +++++++++---------- .../partials/workers/vite-environments.mdx | 7 +++ .../partials/workers/workers_sites.mdx | 2 +- 6 files changed, 60 insertions(+), 48 deletions(-) create mode 100644 src/content/partials/workers/vite-environments.mdx diff --git a/src/content/docs/workers/static-assets/index.mdx b/src/content/docs/workers/static-assets/index.mdx index c1fbc5b8ca61e9e..54ee5f4b91954eb 100644 --- a/src/content/docs/workers/static-assets/index.mdx +++ b/src/content/docs/workers/static-assets/index.mdx @@ -60,7 +60,7 @@ The **assets directory** specified in your [Wrangler configuration file](/worker :::note -With some build/development tools, including the Cloudflare Vite plugin, you don't need to specify `assets.directory`. This field is functionally equivalent to the build output folder. +With some build/development tools, including the [Cloudflare Vite plugin](/workers/vite-plugin/), you do not need to specify `assets.directory`. This field is functionally equivalent to the build output folder. ::: By adding an [**assets binding**](/workers/static-assets/binding/#binding), you can directly fetch and serve assets within your Worker code. diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index f923b08d479ef23..c6d8ad5b7512cf0 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -424,6 +424,7 @@ As of Wrangler v3.2.0, `wrangler dev` is supported by any Linux distributions pr - Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to [Bundling](https://developers.cloudflare.com/workers/wrangler/bundling/) for more information. - `--env` - Perform on a specific environment. + - `--compatibility-date` - A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used. - `--compatibility-flags`, `--compatibility-flag` @@ -515,6 +516,7 @@ None of the options for this command are required. Also, many can be set in your - Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to [Bundling](https://developers.cloudflare.com/workers/wrangler/bundling/) for more information. - `--env` - Perform on a specific environment. + - `--outdir` - Path to directory where Wrangler will write the bundled Worker files. - `--compatibility-date` @@ -1415,6 +1417,9 @@ wrangler versions upload [OPTIONS] - Add a version message. Accepts empty string. - `--name` - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/). +- `--env` + - Perform on a specific environment. + diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 3bc77283d6cefe5..04f7f3d68ea6eb6 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -61,7 +61,7 @@ The majority of keys are inheritable, meaning that top-level configuration can b Further, there are a few keys that can _only_ appear at the top-level. -With the [Cloudflare Vite plugin](/workers/local-development/vite/), you select a Wrangler environment at dev or build time via the `CLOUDFLARE_ENV` environment variable. Otherwise, environments are defined in your Wrangler config file as usual. For more detail on using Wrangler environments with the Cloudflare Vite plugin, refer to the [plugin documentation](/workers/local-development/vite#environments). + ## Top-level only keys @@ -82,7 +82,7 @@ Top-level keys apply to the Worker as a whole (and therefore all environments). - `site` - See the [Workers Sites](#workers-sites) section below for more information. Cloudflare Pages and Workers Assets is preferred over this approach. - - This is not supported by the [Cloudflare Vite plugin](/workers/local-development/vite/). + - This is not supported by the [Cloudflare Vite plugin](/workers/vite-plugin/). ## Inheritable keys @@ -132,7 +132,7 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d - `tsconfig` - Path to a custom `tsconfig`. - - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). - `triggers` @@ -141,17 +141,17 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d - `rules` - An ordered list of rules that define which modules to import, and what type to import them as. You will need to specify rules to use `Text`, `Data` and `CompiledWasm` modules, or when you wish to have a `.js` file be treated as an `ESModule` instead of `CommonJS`. - - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). - `build` - Configures a custom build step to be run by Wrangler when building your Worker. Refer to [Custom builds](#custom-builds). - - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). - `no_bundle` - Skip internal build steps and directly deploy your Worker script. You must have a plain JavaScript Worker with no dependencies. - - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). - `find_additional_modules` @@ -159,24 +159,24 @@ At a minimum, the `name`, `main` and `compatibility_date` keys are required to d Any files that match `rules` will be included in the deployed Worker. Defaults to true if `no_bundle` is true, otherwise false. Can only be used with Module format Workers (not Service Worker format). - - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). - `base_dir` - The directory in which module "rules" should be evaluated when including additional files (via `find_additional_modules`) into a Worker deployment. Defaults to the directory containing the `main` entry point of the Worker if not specified. - - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). - `preserve_file_names` - Determines whether Wrangler will preserve the file names of additional modules bundled with the Worker. The default is to prepend filenames with a content hash. For example, `34de60b44167af5c5a709e62a4e20c4f18c9e3b6-favicon.ico`. - - Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). + - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). - `minify` - Minify the Worker script before uploading. - - If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), `minify` is replaced by Vite's [`build.minify`](https://vite.dev/config/build-options.html#build-minify). + - If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), `minify` is replaced by Vite's [`build.minify`](https://vite.dev/config/build-options.html#build-minify). - `logpush` @@ -200,7 +200,7 @@ Non-inheritable keys are configurable at the top-level, but cannot be inherited - `define` - A map of values to substitute when deploying your Worker. - - If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), this is replaced by Vite's [`define`](https://vite.dev/config/shared-options.html#define). + - If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), this is replaced by Vite's [`define`](https://vite.dev/config/shared-options.html#define). - `vars` @@ -382,7 +382,7 @@ head_sampling_rate = 0.1 # 10% of requests are logged ## Custom builds :::note -Not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). +Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). ::: You can configure a custom build step that will be run before your Worker is deployed. Refer to [Custom builds](/workers/wrangler/custom-builds/). @@ -1004,7 +1004,7 @@ The following options are available under the `assets` key. - `directory` - Folder of static assets to be served. - - Not required if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), which will automatically point to the client build output. + - Not required if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), which will automatically point to the client build output. - `binding` @@ -1035,7 +1035,7 @@ assets = { directory = "./public", binding = "ASSETS", html_handling = "force-tr ## Bundling :::note -Wrangler bundling is not applicable if you're using the [Cloudflare Vite plugin](/workers/local-development/vite/). +Wrangler bundling is not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/). ::: Wrangler can operate in two modes: the default bundling mode and `--no-bundle` mode. @@ -1096,7 +1096,7 @@ See https://developers.cloudflare.com/workers/wrangler/bundling/ for more detail ## Local development settings :::note -If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), you should use Vite's [server options]](https://vite.dev/config/server-options.html) instead. +If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), you should use Vite's [server options]](https://vite.dev/config/server-options.html) instead. ::: You can configure various aspects of local development, such as the local protocol or port. @@ -1143,7 +1143,7 @@ local_protocol = "http" ## Module Aliasing :::note -If you're using the [Cloudflare Vite plugin](/workers/local-development/vite/), `alias` is replaced Vite's [`resolve.alias`](https://vite.dev/config/shared-options.html#resolve-alias). +If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), `alias` is replaced Vite's [`resolve.alias`](https://vite.dev/config/shared-options.html#resolve-alias). ::: You can configure Wrangler to replace all calls to import a particular package with a module of your choice, by configuring the `alias` field: @@ -1306,7 +1306,7 @@ This section describes a feature that can be implemented by frameworks and other 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. -For example, when you are using the [Cloudflare Vite plugin](/workers/local-development/vite/), it will generate a Wrangler configuration file when you run `vite build`, which is then used for preview and deployment. +For example, when you are using the [Cloudflare Vite plugin](/workers/vite-plugin/), it will generate a Wrangler configuration file when you run `vite build`, which is then used for preview and deployment. ::: diff --git a/src/content/docs/workers/wrangler/environments.mdx b/src/content/docs/workers/wrangler/environments.mdx index 3b4fa02624c2606..4e118875a586bed 100644 --- a/src/content/docs/workers/wrangler/environments.mdx +++ b/src/content/docs/workers/wrangler/environments.mdx @@ -5,52 +5,52 @@ head: [] description: Use environments to create different configurations for the same Worker application. --- -import { WranglerConfig } from "~/components"; +import { WranglerConfig, Render, Steps } from "~/components"; 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. + +When you create an environment, Cloudflare effectively creates a new Worker with the name `-`. For example, a Worker project named `my-worker` with an environment `dev` would deploy as a Worker named `my-worker-dev`. Review the following environments flow: + 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.]` section. - + -```json -{ - "name": "my-worker", - "env": { - "": { - // environment-specific configuration goes here - } - } -} -``` + ```json + { + "name": "my-worker", + "env": { + "": { + // environment-specific configuration goes here + } + } + } + ``` + - +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. + For example, to set a different route for a Worker in the `dev` environment: -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. + -For example, to set a different route for a Worker in the `dev` environment: + ```toml + name = "your-worker" + route = "example.com" - + [env.dev] + route = "dev.example.com" + ``` -```toml -name = "your-worker" -route = "example.com" + -[env.dev] -route = "dev.example.com" -``` +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`. - -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`. + -:::note - -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 diff --git a/src/content/partials/workers/vite-environments.mdx b/src/content/partials/workers/vite-environments.mdx new file mode 100644 index 000000000000000..6abab3ba5aa19f7 --- /dev/null +++ b/src/content/partials/workers/vite-environments.mdx @@ -0,0 +1,7 @@ +--- +{} +--- + +:::note +If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), you select a Wrangler environment at dev or build time via the `CLOUDFLARE_ENV` environment variable rather than the `--env` flag. Otherwise, environments are defined in your Wrangler config file as usual. For more detail on using Wrangler environments with the Cloudflare Vite plugin, refer to the [plugin documentation](/workers/vite-plugin/reference/cloudflare-environments/). +::: diff --git a/src/content/partials/workers/workers_sites.mdx b/src/content/partials/workers/workers_sites.mdx index 1b522b729ab965d..369db209e37b707 100644 --- a/src/content/partials/workers/workers_sites.mdx +++ b/src/content/partials/workers/workers_sites.mdx @@ -4,5 +4,5 @@ :::caution[Use Workers Static Assets Instead] -You should use [Workers Static Assets](/workers/static-assets/) to host full-stack applications instead of Workers Sites. It has been deprecated in Wrangler v4, and the [Cloudflare Vite plugin](/workers/local-development/vite) does not support Workers Sites. Do not use Workers Sites for new projects. +You should use [Workers Static Assets](/workers/static-assets/) to host full-stack applications instead of Workers Sites. It has been deprecated in Wrangler v4, and the [Cloudflare Vite plugin](/workers/vite-plugin/) does not support Workers Sites. Do not use Workers Sites for new projects. ::: From a3d1c39445dcdcd87b7081c83e1f2b3ba8fc3600 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Fri, 4 Apr 2025 14:45:18 +0100 Subject: [PATCH 08/11] Apply suggestions from code review --- src/content/docs/workers/static-assets/index.mdx | 2 +- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/static-assets/index.mdx b/src/content/docs/workers/static-assets/index.mdx index 54ee5f4b91954eb..c68a09fcb1f3bb4 100644 --- a/src/content/docs/workers/static-assets/index.mdx +++ b/src/content/docs/workers/static-assets/index.mdx @@ -87,7 +87,7 @@ export default { By default, if a requested URL matches a file in the static assets directory, that file will always be served — without running Worker code. If no matching asset is found and a Worker is configured, the request will be processed by the Worker instead. -- If no Worker is set up, the [`not_found_handling`](/workers/static-assets/routing/#not_found_handling-1) setting in your Wrangler configuration determines what happens next. By default, a `404 Not Found` response is returned. +- If no Worker is set up, the [`not_found_handling`](/workers/static-assets/routing/#2-not_found_handling-1) setting in your Wrangler configuration determines what happens next. By default, a `404 Not Found` response is returned. - If a Worker is configured and a request does not match a static asset, the Worker will handle the request. The Worker can choose to pass the request to the asset binding (through `env.ASSETS.fetch()`), following the `not_found_handling` rules. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 04f7f3d68ea6eb6..e8ecbe1a5e32d47 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -9,7 +9,7 @@ description: Use a configuration file to customize the Platform products. --- -import { Render, Type, MetaInfo, WranglerConfig, Details } from "~/components"; +import { Render, Type, MetaInfo, WranglerConfig } from "~/components"; import { FileTree } from "@astrojs/starlight/components"; Wrangler optionally uses a configuration file to customize the development and deployment setup for a Worker. From 361daaceab6dcd1cdb44c50aeea26c8d8bcdbd48 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Fri, 4 Apr 2025 14:52:54 +0100 Subject: [PATCH 09/11] update routing summary --- src/content/partials/workers/workers-assets-routing-summary.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/partials/workers/workers-assets-routing-summary.mdx b/src/content/partials/workers/workers-assets-routing-summary.mdx index 6ba9e0b6a2e4006..0935ff92ec4b099 100644 --- a/src/content/partials/workers/workers-assets-routing-summary.mdx +++ b/src/content/partials/workers/workers-assets-routing-summary.mdx @@ -2,6 +2,6 @@ {} --- -By default, Cloudflare first tries to serve a static asset, and failing that, invokes a Worker if one is present. If there is no Worker, or the Worker uses the asset binding (e.g. `env.ASSETS.fetch(request)`), then Cloudflare will fallback to the behaviour set by [`not_found_handling`](/workers/static-assets/routing/#not_found_handling). +By default, Cloudflare first tries to match a request path against a static asset path, which is based on the file structure of the uploaded asset directory. This is either the directory specified by `assets.directory` in your Wrangler config, or the output directory of a build tool like Vite with the [Cloudflare Vite plugin](/workers/vite-plugin/). Failing that, we invoke a Worker if one is present. If there is no Worker, or the Worker then uses the asset binding, Cloudflare will fallback to the behaviour set by [`not_found_handling`](/workers/static-assets/routing/#not_found_handling). Refer to the [routing documentation](/workers/static-assets/routing/#routing-configuration) for more information on how to routing works with Workers Assets, and how to customize this behavior. From 6ff4810acc9295b41715da6e07bd9366836d78ce Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Mon, 7 Apr 2025 10:40:06 +0100 Subject: [PATCH 10/11] Update src/content/docs/workers/static-assets/index.mdx Co-authored-by: James Opstad <13586373+jamesopstad@users.noreply.github.com> --- src/content/docs/workers/static-assets/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/static-assets/index.mdx b/src/content/docs/workers/static-assets/index.mdx index c68a09fcb1f3bb4..35e1fbfa4f290bc 100644 --- a/src/content/docs/workers/static-assets/index.mdx +++ b/src/content/docs/workers/static-assets/index.mdx @@ -60,7 +60,7 @@ The **assets directory** specified in your [Wrangler configuration file](/worker :::note -With some build/development tools, including the [Cloudflare Vite plugin](/workers/vite-plugin/), you do not need to specify `assets.directory`. This field is functionally equivalent to the build output folder. +If you are using the [Cloudflare Vite plugin](/workers/vite-plugin/), you do not need to specify `assets.directory`. For more information about using static assets with the Vite plugin, refer to the [plugin documentation](/workers/vite-plugin/reference/static-assets/). ::: By adding an [**assets binding**](/workers/static-assets/binding/#binding), you can directly fetch and serve assets within your Worker code. From 4c2d044bd4eb34e846fc89183c57cf1a735e87c4 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Mon, 7 Apr 2025 10:46:51 +0100 Subject: [PATCH 11/11] Apply suggestions from code review Co-authored-by: James Opstad <13586373+jamesopstad@users.noreply.github.com> --- src/content/docs/workers/wrangler/commands.mdx | 1 - src/content/docs/workers/wrangler/configuration.mdx | 4 ++-- src/content/partials/workers/vite-environments.mdx | 2 +- .../partials/workers/workers-assets-routing-summary.mdx | 4 ++-- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index c6d8ad5b7512cf0..2928ae791c87ff9 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -424,7 +424,6 @@ As of Wrangler v3.2.0, `wrangler dev` is supported by any Linux distributions pr - Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to [Bundling](https://developers.cloudflare.com/workers/wrangler/bundling/) for more information. - `--env` - Perform on a specific environment. - - `--compatibility-date` - A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used. - `--compatibility-flags`, `--compatibility-flag` diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index e8ecbe1a5e32d47..be52754d94a5c2b 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -200,7 +200,7 @@ Non-inheritable keys are configurable at the top-level, but cannot be inherited - `define` - A map of values to substitute when deploying your Worker. - - If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), this is replaced by Vite's [`define`](https://vite.dev/config/shared-options.html#define). + - If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), `define` is replaced by Vite's [`define`](https://vite.dev/config/shared-options.html#define). - `vars` @@ -1306,7 +1306,7 @@ This section describes a feature that can be implemented by frameworks and other 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. -For example, when you are using the [Cloudflare Vite plugin](/workers/vite-plugin/), it will generate a Wrangler configuration file when you run `vite build`, which is then used for preview and deployment. +For example, when using the [Cloudflare Vite plugin](/workers/vite-plugin/), an output Worker configuration file is generated as part of the build. This is then used for preview and deployment. ::: diff --git a/src/content/partials/workers/vite-environments.mdx b/src/content/partials/workers/vite-environments.mdx index 6abab3ba5aa19f7..60b61e224b8298d 100644 --- a/src/content/partials/workers/vite-environments.mdx +++ b/src/content/partials/workers/vite-environments.mdx @@ -3,5 +3,5 @@ --- :::note -If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), you select a Wrangler environment at dev or build time via the `CLOUDFLARE_ENV` environment variable rather than the `--env` flag. Otherwise, environments are defined in your Wrangler config file as usual. For more detail on using Wrangler environments with the Cloudflare Vite plugin, refer to the [plugin documentation](/workers/vite-plugin/reference/cloudflare-environments/). +If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), you select the environment at dev or build time via the `CLOUDFLARE_ENV` environment variable rather than the `--env` flag. Otherwise, environments are defined in your Worker config file as usual. For more detail on using environments with the Cloudflare Vite plugin, refer to the [plugin documentation](/workers/vite-plugin/reference/cloudflare-environments/). ::: diff --git a/src/content/partials/workers/workers-assets-routing-summary.mdx b/src/content/partials/workers/workers-assets-routing-summary.mdx index 0935ff92ec4b099..5707edc5c7395a4 100644 --- a/src/content/partials/workers/workers-assets-routing-summary.mdx +++ b/src/content/partials/workers/workers-assets-routing-summary.mdx @@ -2,6 +2,6 @@ {} --- -By default, Cloudflare first tries to match a request path against a static asset path, which is based on the file structure of the uploaded asset directory. This is either the directory specified by `assets.directory` in your Wrangler config, or the output directory of a build tool like Vite with the [Cloudflare Vite plugin](/workers/vite-plugin/). Failing that, we invoke a Worker if one is present. If there is no Worker, or the Worker then uses the asset binding, Cloudflare will fallback to the behaviour set by [`not_found_handling`](/workers/static-assets/routing/#not_found_handling). +By default, Cloudflare first tries to match a request path against a static asset path, which is based on the file structure of the uploaded asset directory. This is either the directory specified by `assets.directory` in your Wrangler config or, in the case of the [Cloudflare Vite plugin](/workers/vite-plugin/), the output directory of the client build. Failing that, we invoke a Worker if one is present. If there is no Worker, or the Worker then uses the asset binding, Cloudflare will fallback to the behaviour set by [`not_found_handling`](/workers/static-assets/routing/#not_found_handling). -Refer to the [routing documentation](/workers/static-assets/routing/#routing-configuration) for more information on how to routing works with Workers Assets, and how to customize this behavior. +Refer to the [routing documentation](/workers/static-assets/routing/#routing-configuration) for more information about how routing works with static assets, and how to customize this behavior.