Cloudflare

Pour déployer sur les Cloudflare Workers ou les Cloudflare Pages, utilisez l’adaptateur adapter-cloudflare.

Cet adaptateur sera installé par défaut lorsque vous utilisez adapter-auto. Si vous prévoyez de rester sur Cloudflare, vous pouvez directement passer de adapter-auto à cet adaptateur afin que la plateforme event.platform soit émulée lors du développement local, que les déclarations de type soient automatiquement appliquées et que la possibilité de définir des options spécifiques à Cloudflare soit activée.

Comparaisons

• adapter-cloudflare – supporte toutes les fonctionnalités de SvelteKit ; compile pour Cloudflare Workers Static Assets et Cloudflare Pages
• adapter-cloudflare-workers – déprécié. Supporte toutes les fonctionnalités de SvelteKit ; compile pour Cloudflare Workers Site
• adapter-static – ne produit que des assets statique client ; compatible avec Cloudflare Workers Static Assets et Cloudflare Pages

Usage

Installez l’adaptateur avec npm i -D @sveltejs/adapter-cloudflare, puis ajoutez-le à votre fichier svelte.config.js :

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

/** @type {import('@sveltejs/kit').Config} */
const 
const config: {
    kit: {
        adapter: any;
    };
}
@type{import('@sveltejs/kit').Config}config = {
	
kit: {
    adapter: any;
}kit: {
		adapter: anyadapter: import adapteradapter({
			// Voir plus bas pour une explication de ces 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>']
			}
		})
	}
};

export default 
const config: {
    kit: {
        adapter: any;
    };
}
@type{import('@sveltejs/kit').Config}config;

Options

config

Chemin vers votre fichier de configuration Wrangler. Si vous souhaitez utiliser un nom de fichier de configuration Wrangler autre que wranglet.jsonc, wrangler.json, ou wrangler.toml, vous pouvez le préciser avec cette option.

platformProxy

Les préférences pour les liaisons locales émulées platform.env. Voir la documentation d’API de Wrangler qui traite de getPlatformProxy pour plus de détails.

fallback

Si oui ou non afficher une page 404.html en texte pur, ou une page de secours rendue en SPA pour les requêtes ne correspondant à aucun asset.

Pour les Cloudflare Workers, le comportement par défaut est de renvoyer une réponse 404 avec un body vide pour les requêtes ne correspondant à aucun asset. Cependant, si l’option de configuration de Wrangler assets.not_found_handling vaut "404-page", cette page sera servie si une requête échoue à correspondre un asset. Si asset.not_found_handling est défini comme "single-page-application", l’adaptateur va rendre une page de secours index.html en SPA indépendamment de l’option fallback précisée.

Pour les Cloudflare Pages, cette page sera uniquement servie lorsqu’une requête correspondant à une entrée précisée dans routes.exclude échoue à correspondre à un asset.

La plupart du temps plaintext suffit, mais si vous utilisez routes.exclude pour manuellement exclure un ensemble de pages pré-rendues sans dépasser la limite de 100 routes, vous pourriez souhaiter plutôt utiliser spa pour éviter afficher une page 404 sans aucun style à vos utilisateurs et utilisatrices.

Voir la section Comportement Not Found dans la documentation de Cloudflare pour plus d’infos.

routes

Uniquement pour les Cloudflare Pages. Vous permet de personnaliser le fichier _routes.json généré par adapter-cloudflare.

• include définit les routes qui vont invoquer une fonction, et vaure ['/*'] par défaut
• exclude définit les routes qui ne vont pas invoquer une fonction — c’est une façon plus rapide et moins chère de servir les assets statiques de votre application. Ce tableau peut inclure les valeurs spéciales suivantes :
  • <build> contient les artéfacts de compilation de votre application (les fichiers générés par Vite)
  • <files> contient le contenu de votre dossier static
  • <prerendered> contient une liste des pages pré-rendues
  • <all> (par défaut) contient tout ce qui précisé juste au-dessus

Vous pouvez avoir jusqu’à 100 règles include et exclude combinées. Généralement, vous pouvez omettre l’option routes, mais si (par exemple) vos chemins <prerendered> excèdent cette limite, vous pourriez trouver utile de créer manuellement une liste exclude qui inclut '/articles/*' plutôt que la liste auto-générée ['/articles/foo', '/articles/bar', '/articles/baz', ...].

Cloudflare Workers

Configuration de base

Lorsque vous compilez pour les Cloudflare Workers, cet adaptateur s’attend à trouver le fichier de configuration Wrangler à la racine du projet. Il devrait ressembler à quelque chose comme ça :

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

Déploiement

Merci de suivre le guide dédié aux frameworks pour vous lancer avec les Cloudflare Workers.

Cloudflare Pages

Déploiement

Merci de suivre le Guide Get Started pour vous lancer avec les Cloudflare Pages.

Si vous utilisez l’intégration Git vos paramètres de compilation devraient ressembler à ça :

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

Plus de lecture

Vous devriez vous référer à la documentation de Cloudflare pour déployer un site SvelteKit sur les Cloudflare Pages.

Notes

Les fonctions présentes dans le dossier /functions à la racine du projet ne seront pas incluses dans le déploiement. À la place, les fonctions devraient être implémentées en tant que endpoints de serveur dans votre application SvelteKit, qui sont compilées en un seul fichier _workers.js.

APIs de runtime

