Cloudflare Pages

To deploy to Cloudflare Workers or Cloudflare Pages, 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 event.platform 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 and Cloudflare Pages
• 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

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

import import adapteradapter from '@sveltejs/adapter-cloudflare';

export default {
	
kit: {
    adapter: any;
}kit: {
		adapter: anyadapter: import adapteradapter({
			// See below for an explanation of these options
			config: undefinedconfig: var undefinedundefined,
			
platformProxy: {
    configPath: undefined;
    environment: undefined;
    persist: undefined;
}platformProxy: {
				configPath: undefinedconfigPath: var undefinedundefined,
				environment: undefinedenvironment: var undefinedundefined,
				persist: undefinedpersist: var undefinedundefined
			},
			fallback: stringfallback: 'plaintext',
			
routes: {
    include: string[];
    exclude: string[];
}routes: {
				include: string[]include: ['/*'],
				exclude: string[]exclude: ['<all>']
			}
		})
	}
};

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.

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.

For Cloudflare Pages, this page will only be served when a request that matches an entry in routes.exclude fails to match an asset.

Most of the time plaintext is sufficient, but if you are using routes.exclude to manually exclude a set of prerendered pages without exceeding the 100 route limit, you may wish to use spa instead to avoid showing an unstyled 404 page to users.

See Cloudflare Pages’ Not Found behaviour for more info.

routes

Only for Cloudflare Pages. Allows you to customise the _routes.json file generated by adapter-cloudflare.

• include defines routes that will invoke a function, and defaults to ['/*']
• exclude defines routes that will not invoke a function — this is a faster and cheaper way to serve your app’s static assets. This array can include the following special values:
  • <build> contains your app’s build artifacts (the files generated by Vite)
  • <files> contains the contents of your static directory
  • <prerendered> contains a list of prerendered pages
  • <all> (the default) contains all of the above

You can have up to 100 include and exclude rules combined. Generally you can omit the routes options, but if (for example) your <prerendered> paths exceed that limit, you may find it helpful to manually create an exclude list that includes '/articles/*' instead of the auto-generated ['/articles/foo', '/articles/bar', '/articles/baz', ...].

Cloudflare Workers

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:

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

Deployment

Please follow the framework guide for Cloudflare Workers to begin.

Cloudflare Pages

Deployment

Please follow the Get Started Guide for Cloudflare Pages to begin.

If you’re using the Git integration, your build settings should look like this:

• Framework preset – SvelteKit
• Build command – npm run build or vite build
• Build output directory – .svelte-kit/cloudflare

Further reading

You may wish to refer to Cloudflare’s documentation for deploying a SvelteKit site on Cloudflare Pages.

Notes

Functions contained in the /functions directory at the project’s root will not be included in the deployment. Instead, functions should be implemented as server endpoints in your SvelteKit app, which is compiled to a single _worker.js file.

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 context, caches, and cf, meaning that you can access it in hooks and endpoints:

export async function 
function POST({ request, platform }: {
    request: any;
    platform: any;
}): Promise<void>POST({ request, platform }) {

	const const x: anyx = platform: anyplatform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}

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:

import { interface KVNamespace<Key extends string = string>KVNamespace, interface DurableObjectNamespace<T extends Rpc.DurableObjectBranded | undefined = undefined>DurableObjectNamespace } from '@cloudflare/workers-types';

declare global {
	namespace App {
		interface interface App.Platform
If your adapter provides platform-specific context via event.platform, you can specify it here.
Platform {
			
App.Platform.env?: {
    YOUR_KV_NAMESPACE: KVNamespace;
    YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
} | undefinedenv?: {
				type YOUR_KV_NAMESPACE: KVNamespace<string>YOUR_KV_NAMESPACE: interface KVNamespace<Key extends string = string>KVNamespace;
				type YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace<undefined>YOUR_DURABLE_OBJECT_NAMESPACE: interface DurableObjectNamespace<T extends Rpc.DurableObjectBranded | undefined = undefined>DurableObjectNamespace;
			};
		}
	}
}

export {};

Testing locally

Cloudflare 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 .svelte-kit/cloudflare if you’re testing for Cloudflare Workers or wrangler pages dev .svelte-kit/cloudflare for Cloudflare Pages.

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:

{
	"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.

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 all site configuration settings from your Wrangler configuration file, then add the assets.directory and assets.binding configuration settings:

svelte.config.js

import adapter from '@sveltejs/adapter-cloudflare-workers';
import import adapteradapter from '@sveltejs/adapter-cloudflare';

export default {
	
kit: {
    adapter: any;
}kit: {
		adapter: anyadapter: import adapteradapter()
	}
};

wrangler.toml

site.bucket = ".cloudflare/public"
assets.directory = ".cloudflare/public"
assets.binding = "ASSETS"

wrangler.jsonc

{
	"site": {
		"bucket": ".cloudflare/public"
	},
	"assets": {
		"directory": ".cloudflare/public",
		"binding": "ASSETS"
	}
}