breaking: require `nodejs_als` compatibility flag #14189

Rich-Harris · 2025-08-12T19:55:20Z

Supersedes #13605.

Honestly I don't know if this guidance is 100% correct — in particular I'm not sure if this contains the right advice around configuration Pages apps (the Workers documentation says 'Cloudflare Pages and Workers Assets is preferred over this approach', while the Pages documentation says 'We recommend using Cloudflare Workers for new projects', so who knows which approach you're meant to use) — but I eventually managed to deploy a test app using the wrangler CLI (though unfortunately not via the git integration/dashboard, which is just spinners for me) and confirmed that this flag does allow you to use getRequestEvent asynchronously.

Erroring on build might be a little aggressive given that most apps don't need getRequestEvent synchronously, but it feels better than failing at runtime for the minority of cases that do.

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 · 2025-08-12T19:55:25Z

🦋 Changeset detected

Latest commit: 2c7b63d

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	Major

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 · 2025-08-12T19:55:48Z

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

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

benmccann · 2025-08-12T20:48:11Z

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

@@ -120,6 +123,19 @@ You may wish to refer to [Cloudflare's documentation for deploying a SvelteKit s

 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/).

+## Node compatibility
+
+SvelteKit uses the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) API internally. You need to enable the `nodejs_als` [compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/), either via the Cloudflare dashboard (if using Pages) or your Wrangler configuration, or your app may break in production.


this says you need to enable it via the dashboard or config file, but it looks like the code will error if it's not in the config file, so maybe we should drop the reference to the dashboard here?

oh right, I've remembered why I hesitated to put this PR up — it's entirely possible that you've set the flag via the dashboard and so don't need the config file at all. The way this should work is that the framework should be able to configure this stuff on the user's behalf but I don't think that exists on Cloudflare

So maybe it should only error for workers, and be a warning for pages? Ugh

The way this should work is that the framework should be able to configure this stuff on the user's behalf but I don't think that exists on Cloudflare

I've talked to the Cloudflare folks and the recommended way to handle this is through a generated Wrangler config: https://developers.cloudflare.com/workers/wrangler/configuration/#generated-wrangler-configuration . I'm not a big fan of it though as it requires duplicating the user's config since it doesn't extend an existing one. Duplicating can also get tricky because any relative paths set need to be changed to resolve from where the generated config is instead of where the original config is.

Co-authored-by: Ben McCann <[email protected]>

eltigerchino · 2025-08-13T01:29:01Z

packages/adapter-cloudflare/index.js

@@ -301,6 +301,22 @@ function validate_wrangler_config(config_file = undefined) {
 		validate_worker_settings(wrangler_config);
 	}

+	const flags = wrangler_config?.compatibility_flags ?? [];
+
+	if (flags.includes('nodejs_compat') && flags.includes('nodejs_als')) {


We should check that a main key is specified in the config too so that it's only needed if a user is deploying a Worker. I've met some folks who are only using the Cloudflare adapter for static sites / single-page apps. The docs should also mention something similar

eltigerchino · 2025-08-13T01:37:37Z

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

@@ -120,6 +123,19 @@ You may wish to refer to [Cloudflare's documentation for deploying a SvelteKit s

 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/).

+## Node compatibility
+
+SvelteKit uses the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) API internally. You need to enable the `nodejs_als` [compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/), either via the Cloudflare dashboard (if using Pages) or your Wrangler configuration, or your app may break in production.


Suggested change

SvelteKit uses the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) API internally. You need to enable the `nodejs_als` [compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/), either via the Cloudflare dashboard (if using Pages) or your Wrangler configuration, or your app may break in production.

SvelteKit uses the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) API internally. You need to enable the `nodejs_als` [compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) via your Wrangler configuration, or your app may break in production.

It may be better to force Cloudflare Pages users to have a Wrangler configuration since it's required when migrating to Cloudflare Workers anyway. Also makes it easier for us since we can't detect dashboard settings during a local build.

breaking: require nodejs_als compatibility flag

f9327cb

Rich-Harris added 2 commits August 12, 2025 15:59

put it alongside other validation code

6593c37

tweak

0d764a5

Rich-Harris mentioned this pull request Aug 12, 2025

docs: mention nodejs_als compatibility flag #13605

Open

benmccann reviewed Aug 12, 2025

View reviewed changes

documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md Outdated Show resolved Hide resolved

benmccann reviewed Aug 12, 2025

View reviewed changes

benmccann added breaking change pkg:adapter-cloudflare labels Aug 12, 2025

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

2c7b63d

Co-authored-by: Ben McCann <[email protected]>

eltigerchino reviewed Aug 13, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

breaking: require `nodejs_als` compatibility flag #14189

breaking: require `nodejs_als` compatibility flag #14189

Rich-Harris commented Aug 12, 2025

Uh oh!

changeset-bot bot commented Aug 12, 2025 •

edited

Loading

Uh oh!

svelte-docs-bot bot commented Aug 12, 2025

Uh oh!

Uh oh!

benmccann Aug 12, 2025

Uh oh!

Rich-Harris Aug 12, 2025

Uh oh!

eltigerchino Aug 13, 2025 •

edited

Loading

Uh oh!

eltigerchino Aug 13, 2025 •

edited

Loading

Uh oh!

eltigerchino Aug 13, 2025 •

edited

Loading

Uh oh!

Uh oh!

	SvelteKit uses the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) API internally. You need to enable the `nodejs_als` [compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/), either via the Cloudflare dashboard (if using Pages) or your Wrangler configuration, or your app may break in production.
	SvelteKit uses the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) API internally. You need to enable the `nodejs_als` [compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) via your Wrangler configuration, or your app may break in production.

Uh oh!

breaking: require nodejs_als compatibility flag #14189

Are you sure you want to change the base?

breaking: require nodejs_als compatibility flag #14189

Conversation

Rich-Harris commented Aug 12, 2025

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

Tests

Changesets

Edits

Uh oh!

changeset-bot bot commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

svelte-docs-bot bot commented Aug 12, 2025

Uh oh!

Uh oh!

benmccann Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

Rich-Harris Aug 12, 2025

Choose a reason for hiding this comment

Uh oh!

eltigerchino Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eltigerchino Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eltigerchino Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

breaking: require `nodejs_als` compatibility flag #14189

breaking: require `nodejs_als` compatibility flag #14189

changeset-bot bot commented Aug 12, 2025 •

edited

Loading

eltigerchino Aug 13, 2025 •

edited

Loading

eltigerchino Aug 13, 2025 •

edited

Loading

eltigerchino Aug 13, 2025 •

edited

Loading