SvelteKitCompiler et déployer

Vercel

Pour déployer sur Vercel, utilisez l’adaptateur adapter-vercel.

Cet adaptateur sera installé par défaut lorsque utilisez adapter-auto, mais l’ajouter à votre projet vous permet de préciser des options spécifiques à Vercel.

Usage

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

svelte.config

import function adapter(config?: Config): Adapteradapter from '@sveltejs/adapter-vercel';

export default {
	kit: {
    adapter: Adapter;
}kit: {
		adapter: Adapteradapter: function adapter(config?: Config): Adapteradapter({
			// voir plus bas pour les options pouvant être définies ici
		})
	}
};

Configuration de déploiement

Pour contrôler comment vos routes sont déployées sur Vercel en tant que fonctions, vous pouvez préciser une configuration de déploiement, soit au travers de l’option montrée au-dessus, soit avec export const config au sein des fichiers +server.js, +page(.server).js et +layout(.server).js.

Par exemple, vous pourriez déployer certaines parties de votre application en tant que Edge Functions...

about/+page

/** @type {import('@sveltejs/adapter-vercel').Config} */
export const const config: {
    runtime: string;
}@type{import('@sveltejs/adapter-vercel').Config}config = {
	runtime: stringruntime: 'edge'
};

import type { type Config = (EdgeConfig | ServerlessConfig) & {
    images?: ImagesConfig;
}Config } from '@sveltejs/adapter-vercel';


export const const config: Configconfig: type Config = (EdgeConfig | ServerlessConfig) & {
    images?: ImagesConfig;
}Config = {
	runtime: "edge"runtime: 'edge'
};

... et d’autres en tant que Serverless Functions (notez qu’en précisant une config au sein d’un layout, celle-ci va s’appliquer à toutes les pages enfant de ce layout) :

admin/+layout

/** @type {import('@sveltejs/adapter-vercel').Config} */
export const const config: {
    runtime: string;
}@type{import('@sveltejs/adapter-vercel').Config}config = {
	runtime: stringruntime: 'nodejs22.x'
};

import type { type Config = (EdgeConfig | ServerlessConfig) & {
    images?: ImagesConfig;
}Config } from '@sveltejs/adapter-vercel';


export const const config: Configconfig: type Config = (EdgeConfig | ServerlessConfig) & {
    images?: ImagesConfig;
}Config = {
	ServerlessConfig.runtime?: `nodejs${number}.x` | undefinedWhether to use Edge Functions ('edge') or Serverless Functions ('nodejs18.x', 'nodejs20.x' etc).
@defaultSame as the build environmentruntime: 'nodejs22.x'
};

Les options suivantes s’appliquent à toutes les fonctions :

runtime : 'edge', 'nodejs18.x', 'nodejs20.x' ou 'nodejs22.x'. Par défaut, l’adaptateur va choisir la version de Node 'nodejs<version>.x correspondant à la version sur laquelle votre projet est configuré sur l’interface de Vercel
regions : un tableau de régions du réseau edge (par défaut ["iad1"] pour les fonctions serverless) ou 'all' si runtime vaut edge (sa valeur par défaut). Notez que plusieurs régions de fonctions serverless sont seulement supportées sur les plans Enterprise
split : si true, provoque le déploiement d’une route en tant que fonction individuelle. Si split vaut true au niveau de l’adaptateur, toutes les routes seront déployées en tant que fonctions individuelles

De plus, l’option suivante s’applique aux fonctions edge :

external : un tableau de dépendances que esbuild devrait traiter comme externes lorsqu’il compile des fonctions. Cette option devrait être uniquement utilisée pour exclure des dépendances optionnelles qui ne peuvent pas être exécutées en dehors de Node

Et les options suivantes s’appliquent aux fonctions serverless :

memory : la quantité de mémoire disponible pour la fonction. Vaut par défaut 1024 Mb, et peut être réduite à 128 Mb ou augmentée par tranches de 64Mb jusqu’à 3008 Mb sur les comptes Pro ou Enterprise
maxDuration : durée d’exécution maximum de la fonction. Vaut par défaut 10 secondes pour les comptes Hobby, 15 pour les comptes Pro et 900 pour les comptes Enterprise
isr : configuration de l’ISR (Incremental Static Regeneration), décrite un peu plus bas

Si vos fonctions ont besoin d’accéder à des données dans une région précise, il est recommandé qu’elles soient déployées dans la même région (ou dans une région proche) pour des performances optimales.

Optimisation d’image

Vous pouvez définir une configuration images pour contrôler comment Vercel compile vos images. Voir la documentation sur la configuration des images pour plus de détails. Par exemple, vous pouvez définir la configuration suivante :

svelte.config

import function adapter(config?: Config): Adapteradapter from '@sveltejs/adapter-vercel';

