From ed87ba6923accbb9093a241906a4fa315215b58f Mon Sep 17 00:00:00 2001 From: TatLead Date: Tue, 22 Jul 2025 06:01:48 +0800 Subject: [PATCH 1/6] Add workerScriptPath option to adapter-cloudflare Introduces a new 'workerScriptPath' option to AdapterOptions, allowing users to specify the output directory for the worker script. The implementation prioritizes this option over the 'main' field in the wrangler config, providing more flexibility in worker script placement. --- packages/adapter-cloudflare/index.d.ts | 7 +++++++ packages/adapter-cloudflare/index.js | 4 +++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/adapter-cloudflare/index.d.ts b/packages/adapter-cloudflare/index.d.ts index 0c02fb786cee..a40975b5e757 100644 --- a/packages/adapter-cloudflare/index.d.ts +++ b/packages/adapter-cloudflare/index.d.ts @@ -65,6 +65,13 @@ export interface AdapterOptions { * during development and preview. */ platformProxy?: GetPlatformProxyOptions; + + /** + * Worker script `_worker.js` output directory. + * If not specified, the adapter will use the `main` field in your + * wrangler file, or default to `_worker.js` in the output directory. + */ + workerScriptPath?: string; } export interface RoutesJSONSpec { diff --git a/packages/adapter-cloudflare/index.js b/packages/adapter-cloudflare/index.js index 58e95d11736c..82dbe4f62b17 100644 --- a/packages/adapter-cloudflare/index.js +++ b/packages/adapter-cloudflare/index.js @@ -44,7 +44,9 @@ export default function (options = {}) { worker_dest = `${dest}/_worker.js`; } } else { - if (wrangler_config.main) { + if (options.workerScriptPath) { + worker_dest = options.workerScriptPath; + } else if (wrangler_config.main) { worker_dest = wrangler_config.main; } if (wrangler_config.assets?.directory) { From fedaa4a0b4ec236551c57a5accceba94a10ff00c Mon Sep 17 00:00:00 2001 From: TatLead Date: Tue, 22 Jul 2025 07:14:31 +0800 Subject: [PATCH 2/6] Create small-hounds-greet.md --- .changeset/small-hounds-greet.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/small-hounds-greet.md diff --git a/.changeset/small-hounds-greet.md b/.changeset/small-hounds-greet.md new file mode 100644 index 000000000000..6e8c6d955e97 --- /dev/null +++ b/.changeset/small-hounds-greet.md @@ -0,0 +1,5 @@ +--- +'@sveltejs/adapter-cloudflare': minor +--- + +feat: support custom worker output path for easier integration of cloudflare worker handlers From 4ccdc0bfaad87ac3582e2f9647e4d8c680034254 Mon Sep 17 00:00:00 2001 From: TatLead Date: Tue, 22 Jul 2025 09:44:39 +0800 Subject: [PATCH 3/6] Update 60-adapter-cloudflare.md --- .../60-adapter-cloudflare.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md index 0e438e5b0f12..573e5629eb7a 100644 --- a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md +++ b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md @@ -25,6 +25,7 @@ export default { adapter: adapter({ // See below for an explanation of these options config: undefined, + workerScriptPath: undefined, platformProxy: { configPath: undefined, environment: undefined, @@ -46,6 +47,12 @@ export default { 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. +### workerScriptPath + +Specifies the output path of the generated Worker script file (e.g. `.svelte-kit/cloudflare/_worker.js`). By default, the adapter relies on the `main` field in your Wrangler configuration file to determine the Worker entrypoint. Setting this option allows you to control where the adapter emits the compiled Worker script. + +This is useful when you want to define your own Worker entrypoint (e.g. `src/index.ts`) that imports and wraps the SvelteKit handler, making it easier to add custom Cloudflare Worker handlers such as fetch, scheduled, or queue. + ### 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. @@ -227,3 +234,58 @@ assets.binding = "ASSETS"+++ }+++ } ``` + +## Cloudflare Worker Handlers + +The `workerScriptPath` option allows you to control where the adapter outputs the compiled Worker script. + +By default, the Cloudflare adapter writes the compiled Worker to `.svelte-kit/cloudflare/_worker.js`, and this file is referenced as the `main` entry in your `wrangler.toml` or `wrangler.jsonc`. + +If you want to define your own custom Worker entrypoint (e.g. `src/index.ts`) to add additional handlers like `fetch`, `scheduled`, or `queue`, you can specify the generated script path using this option. + +### svelte.config.js + +```ts +/// file: svelte.config.js +import adapter from '@sveltejs/adapter-cloudflare'; + +export default { + kit: { +--- adapter: adapter()--- ++++ adapter: adapter({ + workerScriptPath: '.svelte-kit/cloudflare/_worker.js' + })+++ + } +}; +``` + +### wrangler.toml + +```toml +/// file: wrangler.toml +---main = ".svelte-kit/cloudflare/_worker.js"--- ++++main = "src/index.ts"+++ +``` + +### wrangler.jsonc + +```jsonc +/// file: wrangler.jsonc +{ +--- "main": ".svelte-kit/cloudflare/_worker.js",--- ++++ "main": "src/index.ts",+++ +} +``` + +### src/index.ts + +```ts +/// file: src/index.ts +import sveltekit from '../.svelte-kit/cloudflare/_worker.js'; + +export default { + async fetch(request, env, ctx) { + return sveltekit.fetch(request, env, ctx); + }, +} satisfies ExportedHandler; +``` From bc4954697ac27a8232fd3de4abd6f73a7161d03a Mon Sep 17 00:00:00 2001 From: TatLead Date: Sat, 1 Nov 2025 07:00:32 +0800 Subject: [PATCH 4/6] Remove workerScriptPath option from Cloudflare adapter Eliminates the workerScriptPath option from AdapterOptions and related logic in the Cloudflare adapter. The worker script path is now determined solely by the wrangler config or defaults, simplifying configuration. --- packages/adapter-cloudflare/index.d.ts | 7 ------- packages/adapter-cloudflare/index.js | 5 ----- 2 files changed, 12 deletions(-) diff --git a/packages/adapter-cloudflare/index.d.ts b/packages/adapter-cloudflare/index.d.ts index a40975b5e757..0c02fb786cee 100644 --- a/packages/adapter-cloudflare/index.d.ts +++ b/packages/adapter-cloudflare/index.d.ts @@ -65,13 +65,6 @@ export interface AdapterOptions { * during development and preview. */ platformProxy?: GetPlatformProxyOptions; - - /** - * Worker script `_worker.js` output directory. - * If not specified, the adapter will use the `main` field in your - * wrangler file, or default to `_worker.js` in the output directory. - */ - workerScriptPath?: string; } export interface RoutesJSONSpec { diff --git a/packages/adapter-cloudflare/index.js b/packages/adapter-cloudflare/index.js index b5ee221f2e45..9e81ab5bcc52 100644 --- a/packages/adapter-cloudflare/index.js +++ b/packages/adapter-cloudflare/index.js @@ -58,11 +58,6 @@ export default function (options = {}) { worker_dest = `${dest}/_worker.js`; } } else { - if (options.workerScriptPath) { - worker_dest = options.workerScriptPath; - } else if (wrangler_config.main) { - worker_dest = wrangler_config.main; - } if (wrangler_config.assets?.directory) { // wrangler doesn't resolve `assets.directory` to an absolute path unlike // `main` and `pages_build_output_dir` so we need to do it ourselves here From f410e8affbf942a680590fd88a644cf5c042424a Mon Sep 17 00:00:00 2001 From: TatLead Date: Sat, 1 Nov 2025 07:44:49 +0800 Subject: [PATCH 5/6] Update Cloudflare adapter docs for custom Worker entrypoint Removed documentation for the deprecated `workerScriptPath` option and added guidance on defining a custom Worker entrypoint for Cloudflare Workers. The new section explains how to wrap the SvelteKit handler and configure Wrangler to use a custom entry file, streamlining the process for adding additional Worker handlers. --- .../60-adapter-cloudflare.md | 95 +++++++------------ 1 file changed, 33 insertions(+), 62 deletions(-) diff --git a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md index 5864a53a5d01..2e0d591567e7 100644 --- a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md +++ b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md @@ -26,7 +26,6 @@ const config = { adapter: adapter({ // See below for an explanation of these options config: undefined, - workerScriptPath: undefined, platformProxy: { configPath: undefined, environment: undefined, @@ -50,12 +49,6 @@ export default 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. -### workerScriptPath - -Specifies the output path of the generated Worker script file (e.g. `.svelte-kit/cloudflare/_worker.js`). By default, the adapter relies on the `main` field in your Wrangler configuration file to determine the Worker entrypoint. Setting this option allows you to control where the adapter emits the compiled Worker script. - -This is useful when you want to define your own Worker entrypoint (e.g. `src/index.ts`) that imports and wraps the SvelteKit handler, making it easier to add custom Cloudflare Worker handlers such as fetch, scheduled, or queue. - ### 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. @@ -106,6 +99,39 @@ When building for Cloudflare Workers, this adapter expects to find a [Wrangler c } ``` +### Worker entrypoint + +Handlers are methods on Workers that can receive and process external inputs, and can be invoked from outside your Worker. + +You can define your own custom Worker entrypoint (e.g. `src/worker.ts`) to add additional [Cloudflare Workers Handlers](https://developers.cloudflare.com/workers/runtime-apis/handlers/). + +```ts +/// file: src/worker.ts +import sv from '../.svelte-kit/cloudflare/_worker.js'; + +export default { + async fetch(request, env, ctx) { + return sv.fetch(request, env, ctx); + }, + + // other handlers ... +} satisfies ExportedHandler; +``` + +```jsonc +/// file: wrangler.jsonc +{ + "name": "", +--- "main": ".svelte-kit/cloudflare/_worker.js",--- ++++ "main": "src/worker.ts",+++ + "compatibility_date": "2025-01-01", + "assets": { + "binding": "ASSETS", + "directory": ".svelte-kit/cloudflare", + } +} +``` + ### Deployment Please follow the [framework guide](https://developers.cloudflare.com/workers/frameworks/framework-guides/svelte/) for Cloudflare Workers to begin. @@ -261,58 +287,3 @@ assets.binding = "ASSETS" # Exclude this if you don't have a `main` key configur }+++ } ``` - -## Cloudflare Worker Handlers - -The `workerScriptPath` option allows you to control where the adapter outputs the compiled Worker script. - -By default, the Cloudflare adapter writes the compiled Worker to `.svelte-kit/cloudflare/_worker.js`, and this file is referenced as the `main` entry in your `wrangler.toml` or `wrangler.jsonc`. - -If you want to define your own custom Worker entrypoint (e.g. `src/index.ts`) to add additional handlers like `fetch`, `scheduled`, or `queue`, you can specify the generated script path using this option. - -### svelte.config.js - -```ts -/// file: svelte.config.js -import adapter from '@sveltejs/adapter-cloudflare'; - -export default { - kit: { ---- adapter: adapter()--- -+++ adapter: adapter({ - workerScriptPath: '.svelte-kit/cloudflare/_worker.js' - })+++ - } -}; -``` - -### wrangler.toml - -```toml -/// file: wrangler.toml ----main = ".svelte-kit/cloudflare/_worker.js"--- -+++main = "src/index.ts"+++ -``` - -### wrangler.jsonc - -```jsonc -/// file: wrangler.jsonc -{ ---- "main": ".svelte-kit/cloudflare/_worker.js",--- -+++ "main": "src/index.ts",+++ -} -``` - -### src/index.ts - -```ts -/// file: src/index.ts -import sveltekit from '../.svelte-kit/cloudflare/_worker.js'; - -export default { - async fetch(request, env, ctx) { - return sveltekit.fetch(request, env, ctx); - }, -} satisfies ExportedHandler; -``` From 343627bc75b686df37d0248c1d9ca4005c92e83b Mon Sep 17 00:00:00 2001 From: TatLead Date: Sat, 1 Nov 2025 08:32:57 +0800 Subject: [PATCH 6/6] Add explicit return type to fetch function The fetch function in the Cloudflare Worker example now explicitly returns a Promise, improving type safety and clarity in TypeScript usage. --- documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md index 2e0d591567e7..b5ae6a3b9071 100644 --- a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md +++ b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md @@ -110,7 +110,7 @@ You can define your own custom Worker entrypoint (e.g. `src/worker.ts`) to add a import sv from '../.svelte-kit/cloudflare/_worker.js'; export default { - async fetch(request, env, ctx) { + async fetch(request, env, ctx): Promise { return sv.fetch(request, env, ctx); },