From 501562e374379b836c08af1948c583d7f2e31229 Mon Sep 17 00:00:00 2001 From: James Opstad <13586373+jamesopstad@users.noreply.github.com> Date: Fri, 27 Jun 2025 14:28:25 +0100 Subject: [PATCH 1/5] Update Vite plugin static assets page --- .../vite-plugin/reference/static-assets.mdx | 45 +++++++++++++++---- 1 file changed, 36 insertions(+), 9 deletions(-) diff --git a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx index 14359554017dbe3..3c1d5b69a60903d 100644 --- a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx +++ b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx @@ -8,14 +8,17 @@ description: Static assets and the Vite plugin import { WranglerConfig } from "~/components"; -The Vite plugin does not require that you provide the `assets` field in order to enable assets and instead determines whether assets should be included based on whether the `client` environment has been built. -By default, the `client` environment is built if there is an `index.html` file in the root of your project or if `build.rollupOptions.input` is specified in the Vite config. +This guide focuses on the areas of working with static assets that are unique to the Vite plugin. +For more general documentation, see [Static Assets](/workers/static-assets/). -:::note -When using the Cloudflare Vite plugin, the `client` environment is deployed as your static assets. -This typically includes files such as static HTML, front-end JavaScript, CSS, images and fonts. -For more information about using static assets in Vite, refer to [Static Asset Handling](https://vite.dev/guide/assets). -::: +## Configuration + +The Vite plugin does not require that you provide the `assets` field in order to enable assets and instead determines whether assets should be included based on whether the `client` environment has been built. By default, the `client` environment is built if any of the following conditions are met: + +- There is an `index.html` file in the root of your project +- `build.rollupOptions.input` or `environments.client.build.rollupOptions.input` is specified in your Vite config +- You have a non-empty [`public` directory](https://vite.dev/guide/assets#the-public-directory) +- Your entry Worker [imports assets as URLs](https://vite.dev/guide/assets#importing-asset-as-url) On running `vite build`, an output `wrangler.json` configuration file is generated as part of the build output. The `assets.directory` field in this file is automatically populated with the path to your `client` build output. @@ -32,10 +35,34 @@ assets = { not_found_handling = "single-page-application" } +## Features + +The Vite plugin ensures that all of Vite's [static asset handling](https://vite.dev/guide/assets) features are supported in your Worker as well as in your frontend. +This includes importing assets as URLs, inlining assets, importing assets as strings and importing assets from the `public` directory. + +Assets [imported as URLs](https://vite.dev/guide/assets#importing-asset-as-url) can be fetched via the [assets binding](/workers/static-assets/binding/#binding). +As the binding's `fetch` method requires a full URL, we recommend using the request URL as the `base`. +This is demonstrated in the following example: + +```ts +import assetPath from "./my-image.svg"; + +export default { + async fetch(request, env) { + return env.ASSETS.fetch(new URL(assetPath, request.url)); + }, +}; +``` + +Assets imported as URLs in your Worker will automatically be moved from the Worker to the client build output. +When running `vite build` the paths of any moved assets will be displayed in the console. + +:::note +If you are developing a multi-Worker application, assets can only be accessed on the client and in your entry Worker. +::: + ## Headers and redirects Custom [headers](/workers/static-assets/headers/) and [redirects](/workers/static-assets/redirects/) are supported at build, preview and deploy time by adding `_headers` and `_redirects` files to your [`public` directory](https://vite.dev/guide/assets#the-public-directory). The paths in these files should reflect the structure of your client build output. For example, generated assets are typically located in an [assets subdirectory](https://vite.dev/config/build-options#build-assetsdir). - -
From 8c2cb8409b19c674c0dac1afd243dea273a3b727 Mon Sep 17 00:00:00 2001 From: James Opstad <13586373+jamesopstad@users.noreply.github.com> Date: Fri, 27 Jun 2025 14:40:21 +0100 Subject: [PATCH 2/5] Reference run_worker_first in tutorial --- .../docs/workers/vite-plugin/tutorial.mdx | 23 ++++++++++++++----- 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/src/content/docs/workers/vite-plugin/tutorial.mdx b/src/content/docs/workers/vite-plugin/tutorial.mdx index f8aa24a0f6fc61b..c31bc0fc3578382 100644 --- a/src/content/docs/workers/vite-plugin/tutorial.mdx +++ b/src/content/docs/workers/vite-plugin/tutorial.mdx @@ -147,12 +147,8 @@ The `main` field specifies the entry file for your Worker code. ### Add your API Worker ```ts title="worker/index.ts" -interface Env { - ASSETS: Fetcher; -} - export default { - fetch(request, env) { + fetch(request) { const url = new URL(request.url); if (url.pathname.startsWith("/api/")) { @@ -163,7 +159,7 @@ export default { return new Response(null, { status: 404 }); }, -} satisfies ExportedHandler; +} satisfies ExportedHandler; ``` The Worker above will be invoked for any non-navigation request that does not match a static asset. @@ -172,6 +168,21 @@ It returns a JSON response if the `pathname` starts with `/api/` and otherwise r :::note For top-level navigation requests, browsers send a `Sec-Fetch-Mode: navigate` header. If this is present and the URL does not match a static asset, the `not_found_handling` behavior will be invoked rather than the Worker. +This implicit routing is the default behavior. + +If you would instead like to define the routes that invoke your Worker explicitly, you can provide an array of route patterns to [`run_worker_first`](/workers/static-assets/binding/#run_worker_first). +This opts out of interpreting the `Sec-Fetch-Mode` header. + + + +```toml +name = "cloudflare-vite-tutorial" +compatibility_date = "2025-04-03" +assets = { not_found_handling = "single-page-application", run_worker_first = ["/api/*"] } +main = "./worker/index.ts" +``` + + ::: ### Call the API from the client From 1f8b16750afb0dc05aa04d49e418d58c5fc17ab2 Mon Sep 17 00:00:00 2001 From: James Opstad <13586373+jamesopstad@users.noreply.github.com> Date: Fri, 27 Jun 2025 15:33:02 +0100 Subject: [PATCH 3/5] Add changelog entry --- ...-06-27-vite-plugin-full-assets-support.mdx | 30 +++++++++++++++++++ .../vite-plugin/reference/static-assets.mdx | 12 ++++---- 2 files changed, 36 insertions(+), 6 deletions(-) create mode 100644 src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx diff --git a/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx b/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx new file mode 100644 index 000000000000000..53643010812d6bf --- /dev/null +++ b/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx @@ -0,0 +1,30 @@ +--- +title: Enhanced support for static assets with the Cloudflare Vite plugin +description: The Cloudflare Vite plugin now supports using all of Vite's static assets features in your Worker +products: + - workers +date: 2025-06-27T12:00:00Z +--- + +All of Vite's [static asset handling](https://vite.dev/guide/assets) features are now supported in your Worker as well as in your frontend. +These include importing assets as URLs, importing as strings and importing from the `public` directory as well as inlining assets. + +Additionally, assets imported as URLs in your Worker are now automatically moved to the client build output. + +Here's an example that fetches an imported asset using the [assets binding](/workers/static-assets/binding/#binding) and modifies the response. + +```ts +import myImage from "./my-image.png"; + +export default { + async fetch(request, env) { + const response = await env.ASSETS.fetch(new URL(myImage, request.url)); + const modifiedResponse = new Response(response.body, response); + modifiedResponse.headers.append("my-header", "imported-asset"); + + return modifiedResponse; + }, +}; +``` + +See [Static Assets](/workers/vite-plugin/reference/static-assets/) in the Vite plugin docs for more info. diff --git a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx index 3c1d5b69a60903d..0c52b8e9771c133 100644 --- a/src/content/docs/workers/vite-plugin/reference/static-assets.mdx +++ b/src/content/docs/workers/vite-plugin/reference/static-assets.mdx @@ -18,7 +18,7 @@ The Vite plugin does not require that you provide the `assets` field in order to - There is an `index.html` file in the root of your project - `build.rollupOptions.input` or `environments.client.build.rollupOptions.input` is specified in your Vite config - You have a non-empty [`public` directory](https://vite.dev/guide/assets#the-public-directory) -- Your entry Worker [imports assets as URLs](https://vite.dev/guide/assets#importing-asset-as-url) +- Your Worker [imports assets as URLs](https://vite.dev/guide/assets#importing-asset-as-url) On running `vite build`, an output `wrangler.json` configuration file is generated as part of the build output. The `assets.directory` field in this file is automatically populated with the path to your `client` build output. @@ -38,23 +38,23 @@ assets = { not_found_handling = "single-page-application" } ## Features The Vite plugin ensures that all of Vite's [static asset handling](https://vite.dev/guide/assets) features are supported in your Worker as well as in your frontend. -This includes importing assets as URLs, inlining assets, importing assets as strings and importing assets from the `public` directory. +These include importing assets as URLs, importing as strings and importing from the `public` directory as well as inlining assets. Assets [imported as URLs](https://vite.dev/guide/assets#importing-asset-as-url) can be fetched via the [assets binding](/workers/static-assets/binding/#binding). As the binding's `fetch` method requires a full URL, we recommend using the request URL as the `base`. This is demonstrated in the following example: ```ts -import assetPath from "./my-image.svg"; +import myImage from "./my-image.png"; export default { - async fetch(request, env) { - return env.ASSETS.fetch(new URL(assetPath, request.url)); + fetch(request, env) { + return env.ASSETS.fetch(new URL(myImage, request.url)); }, }; ``` -Assets imported as URLs in your Worker will automatically be moved from the Worker to the client build output. +Assets imported as URLs in your Worker will automatically be moved to the client build output. When running `vite build` the paths of any moved assets will be displayed in the console. :::note From 71f5740a67eea73f5de153820cce064c2a2752b7 Mon Sep 17 00:00:00 2001 From: James Opstad <13586373+jamesopstad@users.noreply.github.com> Date: Fri, 27 Jun 2025 17:38:28 +0100 Subject: [PATCH 4/5] PR feedback --- .../2025-06-27-vite-plugin-full-assets-support.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx b/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx index 53643010812d6bf..182bd1e4e52d4f8 100644 --- a/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx +++ b/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx @@ -6,25 +6,31 @@ products: date: 2025-06-27T12:00:00Z --- -All of Vite's [static asset handling](https://vite.dev/guide/assets) features are now supported in your Worker as well as in your frontend. +You can now use any of Vite's [static asset handling](https://vite.dev/guide/assets) features in your Worker as well as in your frontend. These include importing assets as URLs, importing as strings and importing from the `public` directory as well as inlining assets. Additionally, assets imported as URLs in your Worker are now automatically moved to the client build output. -Here's an example that fetches an imported asset using the [assets binding](/workers/static-assets/binding/#binding) and modifies the response. +Here is an example that fetches an imported asset using the [assets binding](/workers/static-assets/binding/#binding) and modifies the response. ```ts +// Import the asset URL +// This returns the resolved path in development and production import myImage from "./my-image.png"; export default { async fetch(request, env) { + // Fetch the asset using the binding const response = await env.ASSETS.fetch(new URL(myImage, request.url)); + // Create a new `Response` object that can be modified const modifiedResponse = new Response(response.body, response); + // Add an additional header modifiedResponse.headers.append("my-header", "imported-asset"); + // Return the modfied response return modifiedResponse; }, }; ``` -See [Static Assets](/workers/vite-plugin/reference/static-assets/) in the Vite plugin docs for more info. +Refer to [Static Assets](/workers/vite-plugin/reference/static-assets/) in the Cloudflare Vite plugin docs for more info. From 40dad246f5e04f2d325546d50776910f896e6cca Mon Sep 17 00:00:00 2001 From: James Opstad <13586373+jamesopstad@users.noreply.github.com> Date: Tue, 1 Jul 2025 10:55:33 +0100 Subject: [PATCH 5/5] Updated changelog date --- ...t.mdx => 2025-07-01-vite-plugin-enhanced-assets-support.mdx} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename src/content/changelog/workers/{2025-06-27-vite-plugin-full-assets-support.mdx => 2025-07-01-vite-plugin-enhanced-assets-support.mdx} (98%) diff --git a/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx b/src/content/changelog/workers/2025-07-01-vite-plugin-enhanced-assets-support.mdx similarity index 98% rename from src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx rename to src/content/changelog/workers/2025-07-01-vite-plugin-enhanced-assets-support.mdx index 182bd1e4e52d4f8..35e6e62c2ccfb32 100644 --- a/src/content/changelog/workers/2025-06-27-vite-plugin-full-assets-support.mdx +++ b/src/content/changelog/workers/2025-07-01-vite-plugin-enhanced-assets-support.mdx @@ -3,7 +3,7 @@ title: Enhanced support for static assets with the Cloudflare Vite plugin description: The Cloudflare Vite plugin now supports using all of Vite's static assets features in your Worker products: - workers -date: 2025-06-27T12:00:00Z +date: 2025-07-01T01:00:00Z --- You can now use any of Vite's [static asset handling](https://vite.dev/guide/assets) features in your Worker as well as in your frontend.