export default {
	kit: {
    adapter: Adapter;
}kit: {
		adapter: Adapteradapter: function adapter(config?: Config): Adapteradapter({
			images?: ImagesConfig | undefinedhttps://vercel.com/docs/build-output-api/v3/configuration#images
images: {
				sizes: number[]sizes: [640, 828, 1200, 1920, 3840],
				formats?: ImageFormat[] | undefinedformats: ['image/avif', 'image/webp'],
				minimumCacheTTL?: number | undefinedminimumCacheTTL: 300,
				domains: string[]domains: ['example-app.vercel.app'],
			}
		})
	}
};

Incremental Static Regeneration

Vercel supporte l’Incremental Static Regeneration (ISR), qui fournit la performance et les avantages de coûts d’un contenu pré-rendu avec la flexibilité d’un contenu dynamiquement rendu.

Utilisez l’ISR uniquement pour les routes sur lesquelles chaque visiteur ou visiteuse devrait voir le même contenu (comme pour le pré-rendu). S’il y a du contenu spécifique à l’utilisateur (comme des cookies de session), celui-ci devrait être géré sur le client avec JavaScript afin de ne pas faire fuiter d’information sensible entre les visites.

Pour ajouter l’ISR à une route, ajoutez la propriété isr à votre objet config :

import { import BYPASS_TOKENBYPASS_TOKEN } from '$env/static/private';

export const const config: {
    isr: {
        expiration: number;
        bypassToken: any;
        allowQuery: string[];
    };
}config = {
	isr: {
    expiration: number;
    bypassToken: any;
    allowQuery: string[];
}isr: {
		expiration: numberexpiration: 60,
		bypassToken: anybypassToken: import BYPASS_TOKENBYPASS_TOKEN,
		allowQuery: string[]allowQuery: ['search']
	}
};

Utiliser l’ISR sur une route avec export const prerender = true n’aura aucun effet, puisque la route est alors pré-rendue au moment de la compilation.

La propriété expiration est requise ; toutes les autres sont optionnelles. Les propriétés sont détaillées ci-dessous.

expiration

Le temps d’expiration (en secondes) avant que l’asset mis en cache soit re-généré en invoquant la Serverless Function. Définit la valeur à false signifie que l’asset ne va jamais expirer. Dans ce cas, vous voudrez probablement définir un token permettant de re-générer l’asset à la demande.

bypassToken

Un token aléatoire pouvant être fourni à l’URL pour contourner la version de l’asset mise en cache, en requêtant l’asset avec un cookie __prerender_bypass=<token>.

Faire une requête GET ou HEAD avec x-prerender-revalidate: <token> va forcer l’asset à être re-validé.

Notez que la chaîne de caractères BYPASS_TOKEN doit être au minimum longue de 32 caractères. Vous pouvez générer une telle chaîne en utilisant la console JavaScript de cette manière :

var crypto: CryptoMDN Reference
crypto.Crypto.randomUUID(): `${string}-${string}-${string}-${string}-${string}`Available only in secure contexts.
MDN Reference
randomUUID();

Définissez cette chaîne de caractères en tant que variable d’environnement sur Vercel en vous identifiant, puis en vous rendant sur votre projet dans la section Settings > Environment Variables. Pour la clé “Key”, renseignez BYPASS_TOKEN et pour la valeur “Value” utilisez la chaîne générée plus haut, puis appuyez sur “Save”.

Pour récupérer cette clé lors du développement, vous pouvez utiliser le CLI de Vercel en lançant la commande vercel env pull localement, de cette manière :

vercel env pull .env.development.local

allowQuery

Une liste de paramètres de requête valides contribuant à la clé de cache. D’autres paramètres (comme les codes de tracking utm) seront ignorés, assurant qu’ils n’amènent pas du contenu à être re-généré sans raison. Par défaut, les paramètres de requête sont ignorés.

Les pages qui sont pré-rendues vont ignorer la configuration ISR.

Variables d’environnement

Vercel rend disponibles un ensemble de variables d’environnement spécifiques au déploiement. Comme toute autre variable d’environnement, celles-ci sont accessibles depuis $env/static/private et $env/dynamic/private (parfois — plus sur le sujet un peu plus tard), et inaccessibles depuis les versions publiques de ces modules. Pour accéder à l’une de ces variables depuis le client :

+layout.server

import { import VERCEL_COMMIT_REFVERCEL_COMMIT_REF } from '$env/static/private';

/** @type {import('./$types').LayoutServerLoad} */
export function function load(): {
    deploymentGitBranch: any;
}@type{import('./$types').LayoutServerLoad}load() {
	return {
		deploymentGitBranch: anydeploymentGitBranch: import VERCEL_COMMIT_REFVERCEL_COMMIT_REF
	};
}

