Skip to content

Latest commit

 

History

History
108 lines (76 loc) · 5.38 KB

60-adapter-cloudflare.md

File metadata and controls

108 lines (76 loc) · 5.38 KB
Raw

Cloudflare Pages

To deploy to Cloudflare Pages, use adapter-cloudflare.

This adapter will be installed by default when you use adapter-auto, but adding it to your project is recommended so that event.platform is automatically typed.

Comparisons

  • adapter-cloudflare – supports all SvelteKit features; builds for Cloudflare Pages
  • adapter-cloudflare-workers – supports all SvelteKit features; builds for Cloudflare Workers
  • adapter-static – only produces client-side static assets; compatible with Cloudflare Pages

Unless you have a specific reason to use adapter-cloudflare-workers, it's recommended that you use this adapter instead. Both adapters have equivalent functionality, but Cloudflare Pages offers features like GitHub integration with automatic builds and deploys, preview deployments, instant rollback and so on.

Usage

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

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

export default {
	kit: {
		adapter: adapter({
			// See below for an explanation of these options
			routes: {
				include: ['/*'],
				exclude: ['<all>']
			}
		})
	}
};

Options

The routes option 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', ...].

Deployment

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

When configuring your project settings, you must use the following settings:

  • Framework preset – None
  • Build command – npm run build or vite build
  • Build output directory – .svelte-kit/cloudflare
  • Environment variables
    • NODE_VERSION: 16

You need to add a NODE_VERSION environment variable to both the "production" and "preview" environments. You can add this during project setup or later in the Pages project settings. SvelteKit requires Node 16.14 or later, so you should use 16 as the NODE_VERSION value.

Environment variables

The env object, containing KV/DO namespaces etc, is passed to SvelteKit via the platform property along with context and caches, meaning you can access it in hooks and endpoints:

// @errors: 7031
export async function POST({ request, platform }) {
	const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}

To make these types available to your app, reference them in your src/app.d.ts:

/// file: src/app.d.ts
declare global {
	namespace App {
		interface Platform {
+			env?: {
+				YOUR_KV_NAMESPACE: KVNamespace;
+				YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
+			};
		}
	}
}

export {};

platform.env is only available in the production build. Use wrangler to test it locally

Notes

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

The _headers and _redirects files specific to Cloudflare Pages can be used for static asset responses (like images) by putting them into the /static 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

Accessing the file system

You can't access the file system through methods like fs.readFileSync in Serverless/Edge environments. If you need to access files that way, do that during building the app through prerendering. If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content.