Annexes

Foire aux questions

Autres ressourcespermalink

Merci de consulter la FAQ de Svelte ainsi que la FAQ de vite-plugin-svelte (en anglais) pour vos questions relatives à ces librairies.

À quoi sert SvelteKit ?permalink

SvelteKit peut être utilisé pour créer la plupart des applications. Il fournit clé en main plusieurs fonctionnalités dont :

Du contenu de page dynamique grâce aux fonctions load et aux routes d'API.
Du contenu dynamique compatible avec un référencement de qualité grâce au rendu côté serveur (SSR).
Des pages interactives améliorables progressivement permettant une bonne expérience utilisateur grâce au SSR et aux actions de formulaire.
Des pages statiques grâce au prérendu.

SvelteKit peut aussi être déployé sur une grande variété d'architectures d'hébergements grâce aux adaptateurs. Dans les situations où le rendu côté serveur est utilisé (ou si de la logique côté serveur est ajouté sans prérendu), ces fonctionnalités seront adaptées à la plateforme ciblée. Voici quelques exemples :

Applications web dynamiques auto-hébergées sur un serveur Node.js.
Applications web serverless avec des fonctions de chargement sur le serveur et des API déployées en tant que fonctions distantes. Voir la section Déploiements sans configuration pour plus d'infos sur les options de déploiement disponibles.
Sites statiques prérendus tels qu'un blog ou un site multi-pages hébergées sur un CDN ou un hébergeur de contenu statique. Les sites générées de manière statique sont déployés sans aucun serveur.
Applications de type SPA avec un routing et des rendus côté client pour des contenus dynamiques se basant sur des APIs. Les SPAs sont déployées sans aucun serveur et ne sont donc pas rendues sur un serveur. Cette option est souvent choisie lorsque l'on compile SvelteKit avec une application écrite en PHP, .NET, Java, C, Golang, Rust, etc.
Un mélange de tout ce qui précède ; certaines routes peuvent être statiques, et d'autres routes peuvent utiliser des fonctions de serveur pour récupérer des informations dynamiques. Ceci peut être configuré grâce aux options de page qui incluent la possibilité de désactiver le SSR.

Si vous souhaitez permettre le SSR, un serveur JS – basé par exemple sur Node.js, Deno, des fonctions serverless ou edge – est requis.

Il est également possible d'écrire des adaptateurs personnalisés ou de se servir des adapatateurs de la communauté pour déployer SvelteKit sur plus de plateformes tels que des environnements serveur spécialisés, des extensions de navigateur ou des applications natives. Voir la section Intégrations pour plus d'exemples.

Comment utiliser le HMR avec SvelteKit ?permalink

SvelteKit propose le HMR activé par défaut grâce à svelte-hmr. Si vous avez vu la présentation de Rich au Svelte Summit 2020, vous avez peut-être constaté une version du HMR qui semble plus puissante. Cette démo avait activé l'option preserveLocalState de svelte-hmr. Cette option est maintenant désactivée par défaut car elle peut amener à des comportements inattendus. Mais ne vous inquiétez pas, vous bénéficiez tout de même du HMR avec SvelteKit ! Si vous souhaitez préserver l'état local vous pouvez utiliser les directives @hmr:keep ou @hmr:keep-all comme documenté sur la page de svelte-hmr (en anglais).

Comment inclure les détails de mon package.json dans mon application ?permalink

Vous ne pouvez pas importer directement des fichiers JSON, puisque SvelteKit attend que le fichier svelte.config.js soit un module ECMAScript. Si vous souhaitez inclure le numéro de version de votre application ou toute autre information de votre fichier package.json dans votre application, vous pouvez charger le JSON de cette manière :

svelte.config.js

ts
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';

const path = fileURLToPath(new URL('package.json', import.meta.url));
const pkg = JSON.parse(readFileSync(path, 'utf8'));

Comment corriger l'erreur qui se produit lorsque j'essaie d'inclure un paquet ?permalink

La plupart des problèmes liés à l'ajout de librairies sont dus à un mauvais packaging. Vous pouvez vérifier que le paquet d'une librairie est compatible avec Node.js sur le site publint.

Voici quelques choses à savoir lorsque vous vérifiez si une librairie est correctement packagée :

