docs: update Cloudflare deployment guide

[hyunbinseo]

Describe the bug

Recommend nodejs_compat flag instead of putting it in the troubleshooting section. Related:

• Better visibility of async_local_storage_unavailable error #15029

 Svelte error: async_local_storage_unavailable
      The node API `AsyncLocalStorage` is not available, but is required to use async server rendering.
      https://svelte.dev/e/async_local_storage_unavailable

Guide users to set the compatibility_date to the current date. Reference

When you start your project, you should always set compatibility_date to the current date.

{
	"name": "<any-name-you-want>",
	"main": ".svelte-kit/cloudflare/_worker.js",
	"compatibility_date": "2025-01-01", // almost an year has passed
	"assets": {
		"binding": "ASSETS",
		"directory": ".svelte-kit/cloudflare",
	}
}

Add a wrangler.jsonc example for the Cloudflare Pages section.

This helps adding the nodejs_compat flag A LOT easier.

- assets # reserved for Workers only
+ pages_build_output_dir # required

The name 'ASSETS' is reserved in Pages projects. Please use a different name for your Assets binding.

A wrangler.toml file was found but it does not appear to be valid. Did you mean to use wrangler.toml to configure Pages? If so, then make sure the file is valid and contains the pages_build_output_dir property. Skipping file and continuing.

{
	"name": "svelte-kit-cloudflare",
	"pages_build_output_dir": ".svelte-kit/cloudflare", // required
	"compatibility_flags": ["nodejs_compat"], // easier to add
	"compatibility_date": "2025-12-12" // easier to add
}

Remove trailing comma from the wrangler.jsonc example

It does work in Workers but causes parse error in Pages. Related:

• wrangler.jsonc file not utilized in Cloudflare Pages build #14926 (comment)
• Tolerate trailing commas in jsonc format microsoft/vscode#102061

{
	"name": "<any-name-you-want>",
	"main": ".svelte-kit/cloudflare/_worker.js",
	"compatibility_date": "2025-01-01",
	"assets": {
		"binding": "ASSETS",
		"directory": ".svelte-kit/cloudflare", // causes parse error in the Pages build system
	}
}

Add the $schema field in wrangler.jsonc. Requires wrangler installation, but it provides type safety.

{
	"$schema": "./node_modules/wrangler/config-schema.json", // Added

Reproduction

https://github.com/hyunbinseo/svelte-kit-cloudflare

Logs

System Info

System:
  OS: Windows 11 10.0.26200
  CPU: (8) x64 Intel(R) Core(TM) Ultra 7 258V
  Memory: 9.67 GB / 31.48 GB
Binaries:
  Node: 24.12.0 - C:\Users\hyunb\AppData\Local\fnm_multishells\11728_1765560385450\node.EXE
  npm: 11.6.2 - C:\Users\hyunb\AppData\Local\fnm_multishells\11728_1765560385450\npm.CMD
  pnpm: 10.25.0 - C:\Users\hyunb\AppData\Local\fnm_multishells\11728_1765560385450\pnpm.CMD
  Deno: 2.4.0 - C:\Users\hyunb\.deno\bin\deno.EXE
Browsers:
  Chrome: 143.0.7499.109
  Edge: Chromium (140.0.3485.54)
  Firefox: 146.0 - C:\Program Files\Mozilla Firefox\firefox.exe
npmPackages:
  @sveltejs/adapter-cloudflare: ^7.2.4 => 7.2.4
  @sveltejs/kit: ^2.49.2 => 2.49.2
  @sveltejs/vite-plugin-svelte: ^6.2.1 => 6.2.1
  svelte: ^5.45.10 => 5.45.10
  vite: ^7.2.7 => 7.2.7

Severity

annoyance

Additional Information

It would be nice if the sv CLI added wrangler.jsonc during scaffolding.

Choosing the cloudflare adapter basically means CF Workers or Pages deployment.

◇  What would you like to add to your project? (use arrow keys / space bar)
│  sveltekit-adapter
│
◇  Which SvelteKit adapter would you like to use?
│  cloudflare

Could this be achieved? @jycouet

• Install @sveltejs/adapter-cloudflare and wrangler as well
• Create a wrangler.jsonc file with the $schema field set
• Include nodejs_compat flag and set the date to the date of scaffolding

[jycouet]

Since we already have cloudflare option, I guess that it will not be too complicated to add in sv

[elliott-with-the-longest-name-on-github]

@jycouet All of these suggestions seem great, but the nodejs_compat flag one is probably the one I see causing problems most often. I can't see any reason not to turn it on by default, and if it's causing performance issues for someone they can always turn it off (at the risk of losing some of SvelteKit's functionality)

[jycouet]

@elliott-with-the-longest-name-on-github should be move this to sv ?

[hyunbinseo]

I personally hope both.

The scaffolding should be easier, and switching from adapter-auto to adapter-cloudflare should be easier.

Since Pages and Workers require different wrangler.jsonc content, the CLI should provide two options, not one.

Cloudflare is pushing Workers as the default, but users can still choose Pages.

And the Pages error logs are really not helpful:

• wrangler.jsonc file not utilized in Cloudflare Pages build #14926 (comment)
• Nonexistent wrangler.json and wrangler.toml filenames in the log cloudflare/workers-sdk#11631

[ghostdevv]

if it's causing performance issues for someone they can always turn it off (at the risk of losing some of SvelteKit's functionality)

There is a flag that only enables async local storage, nodejs_als, that could be used instead

[ghostdevv]

Also I noticed that the docs sidebar has Cloudflare and Cloudflare Workers, with the latter specifically reffering to workers sites which is very deprecated at this point. We should perhaps consider updating the page titles to better reflect this.

[hyunbinseo]

Didn't know there was a separate nodejs_als flag. Reference

The Node.js AsyncLocalStorage API is a particularly useful feature for Workers. To enable only the AsyncLocalStorage API, use the nodejs_als compatibility flag.

Adding this flag by default could be a solution to this issue as well:

• [WARNING] The package "node:async_hooks" wasn't found on the file system but is built into node. #13668 (comment)

I'd highly recommend enabling the nodejs_als compatibility flag in the meantime if you want to get rid of the warning. This doesn't seem to bundle any extra code in the worker from my testing compared to enabling the nodejs_compat flag which does.

[ghostdevv]

I've opened a PR against sv to introduce these changes, and I found there was a PR to add nodejs_als so updated that with main and bumped. Taking a break for now, then will look at the other docs changes later if no one else wants to!

[ghostdevv]

Somewhat ironically because svelte now dynamically imports node:crypto as a fallback for the global, we now get a warning from wrangler about it when only node_als is enabled. (globalThis.crypto is available so this won't crash, i.e. false positive)

▲ [WARNING] The package "node:crypto" wasn't found on the file system but is built into node.

  Your Worker may throw errors at runtime unless you enable the "nodejs_compat"
  compatibility flag. Refer to
  https://developers.cloudflare.com/workers/runtime-apis/nodejs/ for more details. Imported
  from:
   - .svelte-kit/output/server/chunks/index.js

[elliott-with-the-longest-name-on-github]

Ugh, yes, the node:crypto thing also causes an error if you try to build with ESBuild in an environment that doesn't support node:crypto because it's bad at treeshaking -- I think we need to do the old import("node:" + "crypto") trick to get around it