SvelteKitBuild and deploy

Cloudflare

To deploy to Cloudflare Workers, use adapter-cloudflare.

This adapter will be installed by default when you use adapter-auto. If you plan on staying with Cloudflare, you can switch from adapter-auto to using this adapter directly so that cloudflare:workers is emulated during local development, type declarations are automatically applied, and the ability to set Cloudflare-specific options is provided.

Comparisons

adapter-cloudflare – supports all SvelteKit features; builds for Cloudflare Workers Static Assets
adapter-cloudflare-workers – deprecated. Supports all SvelteKit features; builds for Cloudflare Workers Sites
adapter-static – only produces client-side static assets; compatible with Cloudflare Workers Static Assets and Cloudflare Pages

Usage

Run npx sv add sveltekit-adapter="adapter:cloudflare", or install with npm i -D @sveltejs/adapter-cloudflare and add the adapter to your vite.config.js:

vite.config

import adapter(alias) function adapter(options?: AdapterOptions): Adapter
import adapter from '@sveltejs/adapter-cloudflare';
import { sveltekit(alias) function sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference } from '@sveltejs/kit/vite';
import { defineConfig(alias) function defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
 } from 'vite';

export default defineConfig(alias) defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
({
	plugins(property) UserConfig.plugins?: PluginOption[] | undefinedArray of vite plugins to use.
: [
		sveltekit(alias) sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference({
			adapter(property) Config.adapter?: Adapter | undefinedYour adapter is run when executing vite build. It determines how the output is converted for different platforms.
undefined
: adapter(alias) adapter(options?: AdapterOptions): Adapter
import adapter({
				// See below for an explanation of these options
				config(property) AdapterOptions.config?: string | undefinedPath to your Wrangler configuration file.
The adapter manages main and assets.directory; neither must be configured.
assets.binding defaults to ASSETS.
: undefinedvar undefined,
				platformProxy(property) AdapterOptions.platformProxy?: GetPlatformProxyOptions | undefinedConfig object passed to getPlatformProxy
during development.
: {
					configPath(property) configPath?: string | undefinedThe path to the config file to use.
If no path is specified the default behavior is to search from the
current directory up the filesystem for a Wrangler configuration file to use.
Note: this field is optional but if a path is specified it must
      point to a valid file on the filesystem
: undefinedvar undefined,
					environment(property) environment?: string | undefinedThe name of the environment to use
: undefinedvar undefined,
					persist(property) persist?: boolean | {
    path: string;
} | undefinedIndicates if and where to persist the bindings data, if not present or true it defaults to the same location
used by wrangler: .wrangler/state/v3 (so that the same data can be easily used by the caller and wrangler).
If false is specified no data is persisted on the filesystem.
: undefinedvar undefined
				},
				fallback(property) AdapterOptions.fallback?: "plaintext" | "spa" | undefinedWhether to render a plaintext 404.html page or a rendered SPA fallback page
for non-matching asset requests.
For Cloudflare Workers, the default behaviour is to return a null-body
404-status response for non-matching assets requests. However, if the
assets.not_found_handling
Wrangler configuration setting is set to "404-page", this page will be
served if a request fails to match an asset. If assets.not_found_handling
is set to "single-page-application", the adapter will render a SPA fallback
index.html page regardless of the fallback option specified.
'plaintext'
: 'plaintext'
			})
		})
	]
});

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 env local bindings during development. See the getPlatformProxy Wrangler API documentation for a full list of options.

fallback

Whether to render a plaintext 404.html page or a rendered SPA fallback page for non-matching asset requests.

For Cloudflare Workers, the default behaviour is to return a null-body 404-status response for non-matching assets requests. However, if the assets.not_found_handling Wrangler configuration setting is set to "404-page", this page will be served if a request fails to match an asset. If assets.not_found_handling is set to "single-page-application", the adapter will render a SPA fallback index.html page regardless of the fallback option specified.

Basic configuration

When building for Cloudflare Workers, this adapter expects to find a Wrangler configuration file in the project root. It should look something like this:

wrangler

{
	"name": "<any-name-you-want>",
	"compatibility_flags": ["nodejs_als"],
	"compatibility_date": "<YYYY-MM-DD>"
}

