Cloudflare Workers

[!NOTE] adapter-cloudflare-workers has been deprecated in favour of adapter-cloudflare. We recommend using adapter-cloudflare to deploy to Cloudflare Workers with Static Assets since Cloudflare Workers Sites will be deprecated in favour of it.

To deploy to Cloudflare Workers with Workers Sites, use adapter-cloudflare-workers.

Usage

Install with npm i -D @sveltejs/adapter-cloudflare-workers, then add the adapter to your svelte.config.js:

// @errors: 2307
/// file: svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare-workers';

/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		adapter: adapter({
			// see below for options that can be set here
		})
	}
};

export default config;

Options

config

Path to your Wrangler configuration file. If you would like to use a Wrangler configuration filename other than wrangler.jsonc, wrangler.json, or wrangler.toml you can specify it using this option.

platformProxy

Preferences for the emulated platform.env local bindings. See the getPlatformProxy Wrangler API documentation for a full list of options.

Basic Configuration

This adapter expects to find a Wrangler configuration file in the project root. It should look something like this:

/// file: wrangler.jsonc
{
	"name": "<your-service-name>",
	"account_id": "<your-account-id>",
	"main": "./.cloudflare/worker.js",
	"site": {
		"bucket": "./.cloudflare/public"
	},
	"build": {
		"command": "npm run build"
	},
	"compatibility_date": "2021-11-12"
}

<your-service-name> can be anything. <your-account-id> can be found by running wrangler whoami using the Wrangler CLI tool or by logging into your Cloudflare dashboard and grabbing it from the end of the URL:

https://dash.cloudflare.com/<your-account-id>/home

[!NOTE] You should add the .cloudflare directory (or whichever directories you specified for main and site.bucket) and the .wrangler directory to your .gitignore.

You will need to install Wrangler and log in, if you haven't already:

npm i -D wrangler
wrangler login

Then, you can build your app and deploy it:

wrangler deploy

Runtime APIs

The env object contains your project's bindings, which consist of KV/DO namespaces, etc. It is passed to SvelteKit via the platform property, along with ctx, caches, and cf, meaning that you can access it in hooks and endpoints:

// @filename: ambient.d.ts
import { DurableObjectNamespace } from '@cloudflare/workers-types';

declare global {
	namespace App {
		interface Platform {
			env: {
				YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
			};
		}
	}
}
// @filename: +server.js
// ---cut---
// @errors: 2355 2322
/// file: +server.js
/** @type {import('./$types').RequestHandler} */
export async function POST({ request, platform }) {
	const x = platform?.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}

[!NOTE] SvelteKit's built-in $env module should be preferred for environment variables.

To make these types available to your app, install @cloudflare/workers-types and reference them in your src/app.d.ts:

/// file: src/app.d.ts
+++import { KVNamespace, DurableObjectNamespace } from '@cloudflare/workers-types';+++

declare global {
	namespace App {
		interface Platform {
+++			env?: {
				YOUR_KV_NAMESPACE: KVNamespace;
				YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
			};+++
		}
	}
}

export {};

Testing Locally

Cloudflare Workers specific values in the platform property are emulated during dev and preview modes. Local bindings are created based on your Wrangler configuration file and are used to populate platform.env during development and preview. Use the adapter config platformProxy option to change your preferences for the bindings.

For testing the build, you should use Wrangler version 4. Once you have built your site, run wrangler dev.

Troubleshooting

Node.js compatibility

If you would like to enable Node.js compatibility, you can add the nodejs_compat compatibility flag to your Wrangler configuration file:

/// file: wrangler.jsonc
{
	"compatibility_flags": ["nodejs_compat"]
}

Worker size limits

When deploying your application, the server generated by SvelteKit is bundled into a single file. Wrangler will fail to publish your worker if it exceeds the size limits after minification. You're unlikely to hit this limit usually, but some large libraries can cause this to happen. In that case, you can try to reduce the size of your worker by only importing such libraries on the client side. See the FAQ for more information.

Accessing the file system

You can't use fs in Cloudflare Workers — you must prerender the routes in question.