feat: Cloudflare Vite plugin integration

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

@@ -2,13 +2,13 @@
 title: Cloudflare
 ---
 
-To deploy to [Cloudflare Workers](https://workers.cloudflare.com/) or [Cloudflare Pages](https://pages.cloudflare.com/), use [`adapter-cloudflare`](https://github.com/sveltejs/kit/tree/main/packages/adapter-cloudflare).
+To deploy to [Cloudflare Workers](https://workers.cloudflare.com/), use [`adapter-cloudflare`](https://github.com/sveltejs/kit/tree/main/packages/adapter-cloudflare).
 
-This adapter will be installed by default when you use [`adapter-auto`](adapter-auto). If you plan on staying with Cloudflare, you can switch from [`adapter-auto`](adapter-auto) to using this adapter directly so that `event.platform` is emulated during local development, type declarations are automatically applied, and the ability to set Cloudflare-specific options is provided.
+This adapter will be installed by default when you use [`adapter-auto`](adapter-auto). If you plan on staying with Cloudflare Workers, you can switch from [`adapter-auto`](adapter-auto) to using this adapter directly so that `event.platform` is emulated during local development, type declarations are automatically applied, and the ability to set Cloudflare-specific options is provided.
 
 ## Comparisons
 
-- `adapter-cloudflare` – supports all SvelteKit features; builds for Cloudflare Workers Static Assets and Cloudflare Pages
+- `adapter-cloudflare` – supports all SvelteKit features; builds for Cloudflare Workers Static Assets
 - `adapter-cloudflare-workers` – deprecated. Supports all SvelteKit features; builds for Cloudflare Workers Sites
 - `adapter-static` – only produces client-side static assets; compatible with Cloudflare Workers Static Assets and Cloudflare Pages
 
@@ -23,112 +23,69 @@ import adapter from '@sveltejs/adapter-cloudflare';
 /** @type {import('@sveltejs/kit').Config} */
 const config = {
 	kit: {
-		adapter: adapter({
-			// See below for an explanation of these options
-			config: undefined,
-			platformProxy: {
-				configPath: undefined,
-				environment: undefined,
-				persist: undefined
-			},
-			fallback: 'plaintext',
-			routes: {
-				include: ['/*'],
-				exclude: ['<all>']
-			}
-		})
+		adapter: adapter()
 	}
 };
 
 export default config;
 ```
 
-## Options
-
-### config
-
-Path to your [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/). If you would like to use a Wrangler configuration filename other than `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml` you can specify it using this option.
-
-### platformProxy
-
-Preferences for the emulated `platform.env` local bindings. See the [getPlatformProxy](https://developers.cloudflare.com/workers/wrangler/api/#parameters-1) Wrangler API documentation for a full list of options.
-
-### fallback
-
-Whether to render a plaintext 404.html page or a rendered SPA fallback page for non-matching asset requests.
-
-For Cloudflare Workers, the default behaviour is to return a null-body 404-status response for non-matching assets requests. However, if the [`assets.not_found_handling`](https://developers.cloudflare.com/workers/static-assets/routing/#2-not_found_handling) Wrangler configuration setting is set to `"404-page"`, this page will be served if a request fails to match an asset. If `assets.not_found_handling` is set to `"single-page-application"`, the adapter will render a SPA fallback `index.html` page regardless of the `fallback` option specified.
+And also to your `vite.config.js`:
 
-For Cloudflare Pages, this page will only be served when a request that matches an entry in `routes.exclude` fails to match an asset.
-
-Most of the time `plaintext` is sufficient, but if you are using `routes.exclude` to manually exclude a set of prerendered pages without exceeding the 100 route limit, you may wish to use `spa` instead to avoid showing an unstyled 404 page to users.
-
-See Cloudflare Pages' [Not Found behaviour](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior) for more info.
-
-### routes
-
-Only for Cloudflare Pages. Allows you to customise the [`_routes.json`](https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file) file generated by `adapter-cloudflare`.
+```js
+/// file: vite.config.js
+import adapter from '@sveltejs/adapter-cloudflare';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [
+		sveltekit({
+			adapter: adapter({
+				// See below for an explanations of these options
+				vitePluginOptions: undefined
+			})
+		})
+	]
+});
+```
 
-- `include` defines routes that will invoke a function, and defaults to `['/*']`
-- `exclude` defines routes that will _not_ invoke a function — this is a faster and cheaper way to serve your app's static assets. This array can include the following special values:
-	- `<build>` contains your app's build artifacts (the files generated by Vite)
-	- `<files>` contains the contents of your `static` directory
-	- `<redirects>` contains a list of pathnames from your [`_redirects` file](https://developers.cloudflare.com/pages/configuration/redirects/) at the root
-	- `<prerendered>` contains a list of prerendered pages
-	- `<all>` (the default) contains all of the above
+## Options
 
-You can have up to 100 `include` and `exclude` rules combined. Generally you can omit the `routes` options, but if (for example) your `<prerendered>` paths exceed that limit, you may find it helpful to manually create an `exclude` list that includes `'/articles/*'` instead of the auto-generated `['/articles/foo', '/articles/bar', '/articles/baz', ...]`.
+### vitePluginOptions
 
-## Cloudflare Workers
+// TODO:
 
-### Basic configuration
+## Customising your worker
 
-When building for Cloudflare Workers, this adapter expects to find a [Wrangler configuration file](https://developers.cloudflare.com/workers/configuration/sites/configuration/) in the project root. It should look something like this:
+You can customise your worker by creating a new file and specifying the path to it in your [Wrangler configuration file](https://developers.cloudflare.com/workers/configuration/sites/configuration/).
 
 ```jsonc
 /// file: wrangler.jsonc
 {
-	"name": "<any-name-you-want>",
-	"main": ".svelte-kit/cloudflare/_worker.js",
-	"compatibility_flags": ["nodejs_als"],
-	"compatibility_date": "<YYYY-MM-DD>",
-	"assets": {
-		"binding": "ASSETS",
-		"directory": ".svelte-kit/cloudflare",
-	}
+	"main": "src/worker.js",
 }
 ```
 
-### Deployment
-
-You can use the Wrangler CLI to deploy your application by running `npx wrangler deploy` or use the [Cloudflare Git integration](https://developers.cloudflare.com/workers/ci-cd/builds/) to enable automatic builds and deployments on push.
-
-## Cloudflare Pages
-
-### Deployment
-
-Please follow the [Get Started Guide](https://developers.cloudflare.com/pages/get-started/) for Cloudflare Pages to begin.
-
-If you're using the [Git integration](https://developers.cloudflare.com/pages/get-started/git-integration/), your build settings should look like this:
-
-- Framework preset – SvelteKit
-- Build command – `npm run build` or `vite build`
-- Build output directory – `.svelte-kit/cloudflare`
-
+Inside your worker file, you can reproduce the SvelteKit request handling behaviour by importing the `fetch` method from `@sveltejs/adapter-cloudflare/worker`.
 
-Once configured, go to the **Runtime** section of your project settings, and add the `nodejs_als` compatibility flag to enable the [Node.js AsyncLocalStorage](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#nodejs-asynclocalstorage). Alternatively, do this in your wrangler config using the `compatibility_flags` array.
-
-### Further reading
+```js
+/// file: src/worker.js
+import { fetch } from '@sveltejs/adapter-cloudflare/worker';
 