L’objet env contient les liaisons de votre projet, qui consistent en des namespaces KV/DO, etc. Il est passé à SvelteKit via la propriété platform, de même que ctx, caches, et cf, ce qui signifie que vous pouvez y accéder dans les hooks et les endpoints :

/** @type {import('./$types').RequestHandler} */
export async function POST({ request: Request
The original request object.
request, platform: Readonly<App.Platform> | undefined
Additional data made available through the adapter.
platform }) {
	const const x: DurableObjectId | undefinedx = platform: Readonly<App.Platform> | undefined
Additional data made available through the adapter.
platform?.
env: {
    YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
}env.type YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace<undefined>YOUR_DURABLE_OBJECT_NAMESPACE.DurableObjectNamespace<undefined>.idFromName(name: string): DurableObjectIdidFromName('x');
}

import type { type RequestHandler = (event: RequestEvent<Record<string, any>, string | null>) => MaybePromise<Response>RequestHandler } from './$types';
export const POST: type RequestHandler = (event: RequestEvent<Record<string, any>, string | null>) => MaybePromise<Response>RequestHandler = async ({ request: Request
The original request object.
request, platform: Readonly<App.Platform> | undefined
Additional data made available through the adapter.
platform }) => {
	const const x: DurableObjectId | undefinedx = platform: Readonly<App.Platform> | undefined
Additional data made available through the adapter.
platform?.
env: {
    YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
}env.type YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace<undefined>YOUR_DURABLE_OBJECT_NAMESPACE.DurableObjectNamespace<undefined>.idFromName(name: string): DurableObjectIdidFromName('x');
};

Le module intégré de $env devrait être préféré pour les variables d’environnement.

Pour rendre ces types disponibles dans votre application, installez @cloudflare/workers-types et référencez-les dans votre fichier 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;
}env: {
				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 {};

Tester en local

Les valeurs spécifiques à Cloudflare dans la propriété platform sont émulées lors du développement et de la prévisualisation. Les liaisons locales sont créées en fonction de votre fichier de configuration Wrangler et sont utilisées pour remplir platform.env lors du développement et de la prévisualisation. Utilisez la configuration platformProxy de l’adaptateur pour changer vos préférences de liaison.

Pour tester le projet compilé, vous devriez utiliser la version 4 de Wrangler. Une fois que vous avez compilé votre site, lancez wrangler dev .svelte-kit/cloudflare si vous testez pour les Cloudflare Workers ou wrangler pages dev .svelte-kit/cloudflare si vous testez pour les Cloudflare Pages.

En-têtes et redirections

Les fichiers _headers et _redirects, spécifiques à Cloudflare, peuvent être utilisés pour les réponses d’assets statiques (comme les images) en les plaçant à la racine de votre projet.

Cependant, ils n’auront aucun effet pour les réponses rendues dynamiquement par SvelteKit, qui devraient renvoyer des réponses d’en-tête ou de redirection personnalisées depuis vos endpoints de serveur ou grâce au hook handle.

Résolution de problèmes

Compatibilité avec Node.js

Si vous souhaitez activer la compatibilité avec Node.js, vous pouvez ajouter l’option de compatibilité nodejs_compat à votre fichier de configuration :

{
	"compatibility_flags": ["nodejs_compat"]
}

Limites de taille des workers

Lorsque vous déployez votre application, le serveur généré par SvelteKit est compilé en un seul fichier. Wrangler va échouer à publier votre worker s’il excède les limites de taille après minification. Il est normalement peu probable que vous dépassiez cette limite, mais certaines grosses librairies peuvent vous les faire dépasser. Dans ce cas, vous pouvez essayer de réduire la taille de votre worker en n’important ces librairies que côté client. Voir la FÀQ pour plus d’informations.

Accéder au système de fichiers

Vous ne pouvez pas utiliser fs dans les Cloudflare Workers.

Utilisez plutôt la fonction read importée depuis $app/server pour accéder à vos fichiers. Elle fonctionne en récupérant le fichier depuis l’emplacement déployé des assets publics.

De manière alternative, vous pouvez pré-rendre les routes en question.

Migrer depuis Workers Sites

Cloudflare ne recommande plus d’utiliser les Workers Sites et recommande plutôt d’utiliser les Workers Static Assets. Pour migrer, remplacez @sveltejs/adapter-cloudflare-workers par @sveltejs/adapter-cloudflare et supprimez tous les paramètres de configuration site de votre fichier de configuration Wrangler, puis ajoutez-y les paramètres de configuration assets.directory et assets.bindings :

svelte.config.js

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

/** @type {import('@sveltejs/kit').Config} */
const 
const config: {
    kit: {
        adapter: any;
    };
}
@type{import('@sveltejs/kit').Config}config = {
	
kit: {
    adapter: any;
}kit: {
		adapter: anyadapter: import adapteradapter()
	}
};

export default 
const config: {
    kit: {
        adapter: any;
    };
}
@type{import('@sveltejs/kit').Config}config;

wrangler.toml

site.bucket = ".cloudflare/public"
assets.directory = ".cloudflare/public"
assets.binding = "ASSETS" # Excluez ceci si vous n'avez pas de clé `main` configurée.

wrangler.jsonc

{
	"site": {
		"bucket": ".cloudflare/public"
	},
	"assets": {
		"directory": ".cloudflare/public",
		"binding": "ASSETS" // Excluez ceci si vous n'avez pas de clé `main` configurée.
	}
}