exports est prioritaire sur les autres champs de point d'entrée tels que main et module. Ajouter un champ exports peut ne pas être rétro-compatible car il empêche les imports profonds.
les fichiers ESM doivent avoir une extension .mjs à moins que "type": "module" ne soit défini, et dans ce cas les fichiers CommonJS doivent avoir une extension .cjs.
main doit être défini si exports ne l'est pas. Il doit pointer vers un fichier CommonJS ou ESM et satisfaire le point précédent. Si un champ module est défini, il doit pointer vers un fichier ESM.
les composants Svelte doivent être distribués en tant que fichiers .svelte non compilés, et tout fichier JS du paquet doit être écrit en tant que module ESM uniquement. Les langages classiques de scripts et de style, comme TypeScript et SCSS, doivent être préprocessés en tant que JS et CSS vanille respectivement. Nous recommandons l'utilisation de svelte-package pour packager une librairie Svelte, qui s'occupera de cela pour vous.

Les librairies fonctionnent mieux dans le navigateur avec Vite lorsqu'elle sont distribuées en version ESM, surtout si ce sont de dépendances d'une librairie de composants Svelte. Vous pouvez suggérer aux auteurs et autrices de librairies qu'elles fournissent une version ESM. Néanmoins, les dépendances CommonJS (CJS) devraient également fonctionner, puisque par défaut, vite-plugin-svelte va demander à Vite de les pré-compiler en utilisant esbuild pour les convertir en ESM.

Si vous rencontrez toujours des problèmes, nous vous recommandons de faire un tour dans les issues de Vite et les issues de la librairie en question. Parfois les problèmes peuvent être contournés en jouant avec les options optimizeDeps ou ssr, même si nous recommandons ceci comme une solution court-terme – corriger la librairie en question est une bien meilleure solution.

Comment utiliser l'API de transition de vue avec SvelteKit ?permalink

Bien que SvelteKit n'ait pas d'intégration spécifique aux transitions de vue, vous pouvez appeler document.startViewTransition dans onNavigate pour déclencher une transition de vue à chaque navigation côté client.

ts
import { onNavigate } from '$app/navigation';

onNavigate((navigation) => {
Property 'startViewTransition' does not exist on type 'Document'.2339Property 'startViewTransition' does not exist on type 'Document'.	if (!document.startViewTransition) return;

	return new Promise((resolve) => {
		document.startViewTransition(async () => {
			resolve();
			await navigation.complete;
		});
	});
});

Pour plus d'informations, voir "Unlocking view transitions" (en anglais) sur le blog de Svelte.

Comment utiliser X avec SvelteKit ?permalink

Assurez-vous d'avoir lu la section sur les intégrations. Si vous avez toujours des problèmes, voici quelques solutions à des problèmes classiques.

Comment mettre en place une base de données ?permalink

Mettez le code qui requête votre base de données dans une route de serveur – ne requêtez pas la base de données dans des fichiers .svelte. Vous pouvez créer un fichier db.js ou similaire qui met en place une connection immédiatement et rend le client accessible dans votre application en tant que singleton. Vous pouvez exécuter tout code de mise en place dans le fichier hooks.js et importer vos utilitaires de base de données dans tout fichier de endpoint qui les nécessite.

Comment utiliser une librairie réservée au client qui dépend de document ou de window ?permalink

Si vous avez besoin d'accéder aux variables document ou window, ou si vous avez besoin d'exécuter du code uniquement côté client, vous pouvez le faire au sein d'un bloc qui vérifie si browser vaut true :

ts
import { browser } from '$app/environment';

if (browser) {
	// code client uniquement
}

Vous pouvez aussi exécuter du code dans onMount si vous souhaitez qu'il soit joué après le premier rendu du composant dans le DOM :

ts
import { onMount } from 'svelte';

onMount(async () => {
	const { method } = await import('une-librairie-uniquement-client');
	method('bonjour tout le monde');
});

Si la librairie que vous souhaitez utiliser n'a pas d'effet de bord, vous pouvez aussi l'importer de manière statique, elle sera alors retirée lors de la compilation (grâce au tree shaking) du code serveur compilé dans lequel onMount est automatiquement remplacé par une fonction inerte :

ts
import { onMount } from 'svelte';
import { method } from 'une-librairie-uniquement-client';

onMount(() => {
	method('bonjour tout le monde');
});