import { import VERCEL_COMMIT_REFVERCEL_COMMIT_REF } from '$env/static/private';
import type { type LayoutServerLoad = (event: Kit.ServerLoadEvent<Record<string, any>, Record<string, any>, string | null>) => MaybePromise<void | Record<string, any>>
type LayoutServerLoad = (event: Kit.ServerLoadEvent<Record<string, any>, Record<string, any>, string | null>) => MaybePromise<void | Record<string, any>>LayoutServerLoad } from './$types';

export const const load: LayoutServerLoadload: type LayoutServerLoad = (event: Kit.ServerLoadEvent<Record<string, any>, Record<string, any>, string | null>) => MaybePromise<void | Record<string, any>>
type LayoutServerLoad = (event: Kit.ServerLoadEvent<Record<string, any>, Record<string, any>, string | null>) => MaybePromise<void | Record<string, any>>LayoutServerLoad = () => {
	return {
		deploymentGitBranch: anydeploymentGitBranch: import VERCEL_COMMIT_REFVERCEL_COMMIT_REF
	};
};

+layout

<script>
	/** @type {import('./$types').LayoutProps} */
	let { data } = $props();
</script>

<p>Cet environnement staging a été déployé depuis {data.deploymentGitBranch}.</p>

<script lang="ts">
	import type { LayoutProps } from './$types';

	let { data }: LayoutProps = $props();
</script>

<p>Cet environnement staging a été déployé depuis {data.deploymentGitBranch}.</p>

Puisque toutes ces variables sont inchangées entre la compilation et l’exécution lorsque vous compilez sur Vercel, nous recommandons d’utiliser $env/static/private — qui va remplacer les variables de manière statique, permettant des optimisations comme l’élimination de code mort — plutôt que d’utiliser $env/dynamic/private.

Protection Skew

Lorsqu’une nouvelle version de votre application est déployée, les assets appartenant à la précédente version peuvent ne plus être accessibles. Si quelqu’un utilise activement votre application lorsque cela se produit, des erreurs peuvent émerger lors des navigations — ce phénomène s’appelle version skew. SvelteKit tente de résoudre ce problème en détectant les erreurs provenant du version skew et en provoquant un rechargement complet de la page pour récupérer la dernière version de l’application, mais ceci va provoquer la perte de tout état du client. (Vous pouvez aussi gérer cette situation pro-activement en observant la valeur du store updated, qui prévient les clients lorsqu’une nouvelle version de l’application a été déployée.)

La protection Skew est une fonctionnalité de Vercel qui dirige les requêtes client vers leur déploiement d’origine. Lorsque quelqu’un visite votre application, un cookie est défini avec l’ID du déploiement, et toute requête future sera redirigée vers ce déploiement aussi longtemps que la protection skew est active. Lorsque la personne va recharger la page, elle récupèrera le déploiement le plus récent. (Le store updated est exempté de ce comportement, et va continuer à prévenir des nouveaux déploiements.) Pour activer cette protection, rendez vous dans la section Advanced des paramètres de votre projet sur l’interface Vercel.

La protection skew basée sur les cookies possède un désavantage : si un ou une utilisatrice a plusieurs versions de votre application ouvertes dans des onglets différents, les requêtes venant de versions plus anciennes seront redirigées vers les versions plus récentes, impliquant qu’elles seront gérées au final par la protection skew intégrée de Sveltekit.

Notes

Fonctions Vercel

Si vous avez des fonctions Vercel contenues dans le dossier api à la racine du projet, toute requête vers /api/* ne sera pas gérées par SvelteKit. Vous devriez plutôt implémenter ces fonctions en tant que routes d’API dans votre application SvelteKit, à moins que vous n’ayez besoin d’utiliser un language autre que JavaScript pour ces routes, auquel cas vous aurez besoin de vous assurer que n’ayez aucune route /api/* dans votre application SvelteKit.

Version de Node

Les projets créés avant une certaine date peuvent utiliser une version de Node par défaut plus ancienne que celle que nécessite SvelteKit. Vous pouvez modifier la version de Node dans les paramètres de votre projet.

Résolution de problèmes

Accéder au système de fichiers

Vous ne pouvez pas utiliser fs dans les déploiements edge.

Vous pouvez vous servir de ce module lors des déploiements serverless, mais il ne fonctionnera probablement pas comme prévu, puisque les fichiers ne sont pas copiés depuis votre projet vers votre déploiement. Utilisez plutôt la fonction read importée depuis $app/server pour accéder à vos fichiers. read ne fonctionne pas au sein des déploiements edge (cela pourra changer dans le futur).

Comme alternative, vous pouvez pré-rendre les routes en question.

Modifier cette page sur Github llms.txt

précédent suivant

Netlify Écrire un adaptateur