The adapter applies the Cloudflare Vite plugin to SvelteKit’s server build. It generates the Worker and static assets in .svelte-kit/cloudflare and the configuration used by wrangler deploy. Do not configure main or assets.directory yourself, or add the Cloudflare Vite plugin separately.

paths.base is supported. paths.assets is not supported because vite preview cannot serve assets from a separate location.

Deployment

You can use the Wrangler CLI to deploy your application by running npx wrangler deploy or use the Cloudflare Git integration to enable automatic builds and deployments on push.

Runtime APIs

The env object contains your project’s bindings, which consist of KV/DO namespaces, etc. It is available on the cloudflare:workers module.

+server

import { env } from 'cloudflare:workers';

/** @type {import('./$types').RequestHandler} */
export async function POST() {
	const x = env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}

import { env } from 'cloudflare:workers';
import type { RequestHandler } from './$types';

export const POST: RequestHandler = async () => {
	const x = env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
};

SvelteKit’s built-in $app/env/* modules should be preferred for environment variables.

To make these types available to your app, install wrangler and run wrangler types.

Testing locally

vite dev runs your application in Node.js, with Cloudflare-specific values emulated by Wrangler’s platform proxy. Local bindings are created based on your Wrangler configuration file and populate env. Use the adapter’s platformProxy option to change the development proxy’s preferences.

Run vite build followed by vite preview to test the built Worker in Cloudflare’s local workerd runtime. Preview uses the generated Wrangler configuration and bindings rather than the development platform proxy. You can also run wrangler dev after building.

Durable Objects and Workflows, which require custom classes to be exported from your worker, are not currently supported.

Headers and redirects

The _headers and _redirects files, specific to Cloudflare, can be used for static asset responses (like images) by putting them into the project root folder.

However, they will have no effect on responses dynamically rendered by SvelteKit, which should return custom headers or redirect responses from server endpoints or with the handle hook.

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:

wrangler

{
	"compatibility_flags": ["nodejs_compat"]
}

Worker size limits

When deploying your application, the generated Worker and server modules together count towards the Worker size limit. 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.

Instead, use the read function from $app/server to access your files. It works by fetching the file from the deployed public assets location.

Alternatively, you can prerender the routes in question.

Migrating from Workers Sites

Cloudflare no longer recommends using Workers Sites and instead recommends using Workers Static Assets. To migrate, replace @sveltejs/adapter-cloudflare-workers with @sveltejs/adapter-cloudflare and remove main and all site configuration settings from your Wrangler configuration file.

vite.config

import adapter(alias) function adapter(options?: AdapterOptions): Adapter
import adapter from '@sveltejs/adapter-cloudflare';
import { sveltekit(alias) function sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference } from '@sveltejs/kit/vite';
import { defineConfig(alias) function defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
 } from 'vite';

export default defineConfig(alias) defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
({
	plugins(property) UserConfig.plugins?: PluginOption[] | undefinedArray of vite plugins to use.
: [
		sveltekit(alias) sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference({
			adapter(property) Config.adapter?: Adapter | undefinedYour adapter is run when executing vite build. It determines how the output is converted for different platforms.
undefined
: adapter(alias) adapter(options?: AdapterOptions): Adapter
import adapter()
		})
	]
});

wrangler.toml

wrangler

site.bucket = ".cloudflare/public"

wrangler.jsonc

wrangler

{
	"site": {
		"bucket": ".cloudflare/public"
	}
}

Migrating from Cloudflare Pages

adapter-cloudflare no longer supports Cloudflare Pages and throws a migration error when running in Pages CI (CF_PAGES) or when pages_build_output_dir is configured. See Cloudflare’s Workers and Pages compatibility matrix for a comparison of supported features. To migrate to Cloudflare Workers:

Remove pages_build_output_dir from your Wrangler configuration.
Remove the adapter’s routes option and any _routes.json files. Workers Static Assets handles asset routing without them; see Cloudflare’s routing documentation.
Replace wrangler pages dev with vite preview, and replace wrangler pages deploy with wrangler deploy. For automatic deployments, use Workers Builds instead of the Pages Git integration.

You can keep using _headers and _redirects files in the project root. If you only need a static site on Cloudflare Pages, use adapter-static instead.

Edit this page on GitHub llms.txt

previous next

Single-page apps Cloudflare Workers