Enfin, vous pouvez aussi envisager l'utilisation d'un bloc {#await} :

index.svelte

<script>
	import { browser } from '$app/environment';

	const ComponentConstructor = browser ?
		import('une-librairie-uniquement-client').then((module) => module.Component) :
		new Promise(() => {});
</script>

{#await ComponentConstructor}
	<p>Chargement...</p>
{:then component}
	<svelte:component this={component} />
{:catch error}
	<p>Quelque chose s'est mal passé : {error.message}</p>
{/await}

index.svelte

<script lang="ts">
	import { browser } from '$app/environment';
	
	const ComponentConstructor = browser
		? import('une-librairie-uniquement-client').then((module) => module.Component)
		: new Promise(() => {});
</script>

{#await ComponentConstructor}
	<p>Chargement...</p>
{:then component}
	<svelte:component this={component} />
{:catch error}
	<p>Quelque chose s'est mal passé : {error.message}</p>
{/await}

Comment utiliser un autre serveur d'API ?permalink

Vous pouvez utiliser event.fetch pour requêter des données depuis un serveur d'API externe, mais ayez conscience que vous aurez besoin de gérer les CORS, ce qui amène certaines complications telles que faire des requêtes de pré-vérification, impliquant ainsi une plus grande latence. Requêter un domaine séparé peut aussi augmenter la latence à cause d'une vérification DNS additionnelle, de la mise en place du TLS, etc. Si vous souhaitez utiliser cette méthode, vous pourriez avoir besoin de handleFetch.

Une autre approche est de définir un proxy pour contourner les problèmes liés aux CORS. En production, vous devrez alors réécrire un chemin tel que /api vers le serveur d'API ; en développement local, utilisez l'option server.proxy de Vite.

La manière de mettre en place les réécritures en production va dépendre de votre plateforme de déploiement. Si les réécritures ne sont pas une option, vous pourriez alors ajouter une route d'API :

src/routes/api/[...path]/+server.js

ts
/** @type {import('./$types').RequestHandler} */
export function GET({ params, url }) {
	return fetch(`https://my-api-server.com/${params.path + url.search}`);
}

src/routes/api/[...path]/+server.ts

ts
import type { RequestHandler } from './$types';

export const GET: RequestHandler = ({ params, url }) => {
	return fetch(`https://my-api-server.com/${params.path + url.search}`);
};

(Notez que vous pourriez aussi avoir besoin de relayer les requêtes POST/PATCH etc., ainsi que les request.headers, en fonction de vos besoins.)

Comment utiliser des middlewares ?permalink

L'adaptateur adapter-node fournit un middleware que vous pouvez utiliser avec votre propre serveur en production. En mode développement, vous pouvez ajouter des middlewares à Vite en utilisant un plugin Vite. Par exemple :

ts
import { sveltekit } from '@sveltejs/kit/vite';

/** @type {import('vite').Plugin} */
const myPlugin = {
	name: 'log-request-middleware',
	configureServer(server) {
		server.middlewares.use((req, res, next) => {
			console.log(`Requête reçue ${req.url}`);
			next();
		});
	}
};

/** @type {import('vite').UserConfig} */
const config = {
	plugins: [myPlugin, sveltekit()]
};

export default config;

Voir la documentation Vite sur configureServer (en anglais) pour plus de détails, notamment sur gestion de l'ordre.

Est-ce compatible avec Yarn 2 ?permalink

Plus ou moins. La fonctionnalité Plug'n'Play, ou "PNP", ne fonctionnera pas (elle n'est pas compatible avec l'algorithme de résolution de modules de Node, et ne fonctionne pas encore avec les modules JavaScript natifs, ce que SvelteKit – comme un nombre grandissant de paquets – utilise). Vous pouvez utiliser nodeLinker: 'node-modules' dans votre fichier .yarnrc.yml pour désactiver le PNP, mais il est probablement plus facile de plutôt utiliser NPM ou pnpm, qui sont tout aussi efficaces et rapides, la complexité de la compatibilité en moins.

Est-ce compatible avec Yarn 3 ?permalink

La compatibilité ESM avec la dernière version de Yarn (version 3) est actuellement considérée comme expérimentale.

Ce qui suit semble fonctionner, même si votre cas peut être un peu différent.

Créez d'abord une nouvelle application :

yarn create svelte myapp
cd myapp

Et activez Yarn Berry :

yarn set version berry
yarn install

Le cache global de Yarn 3permalink

Une des fonctionnalités les plus intéressantes de Yarn Berry est la possibilité d'avoir un seul cache global pour tous les paquets, plutôt que d'avoir plusieurs copies pour chaque projet sur le disque. Cependant, définir enableGlobalCache à true fait échouer la compilation, il est donc recommandé d'ajouter la chose suivante dans votre fichier .yarnrc.yml :

yaml
nodeLinker: node-modules

Cette option implique que vos paquets seront téléchargés dans un dossier node_modules local, mais évite le problème décrit ci-dessus, et c'est actuellement votre meilleure chance d'utiliser Yarn 3.

précédent Types

suivant Intégrations