feat: use Workers Static Assets

.changeset/smart-owls-trade.md

@@ -0,0 +1,19 @@
+---
+'@sveltejs/adapter-cloudflare-workers': major
+---
+
+feat: use the new Workers Static Assets feature from Cloudflare
+
+This changes the adapter to stop using the old Workers Sites (kv-asset-handler) approach in favor of the new Workers Static Assets feature, which is embedded into Cloudflare natively.
+
+Also, this change removes the extra esbuild step that was being run inside the adapter, instead relying upon Wrangler to do the bundling.
+
+## Breaking changes and migration
+
+- This version of the adapter requires Wrangler version 3.87.0 or later.
+
+  Run `npm add -D wrangler@latest` (or similar) in your project to update Wrangler.
+
+- The user's Wrangler configuration (`wrangler.toml`) must be migrated from using Workers Sites to using Workers Assets.
+
+For reference, see the previous [Workers Sites documentation](https://developers.cloudflare.com/workers/configuration/sites/configuration/) and the new [Workers Assets documentation](NEW_DOC_URL).

documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md

@@ -4,7 +4,9 @@ title: Cloudflare Workers
 
 To deploy to [Cloudflare Workers](https://workers.cloudflare.com/), use [`adapter-cloudflare-workers`](https://github.com/sveltejs/kit/tree/main/packages/adapter-cloudflare-workers).
 
-> [!NOTE] Unless you have a specific reason to use `adapter-cloudflare-workers`, it's recommended that you use `adapter-cloudflare` instead. Both adapters have equivalent functionality, but Cloudflare Pages offers features like GitHub integration with automatic builds and deploys, preview deployments, instant rollback and so on.
+> [!NOTE] Cloudflare is actively working to bridge the gaps between Workers and Pages and is providing ways to migrate Pages projects to Workers. Many features of Cloudflare Pages are now available in Workers, with Beta support for additional functionality.
+>
+> Both Workers and Pages remain valid options, and the best choice depends on your specific needs. Review the latest feature parity in the [compatibility matrix](https://developers.cloudflare.com/workers/static-assets/compatibility-matrix/) to determine the best fit for your project.
 
 ## Usage
 
@@ -42,20 +44,23 @@ Preferences for the emulated `platform.env` local bindings. See the [getPlatform
 
 ## Basic Configuration
 
-This adapter expects to find a [wrangler.toml/wrangler.json](https://developers.cloudflare.com/workers/platform/sites/configuration) file in the project root. It should look something like this:
+This adapter expects to find a [wrangler.toml/wrangler.toml](https://developers.cloudflare.com/workers/platform/sites/configuration) file in the project root. It should look something like this:
 
 ```toml
 /// file: wrangler.toml
 name = "<your-service-name>"
 account_id = "<your-account-id>"
 
 main = "./.cloudflare/worker.js"
-site.bucket = "./.cloudflare/public"
 
 build.command = "npm run build"
 
-compatibility_date = "2021-11-12"
+compatibility_date = "2025-01-01"
 workers_dev = true
+
+[assets]
+directory = "./.cloudflare/public"
+binding = "ASSETS"
 ```
 
 `<your-service-name>` can be anything. `<your-account-id>` can be found by logging into your [Cloudflare dashboard](https://dash.cloudflare.com) and grabbing it from the end of the URL:
@@ -138,3 +143,63 @@ When deploying to workers, the server generated by SvelteKit is bundled into a s
 ### Accessing the file system
 
 You can't use `fs` in Cloudflare Workers — you must [prerender](page-options#prerender) the routes in question.
+
+
+
+## Migrating from Workers Sites to Workers Static Assets
+
+Cloudflare no longer recommends using Workers Sites. See the official deprecation notice:
+➡ [Workers Sites Documentation (Deprecated)](https://developers.cloudflare.com/workers/configuration/sites/configuration/)
+
+Users should migrate to Workers Static Assets for improved performance and maintainability.
+➡ [Workers Static Assets Documentation](https://developers.cloudflare.com/workers/static-assets/)
+
+This guide provides key information for updating your configuration.
+
+### Update `wrangler.toml`
+
+Replace the **Workers Sites** configuration:
+
+```toml
+# Previous Workers Sites configuration
+name = "<your-site-name>"
+account_id = "<your-account-id>"
+compatibility_date = "2021-11-12"
+main = "./.cloudflare/worker.js"
+
+site.bucket = "./.cloudflare/public"
+```
+
+With the Workers Static Assets configuration:
+
+```toml
+# New Workers Static Assets configuration
+name = "<your-site-name>"
+account_id = "<your-account-id>"
+compatibility_date = "2025-01-01"
+main = "./.cloudflare/worker.js"
+
+[assets]
+directory = "./.cloudflare/public"
+binding = "ASSETS"
+```
+
+The `site.bucket` property is no longer needed and should be removed.
+
+### Asset Serving Behavior Change
+
+In Workers Sites (used with `adapter-cloudflare-workers`), assets were served through the Worker, allowing custom headers such as:
+- `cache-control`
+- `content-type`
+- `x-robots-tag`
+
+However, **Workers Static Assets serves assets directly by default**, bypassing the Worker execution. As a result, these custom headers are no longer applied automatically. Instead, assets now rely on **ETag-based caching** for optimization.
+
+If you need to retain the previous behavior and ensure the Worker runs for every request (allowing custom headers), you can disable direct asset serving:
+
+```toml
+[assets]
+directory = "./.cloudflare/public"
+binding = "ASSETS"
+serve_directly = false
+```

packages/adapter-cloudflare-workers/README.md

@@ -2,7 +2,7 @@
 
 SvelteKit adapter that creates a Cloudflare Workers site using a function for dynamic server rendering.
 
-**Requires [Wrangler v2](https://developers.cloudflare.com/workers/wrangler/get-started/).** Wrangler v1 is no longer supported.
+**Requires [Wrangler v3 or later](https://developers.cloudflare.com/workers/wrangler/get-started/).**.
 
 ## Docs
 

packages/adapter-cloudflare-workers/files/entry.js

@@ -1,8 +1,5 @@
 import { Server } from 'SERVER';
 import { manifest, prerendered, base_path } from 'MANIFEST';
-import { getAssetFromKV, mapRequestToAsset } from '@cloudflare/kv-asset-handler';
-import static_asset_manifest_json from '__STATIC_CONTENT_MANIFEST';
-const static_asset_manifest = JSON.parse(static_asset_manifest_json);
 
 const server = new Server(manifest);
 
@@ -25,7 +22,7 @@ export default {
 		// static assets
 		if (url.pathname.startsWith(app_path)) {
 			/** @type {Response} */
-			const res = await get_asset_from_kv(req, env, context);
+			const res = await env.ASSETS.fetch(req);
 			if (is_error(res.status)) return res;
 
 			const cache_control = url.pathname.startsWith(immutable)
@@ -65,20 +62,11 @@ export default {
 
 		let location = pathname.at(-1) === '/' ? stripped_pathname : pathname + '/';
 
-		if (
-			is_static_asset ||
-			prerendered.has(pathname) ||
-			pathname === version_file ||
-			pathname.startsWith(immutable)
-		) {
-			return get_asset_from_kv(req, env, context, (request, options) => {
-				if (prerendered.has(pathname)) {
-					url.pathname = '/' + prerendered.get(pathname).file;
-					return new Request(url.toString(), request);
-				}
-
-				return mapRequestToAsset(request, options);
-			});
+		if (prerendered.has(pathname)) {
+			url.pathname = '/' + prerendered.get(pathname).file;
+			return env.ASSETS.fetch(new Request(url.toString(), req));
+		} else if (is_static_asset || pathname === version_file || pathname.startsWith(immutable)) {
+			return env.ASSETS.fetch(req);
 		} else if (location && prerendered.has(location)) {
 			if (search) location += search;
 			return new Response('', {
@@ -106,27 +94,6 @@ export default {
 	}
 };
 
-/**
- * @param {Request} req
- * @param {any} env
- * @param {any} context
- */
-async function get_asset_from_kv(req, env, context, map = mapRequestToAsset) {
-	return await getAssetFromKV(
-		{
-			request: req,
-			waitUntil(promise) {
-				return context.waitUntil(promise);
-			}
-		},
-		{
-			ASSET_NAMESPACE: env.__STATIC_CONTENT,
-			ASSET_MANIFEST: static_asset_manifest,
-			mapRequestToAsset: map
-		}
-	);
-}
-
 /**
  * @param {number} status
  * @returns {boolean}