feat: support custom worker output path for easier integration of cloudflare worker handlers

[BattlefieldDuck]

closes #13692
closes #10117
closes #1712

This PR introduces a new workerScriptPath option to AdapterOptions, allowing users to specify the output path for the generated worker script. This option takes precedence over the main field in the wrangler config, enabling more flexible integration with custom Cloudflare Worker handlers.

The Problem

Currently, @sveltejs/adapter-cloudflare outputs the compiled worker to .svelte-kit/cloudflare/_worker.js, and this is hardcoded as the entrypoint via the main field in wrangler.jsonc. This setup makes it difficult to extend the Worker with custom handlers (e.g., fetch, queue, scheduled, etc.) since the generated file isn't easily imported or wrapped.

After this PR

With this change, you can override the default worker script path and use your own file (e.g., src/index.ts) as the main entry in the wrangler config, allowing for easier extension and composition.

Example setup

Update svelte.config.js:

import adapter from '@sveltejs/adapter-cloudflare';

export default {
	kit: {
-		adapter: adapter()
+		adapter: adapter({
+			workerScriptPath: '.svelte-kit/cloudflare/_worker.js'
+		})
	}
};

Update wrangler.jsonc:

{
	"name": "<any-name-you-want>",
- 	"main": ".svelte-kit/cloudflare/_worker.js",
+ 	"main": "src/index.ts",
	"compatibility_date": "2025-01-01",
	"assets": {
		"binding": "ASSETS",
		"directory": ".svelte-kit/cloudflare",
	}
}

Create src/index.ts:

import sveltekit from '../.svelte-kit/cloudflare/_worker.js'

export default {
    async fetch(req, env, ctx) {
        return sveltekit.fetch(req, env, ctx);
    },
} satisfies ExportedHandler<Env>;

You can now extend this file with additional handlers, just like a standard Cloudflare Worker script. For example, you can add queue, scheduled, or custom logic before or after calling sveltekit.fetch().

✅ Result

• The build output (.svelte-kit/cloudflare/_worker.js) is now controlled via workerScriptPath.
• You can define your own worker entrypoint (e.g., src/index.ts).
• This enables easy composition with Cloudflare Worker handlers, such as fetch, queue, scheduled, etc.

---

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.

Tests

• Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

• If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

Edits

• Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4ccdc0b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sveltejs/adapter-cloudflare	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[svelte-docs-bot]

Preview: https://svelte-dev-git-preview-kit-14029-svelte.vercel.app/

[eltigerchino]

Thanks for the PR! Just a heads up that we're exploring a similar route in #14008 which should allow users to specify their own worker and import a request handler from SvelteKit. This follows the same integration pattern which Remix uses with Cloudflare's Vite plugin

[BattlefieldDuck]

Thanks for the PR! Just a heads up that we're exploring a similar route in #14008 which should allow users to specify their own worker and import a request handler from SvelteKit. This follows the same integration pattern which Remix uses with Cloudflare's Vite plugin

Appreciate you sharing that, and #14008 looks like a solid approach! Thanks for all the work you're putting into it, looking forward to seeing it land.