-You may wish to refer to [Cloudflare's documentation for deploying a SvelteKit site on Cloudflare Pages](https://developers.cloudflare.com/pages/framework-guides/deploy-a-svelte-kit-site/).
+export default {
+	fetch
+	// Add other types of handlers here
+}
+```
 
-### Notes
+## Deployment
 
-Functions contained in the [`/functions` directory](https://developers.cloudflare.com/pages/functions/routing/) at the project's root will _not_ be included in the deployment. Instead, functions should be implemented as [server endpoints](routing#server) in your SvelteKit app, which is compiled to a [single `_worker.js` file](https://developers.cloudflare.com/pages/functions/advanced-mode/).
+You can use the Wrangler CLI to deploy your application by running `npx wrangler deploy` or use the [Cloudflare Git integration](https://developers.cloudflare.com/workers/ci-cd/builds/) to enable automatic builds and deployments on push.
 
 ## Runtime APIs
 
-The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object contains your project's [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/), which consist of KV/DO namespaces, etc. It is passed to SvelteKit via the `platform` property, along with [`ctx`](https://developers.cloudflare.com/workers/runtime-apis/context/), [`caches`](https://developers.cloudflare.com/workers/runtime-apis/cache/), and [`cf`](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties), meaning that you can access it in hooks and endpoints:
+The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object contains your project's [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/), which consist of KV/DO namespaces, etc. It is passed to SvelteKit via the `platform` property, along with [`ctx`](https://developers.cloudflare.com/workers/runtime-apis/context/), [`caches`](https://developers.cloudflare.com/workers/runtime-apis/cache/), and [`cf`](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties) meaning that you can access it in hooks and endpoints:
 
 ```js
 // @filename: ambient.d.ts
@@ -155,19 +112,16 @@ export async function POST({ request, platform }) {
 
 > [!NOTE] SvelteKit's built-in [`$env` module]($env-static-private) should be preferred for environment variables.
 
-To make these types available to your app, install [`@cloudflare/workers-types`](https://www.npmjs.com/package/@cloudflare/workers-types) and reference them in your `src/app.d.ts`:
+After configuring the bindings in your Wrangler configuration file, you can make the types available by running [`npx wrangler types`](https://developers.cloudflare.com/workers/languages/typescript/) and referencing the `Env` type in your `src/app.d.ts`:
 
 ```ts
 /// file: src/app.d.ts
-+++import { KVNamespace, DurableObjectNamespace } from '@cloudflare/workers-types';+++
++++import { Env } from '../worker-configuration.d.ts';+++
 
 declare global {
 	namespace App {
 		interface Platform {
-+++			env: {
-				YOUR_KV_NAMESPACE: KVNamespace;
-				YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
-			};+++
++++			env: Env;+++
 		}
 	}
 }
@@ -177,9 +131,7 @@ export {};
 
 ### Testing locally
 
-Cloudflare specific values in the `platform` property are emulated during dev and preview modes. Local [bindings](https://developers.cloudflare.com/workers/wrangler/configuration/#bindings) are created based on your [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/) and are used to populate `platform.env` during development and preview. Use the adapter config [`platformProxy` option](#Options-platformProxy) to change your preferences for the bindings.
-
-For testing the build, you should use [Wrangler](https://developers.cloudflare.com/workers/wrangler/) version 4. Once you have built your site, run `wrangler dev .svelte-kit/cloudflare/_worker.js` if you're testing for Cloudflare Workers or `wrangler pages dev .svelte-kit/cloudflare` for Cloudflare Pages.
+Cloudflare specific values in the `platform` property are emulated during dev and preview modes through [Cloudflare's Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/). [Bindings](https://developers.cloudflare.com/workers/wrangler/configuration/#bindings) are created based on your [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/) and are used to populate `platform.env`.
 
 ## Headers and redirects
 
@@ -212,6 +164,10 @@ Instead, use the [`read`]($app-server#read) function from `$app/server` to acces
 
 Alternatively, you can [prerender](page-options#prerender) the routes in question.
 
+## Migrating from Pages
+
+TODO:
+
 ## Migrating from Workers Sites
 
 Cloudflare no longer recommends using [Workers Sites](https://developers.cloudflare.com/workers/configuration/sites/configuration/) and instead recommends using [Workers Static Assets](https://developers.cloudflare.com/workers/static-assets/). To migrate, replace `@sveltejs/adapter-cloudflare-workers` with `@sveltejs/adapter-cloudflare` and remove all `site` configuration settings from your Wrangler configuration file, then add the `assets.directory` and `assets.binding` configuration settings:

packages/adapter-cloudflare/ambient.d.ts

@@ -10,7 +10,7 @@ declare global {
 			env: unknown;
 			ctx: ExecutionContext;
 			caches: CacheStorage;
-			cf?: IncomingRequestCfProperties;
+			cf: IncomingRequestCfProperties;
 		}
 	}
 }

packages/adapter-cloudflare/index.d.ts

@@ -1,79 +1,39 @@
+import { PluginConfig } from '@cloudflare/vite-plugin';
 import { Adapter } from '@sveltejs/kit';
 import './ambient.js';
-import { GetPlatformProxyOptions } from 'wrangler';
 
 export default function plugin(options?: AdapterOptions): Adapter;
 
 export interface AdapterOptions {
 	/**
-	 * Path to your [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/).
+	 * Options to pass to the Cloudflare Vite plugin.
+	 * @see https://developers.cloudflare.com/workers/vite-plugin/reference/api/#interface-pluginconfig
 	 */
-	config?: string;
+	vitePluginOptions?: PluginConfig;
 	/**
 	 * Whether to render a plaintext 404.html page or a rendered SPA fallback page
 	 * for non-matching asset requests.
 	 *
-	 * For Cloudflare Workers, the default behaviour is to return a null-body
+	 * The default behaviour is to return a null-body
 	 * 404-status response for non-matching assets requests. However, if the
 	 * [`assets.not_found_handling`](https://developers.cloudflare.com/workers/static-assets/routing/#2-not_found_handling)
 	 * Wrangler configuration setting is set to `"404-page"`, this page will be
 	 * served if a request fails to match an asset. If `assets.not_found_handling`
 	 * is set to `"single-page-application"`, the adapter will render a SPA fallback
 	 * `index.html` page regardless of the `fallback` option specified.
-	 *
-	 * For Cloudflare Pages, this page will only be served when a request that
-	 * matches an entry in `routes.exclude` fails to match an asset.
-	 *
-	 * Most of the time `plaintext` is sufficient, but if you are using `routes.exclude` to manually
-	 * exclude a set of prerendered pages without exceeding the 100 route limit, you may wish to
-	 * use `spa` instead to avoid showing an unstyled 404 page to users.
-	 *
-	 * See [Cloudflare Pages' Not Found behavior](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior) for more info.
-	 *
 	 * @default 'plaintext'
+	 * @deprecated removed in 8.0.0. Configure `assets.not_found_handling` in your Wrangler configuration file instead
 	 */
 	fallback?: 'plaintext' | 'spa';
-
-	/**
-	 * Only for Cloudflare Pages. Customize the automatically-generated [`_routes.json`](https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file) file.
-	 */
-	routes?: {
-		/**
-		 * Routes that will be invoked by functions. Accepts wildcards.
-		 * @default ["/*"]
-		 */
-		include?: string[];
-
-		/**
-		 * Routes that will not be invoked by functions. Accepts wildcards.
-		 * `exclude` takes priority over `include`.
-		 *
-		 * To have the adapter automatically exclude certain things, you can use these placeholders:
-		 *
-		 * - `<build>` to exclude build artifacts (files generated by Vite)
-		 * - `<files>` for the contents of your `static` directory
-		 * - `<prerendered>` for prerendered routes
-		 * - `<all>` to exclude all of the above
-		 *
-		 * @default ["<all>"]
-		 */
-		exclude?: string[];
-	};
-
 	/**
 	 * Config object passed to [`getPlatformProxy`](https://developers.cloudflare.com/workers/wrangler/api/#getplatformproxy)
 	 * during development and preview.
+	 * @deprecated removed in 8.0.0. Use `vitePluginOptions` instead
 	 */
-	platformProxy?: GetPlatformProxyOptions;
-}
-
-/**
- * The JSON format of the {@link https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file | `_routes.json`}
- * file that controls when the Cloudflare Pages Function is invoked.
- */
-export interface RoutesJSONSpec {
-	version: 1;
-	description: string;
-	include: string[];
-	exclude: string[];
+	platformProxy?: Record<string, any>;
+	/**
+	 * Path to your [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/).
+	 * @deprecated removed in 8.0.0. Use `vitePluginOptions.configPath` instead
+	 */
+	config?: string;
 }