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

[BattlefieldDuck]

closes #13692
closes #10117
closes #1712

This PR allow 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/worker.ts) as the main entry in the wrangler config, allowing for easier extension and composition.

Example setup

Update wrangler.jsonc:

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

Create src/worker.ts:

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

export default {
    async fetch(req, env, ctx): Promise<Response> {
        return sv.fetch(req, env, ctx);
    },

    // other handlers ...
} 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 sv.fetch().

✅ Result

• You can define your own worker entrypoint (e.g., src/worker.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: 778eb71

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/

[teemingc]

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.

[BattlefieldDuck]

I created an example sveltekit project with Durable Object using this pull request package with minimal code changes.

npm install -D https://pkg.pr.new/sveltejs/kit/@sveltejs/adapter-cloudflare@14029

Check this commit: BattlefieldDuck/sveltekit-durable-object-example@02b56e8

[louis-sicko]

I tried it and its perfect!

[teemingc]

We will do this almost exactly the same in Kit 3 (exported fetch handler so the user can use their own worker script) but with the benefit of it also working during development thanks to the Vite environment API and Cloudflare Vite plugin. Closing this for now as we'll work on this soon