feat: use Workers Static Assets #13427
Conversation
This changes the adapter to stop using the old Workers Sites (kv-asset-handler) approach.
Instead, making use 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, relying upon Wrangler to do the bundling.
The extra esbuild step required a hardcoded list of Node.js compatible modules.
This is no longer needed since Wrangler now manages all of that.
- 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.
Previously a user's `wrangler.toml` might look like:
```toml
name = "<your-site-name>"
account_id = "<your-account-id>"
compatibility_date = "2021-11-12"
main = "./.cloudflare/worker.js"
# Workers Sites configuration
site.bucket = "./.cloudflare/public"
```
Change it to to look like:
```toml
name = "<your-site-name>"
account_id = "<your-account-id>"
compatibility_date = "2021-11-12"`
main = ".svelte-kit/cloudflare/server/index.js"
# Workers Assets configuration
assets = { directory = ".svelte-kit/cloudflare/client" }
```
- Workers Assets defaults to serving assets directly for a matching request, rather than routing it through the Worker code.
The previous adapter would add custom headers to assets responses (such as `cache-control`, `content-type`, and `x-robots-tag`. Such direct asset responses no longer contain these headers - but the will include eTag headers that have proven (in Pages) to be an effective caching strategy for assets.
If you wish to always run the Worker before every request then add `serve_directly = false` to the assets configuration section. For example:
```toml
assets = { directory = ".svelte-kit/cloudflare/client", serve_directly = false }
```
- Removed detailed examples to keep the entry concise. - Provided documentation links for reference.
🦋 Changeset detectedLatest commit: 906c110 The changes in this PR will be included in the next version bump. This PR includes changesets to release 2 packages
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 |
documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md
Outdated
Show resolved
Hide resolved
eltigerchino
added
documentation
eltigerchino
changed the title
|
I don't think the original PR stalled. I'm guessing it's just not ready to be merged or to be continued yet since the Workers Static Assets feature is still in beta. @petebacondarwin what are your thoughts on this? Should we try to get support out during the beta period? |
|
It seems like we are no longer bundling the output ourselves with this PR, it's a good thing! The embedded list of compatible libraries is out of sync with the current list, letting wrangler bundle for us will solve that. Thanks for your work |
|
So |
|
AFAIK, adapter-cloudflare already uses Worker Assets: adapter-cloudlfare-workers not yet, it pushes and fetches assets from a KV |
|
It does make sense given that Cloudflare's own example does use the |
|
Since we (Cloudflare) are going to be supporting Looks like to me there's two ways forwards, depending on what the Svelte team prefers :)
Feel free to let me know if there's any help you need from the Cloudflare side to get this through! |
|
As @emily-shen mentioned, this seems to be a decision for the Svelte team. :) From a cautious personal standpoint, Cloudflare Pages and Cloudflare Workers remain separate services. While efforts are underway to unify their interfaces, the process is still ongoing. Given this, I believe adapter-cloudflare-worker remains relevant. Until full unification is achieved, any resulting duplication is incidental rather than intentional, and I think it is reasonable to allow it for now. |
|
Thanks for this. I've also made some changes to more closely align the two adapters, namely: adapter-cloudflare:
adapter-cloudflare-workers:
both:
|
| }, | ||
| "dependencies": { | ||
| "@cloudflare/workers-types": "^4.20250312.0", | ||
| "esbuild": "^0.24.0" | ||
| "worktop": "0.8.0-next.18" |
There was a problem hiding this comment.
why is this pinned to a prerelease and whats the benefit over the probably much leaner esbuild?
There was a problem hiding this comment.
Worktop is an abstraction of Cloudflare’s caching. It’s already used in the Cloudflare Pages worker but was never added to the workers sites worker so I copied over the implementation
esbuild is still being used, but only as a dev dependency now that we delegate bundling to Wrangler. Esbuild is only used to bundle worktop into the worker before we publish the package
There was a problem hiding this comment.
is worktop bundled into the adapter with esbuild or is esbuild still used by the adapter to add worktop in the users build? if the latter esbuild must remain a dependency.
@lukeed it looks like the last -next release of worktop was a year ago and last code change more like 2. is this still the right tool here? what's missing for a "stable" release
There was a problem hiding this comment.
Change frequency has nothing to do with stability.
The submodule used is here. The "stable" worktop release has a worktop/cache module too, but the one in this @next build is Cloudflare specific. I was experimenting with target-specific platform builds (new territory at the time) then Hono ran with it as their own, so that was deflating.
My 2¢ is that it's still the right tool but you can inline it if the version name is uncomfortable. No other framework has/offers standalone submodules that you can use w/o inheriting the rest of the framework.
Worktop has nothing to do with esbuild. Looks like this PR just moves esbuild to a devdep.. tho wrangler does want to build/bundle (with their own internal esbuild) by default anwyay
There was a problem hiding this comment.
is worktop bundled into the adapter with esbuild or is esbuild still used by the adapter to add worktop in the users build? if the latter esbuild must remain a dependency.
It's the former. We use esbuild to bundle worktop into a worker file then publish this to npm. Finally, the adapter uses this file in the user's build output.
| '@sveltejs/adapter-cloudflare': patch | ||
| --- | ||
|
|
||
| fix: remove `x-robots-tag: noindex` header for `_app/*` files |
There was a problem hiding this comment.
what is the issue this is fixing, is it safe to remove?
There was a problem hiding this comment.
This was added a long time ago but it wasn’t clear why. I did some googling on it and I don’t think it does anything since search engines mostly index pages only I think? If this is useful, we should be adding it to all the adapters anyway
There was a problem hiding this comment.
can we move this to a separate PR then and find out what it was used for? Initial hunch is that crawlers hit these files and incurred cost, so removing it could have negative impact on users that still expect this to work.
closes #13360
closes #13071
closes #13005
closes #12813
closes #13579
This PR builds upon the excellent work by @petebacondarwin in PR #13072, focusing on incorporating reviewer feedback and refining the documentation.
Since the original PR seemed to have stalled, I wanted to help move things forward by addressing the feedback. I didn’t make any code changes—just focused on improving the documentation.
Huge thanks to @petebacondarwin for the initial implementation and to the reviewers for their insights.
Looking forward to any additional feedback to get this merged!
Please don't delete this checklist! Before submitting the PR, please make sure you do the following:
Ideally, include a test that fails without this PR but passes with it.These adapters don't appear to have tests.Tests
pnpm testand lint the project withpnpm lintandpnpm checkChangesets
pnpm changesetand following the prompts. Changesets that add features should beminorand those that fix bugs should bepatch. Please prefix changeset messages withfeat:,fix:, orchore:.Edits