cachesdev/svelte-deep-knowledge

Connaissance approfondie de Svelte

Utilisez ceci comme un index des lacunes de connaissances probables. Vérifiez les API pertinentes auprès du MCP officiel de Svelte pendant la planification et l'implémentation.

Vérifié le 2026-11-01 pour Svelte 5.57.3, SvelteKit 3.1.1 et SvelteKit 2.70.3.

Commencez par les versions installées

1. Inspectez les versions des paquets et la configuration Vite. Faites correspondre les conseils à la version majeure de Kit installée et aux indicateurs expérimentaux activés.
2. Appelez list-sections du MCP Svelte, puis récupérez les sections pertinentes avec get-documentation. Le MCP et svelte.dev servent la documentation de Kit 3. Pour un projet Kit 2, lisez la page correspondante de la branche version-2 de sveltejs/kit sous documentation/docs.
3. Pour les projets Kit 3 et les migrations Kit 2 → 3, lisez la référence Kit 3. Pour les projets Kit 2, lisez la référence Kit 2.
4. Exécutez svelte-autofixer sur les composants/modules Svelte nouveaux ou modifiés et résolvez les résultats applicables. Utilisez les vérifications du projet pour l'intégration et les types.

Pour des exemples de nouvelles API Svelte, de rendu asynchrone, d'attaches et d'outillage du compilateur, lisez la référence Svelte.

Fonctions distantes, frontières et await

Pour les nouvelles applications SvelteKit qui adoptent l'async expérimental, préférez les fonctions distantes avec await direct pour les données des composants et des frontières granulaires pour l'interface utilisateur de chargement/erreur. Choisissez le placement de svelte:boundary en fonction de ce qui doit être rendu sur le serveur.

• Activez experimental.remoteFunctions et compilerOptions.experimental.async ensemble. La configuration officielle des fonctions distantes nécessite les deux indicateurs.
• Les routes load, les actions de formulaire et les routes +server restent prises en charge, mais ne sont pas encouragées. Suivez l'architecture existante, sauf si la tâche inclut une migration.
• Les API de requête .loading, .error et .current restent prises en charge. Le await direct est le mécanisme préféré.
• Utilisez await query(args) dans les contextes de rendu et impératifs.
• {#await} reste pris en charge, bien que non encouragé, et a son propre comportement d'état de promesse. Utilisez le await direct et les frontières pour le rendu asynchrone coordonné ; conservez {#await} lorsque son comportement correspond à la tâche.

Vérifiez avec les sections MCP kit/remote-functions, svelte/await-expressions et svelte/svelte-boundary.

Comportement du rendu asynchrone

• Le await au niveau du composant est arrivé dans Svelte 5.36 ; le SSR asynchrone est arrivé dans 5.39. Await est pris en charge dans le script de niveau supérieur, $derived et le balisage.
• Svelte coordonne les mises à jour de l'interface utilisateur dépendantes pendant la résolution du travail asynchrone. Les expressions await de modèle indépendantes s'exécutent simultanément. Les awaits séquentiels dans les scripts créent encore des cascades ; lancez le travail indépendant avant d'attendre ses résultats.
• Le fragment pending d'une frontière apparaît lors de la création initiale. Utilisez $effect.pending() pour le travail ultérieur dans cette frontière ; son compte exclut les frontières enfants.
• Pendant le SSR, une frontière avec pending rend l'espace réservé et ignore son contenu. Les expressions await en dehors de ces frontières se résolvent avant que await render(...) ne se termine. Placez le contenu nécessaire dans le HTML initial en conséquence. Cette API ne fournit pas encore de SSR en streaming.
• $state.eager(value), ajouté dans 5.41, expose un retour immédiat pendant que les mises à jour coordonnées attendent. Utilisez-le pour les retours utilisateur tels qu'un indicateur de navigation actif.
• tick() attend les changements d'état en attente ; settled(), ajouté dans 5.36, attend également le travail asynchrone provoqué par ceux-ci et les mises à jour DOM résultantes.

Frontières d'erreur

• <svelte:boundary> prend en charge failed(error, reset) et onerror(error, reset) pour les échecs de rendu/effet. Gérez les erreurs asynchrones détachées et les gestionnaires d'événements sur leurs sites d'appel.
• Les fragments failed interceptent également les erreurs pendant le SSR, depuis Svelte 5.53. Dans SvelteKit, l'erreur passe d'abord par handleError, donc le fragment reçoit l'App.Error nettoyée. onerror s'exécute lorsque la frontière défaillante s'hydrate.
• Kit 3 envoie les erreurs de rendu via handleError au +error.svelte le plus proche, qui agit comme une frontière. Un handleError client asynchrone nécessite compilerOptions.experimental.async. Kit 2.54+ nécessite experimental.handleRenderingErrors pour la même intégration.
• L'ancienne note de la documentation de la frontière « depuis 5.51 » entre en conflit avec le journal des modifications publié. Utilisez 5.53 comme version d'introduction et vérifiez les correctifs actuels lors du diagnostic des problèmes SSR/hydratation.

Fonctionnalités du modèle

Balises de déclaration, Svelte 5.56+

• Préférez {let ...} et {const ...} pour les variables locales au balisage. {@const} est documenté comme hérité et reste disponible pour les projets plus anciens.
• Les déclarations simples initialisent les valeurs. Utilisez des runes explicites pour la réactivité : {let count = $state(0)} et {const doubled = $derived(count * 2)}.
• La migration de {@const area = width * height} réactif nécessite {const area = $derived(width * height)}. Un simple {const area = width * height} n'est pas réactif.
• Les déclarations utilisent la portée lexicale dans leur élément/bloc, peuvent masquer les variables externes et doivent précéder l'utilisation. Plusieurs déclarateurs sont pris en charge.

Attaches

• Préférez {@attach ...} pour les nouvelles intégrations d'éléments sur Svelte 5.29+. Renvoyez le nettoyage de l'attache.
• Les attaches suivent les lectures réactives et se réexécutent lorsque les dépendances changent. Les valeurs fausses les désactivent. Évitez de répéter une configuration coûteuse en lisant les options changeantes via un getter dans un effet enfant.
• Les wrappers de composants doivent transmettre les propriétés d'attache à l'élément prévu. createAttachmentKey() prend en charge les attaches dans les objets de spread.
• fromAction(action, () => argument) préserve le comportement d'une action existante. Son deuxième argument est un getter. Cette aide est arrivée dans 5.32, après les attaches elles-mêmes.

Classes, liaisons et HTML

• class accepte les tableaux et objets imbriqués depuis 5.16. ClassValue de svelte/elements est disponible depuis 5.19 pour les propriétés de wrapper.
• Les liaisons de fonction utilisent bind:value={get, set} depuis 5.9. Utilisez null comme getter pour les liaisons en lecture seule.
• Les entrées numériques peuvent produire undefined lorsqu'elles sont vides ou invalides. L'état de la case à cocher peut utiliser bind:checked et bind:indeterminate ; les groupes de boutons radio utilisent bind:group.
• Les entrées prennent en charge defaultValue/defaultChecked depuis 5.6. Les sélections prennent en charge defaultValue depuis 5.57, y compris le comportement de réinitialisation de formulaire. Vérifiez la précédence de la liaison lors de la fourniture de valeurs par défaut.
• Les sélections natives personnalisables sont prises en charge depuis 5.47. Vérifiez la prise en charge du navigateur et le modèle documenté <selectedcontent> avant de remplacer un widget de sélection personnalisé.
• Les commentaires de style JavaScript entre les attributs sont valides depuis 5.53 : <div /* explication */ class="card">.
• {@html} accepte TrustedHTML depuis 5.52. La prise en charge des Trusted Types ne nettoie pas les entrées arbitraires ; utilisez une source de confiance ou une politique de nettoyage.

Blocs each et snippets

• {#each items as { id, name }} déstructure les éléments. L'itération de plage peut utiliser {#each { length: 8 }, index}.
• Préférez les clés d'élément stables pour les listes dont l'identité est importante. Lors de la modification d'un élément, liez sa propriété via l'objet élément afin que les mutations atteignent la source.
• Les snippets sont déclarés dans le balisage et rendus avec {@render snippet(...)}. Les snippets de niveau supérieur peuvent être exportés depuis <script module> depuis 5.5 s'ils ne capturent pas l'état de l'instance.
• Les snippets prennent en charge les génériques depuis 5.30. Les génériques de composants utilisent <script lang="ts" generics="T">.
• En mode runes, les variables de composant sont rendues dynamiquement sous la forme <Component />. Les composants récursifs peuvent s'importer eux-mêmes.

Runes et état partagé

État et propriétés

• $state.raw suit la réaffectation sans proxy profond. Utilisez-le pour les grandes valeurs remplacées dans leur ensemble. $state.snapshot extrait des données simples et respecte toJSON().
• Les instances de classe ne sont pas soumises à un proxy profond. Utilisez les champs $state, ou leur première affectation dans le constructeur depuis 5.31. Les champs réactifs deviennent des accesseurs non énumérables ; conservez this lors du passage de méthodes comme rappels.
• Passer une valeur réactive à une fonction transmet sa valeur actuelle. Passez un getter lorsque la fonction a besoin de valeurs futures. La déstructuration d'un proxy lit également les valeurs actuelles.
• Utilisez .svelte.js/.svelte.ts pour la logique de rune partagée. Exportez un objet d'état stable ou des accesseurs lorsque les consommateurs ont besoin d'un état changeant ; l'exportation directe de l'état de rune réaffecté est restreinte.
• Limitez l'état spécifique à l'utilisateur via le contexte du composant pendant le SSR. L'état partagé du module peut fuiter entre les requêtes.
• $props.id(), ajouté dans 5.20, donne un ID d'instance de composant qui correspond entre le SSR et l'hydratation.
• $bindable() déclare une propriété pouvant être liée. Les propriétés peuvent être réaffectées localement ; la mutation d'un proxy non liable d'un parent génère des avertissements de propriété. Les valeurs de repli ne sont pas automatiquement proxifiées.
• Conservez le type non initialisé réel de $state<T>(), qui inclut undefined, ou fournissez une valeur initiale valide. Utilisez le rétrécissement aux sites d'accès.

Dérivés et effets

• Utilisez $derived(expression) ou $derived.by(fn) pour les valeurs calculées. Les dérivés déclarés avec let peuvent être réaffectés pour l'interface utilisateur optimiste depuis 5.25 ; les changements de dépendance les recalculent.
• Les valeurs $derived déstructurées restent réactives. Les objets retournés ne sont pas automatiquement des proxys profonds. L'égalité référentielle peut ignorer le travail en aval.
• Les effets suivent les lectures synchrones de leur dernière exécution. Les lectures dans un rappel asynchrone ordinaire après await ne sont pas automatiquement des dépendances.
• $effect s'exécute dans le navigateur. Renvoyez le nettoyage de manière synchrone ; réservez les effets pour la synchronisation externe et placez le travail déclenché par l'utilisateur dans les gestionnaires.
• $effect.tracking() détecte un contexte de suivi. $effect.root() crée une portée gérée manuellement et renvoie un dispositif de suppression.
• getAbortSignal(), ajouté dans 5.35, doit s'exécuter dans un effet ou un dérivé. Son signal abandonne lors de la réexécution ou de la destruction. Utilisez-le pour le travail de récupération appartenant à ce calcul réactif.
• untrack(fn) exclut les lectures du suivi des dépendances.
• $inspect(...).with(fn) reçoit "init"/"update" suivi de valeurs. $inspect.trace(label?), ajouté dans 5.14, doit être la première instruction dans la fonction tracée.
• $host() est destiné aux éléments personnalisés et renvoie leur élément DOM hôte.

Modules d'exécution

• createContext<T>() fournit un contexte typé depuis 5.40. Depuis 5.57, il renvoie [get, set, has] ; has() vérifie la disponibilité avant get(), qui lève une exception lorsqu'il n'est pas défini. La recherche de contexte inclut le composant actuel et les ancêtres. Appelez les accesseurs de contexte lors de l'initialisation et définissez le contexte avant le premier await dans le script. Depuis 5.57.1, une setContext ultérieure lève set_context_after_init pendant le SSR.
• svelte/reactivity fournit SvelteMap, SvelteSet, SvelteDate, SvelteURL et SvelteURLSearchParams. Les entrées Map/Set ne sont pas rendues profondément réactives.
• Svelte 5.57 ajoute SvelteMap.getOrInsert(key, value) et getOrInsertComputed(key, key => value). Le rappel calculé s'exécute lorsque la clé est absente, y compris la gestion correcte des entrées undefined existantes.
• MediaQuery et createSubscriber sont arrivés dans 5.7. Utilisez createSubscriber pour connecter des événements externes à des lectures suivies avec une configuration et un nettoyage d'abonnement partagés. MediaQuery accepte un repli SSR ; utilisez CSS lorsqu'il peut exprimer le même comportement.
• svelte/reactivity/window fournit des valeurs .current réactives pour les dimensions, la position de défilement, l'état en ligne, la position de l'écran et le rapport de pixels depuis 5.11. Tenez compte des valeurs de fenêtre indisponibles pendant le SSR.
• on() de svelte/events préserve l'ordre avec les gestionnaires d'événements déclaratifs et renvoie le nettoyage. Utilisez <svelte:window>/<svelte:document> pour les écouteurs globaux déclaratifs.
• flushSync(fn?) vide les mises à jour en attente de manière synchrone. createRawSnippet prend en charge le balisage programmatique avec configuration/nettoyage. getAllContexts() fournit la carte de contexte actuelle pour le montage programmatique ; appelez-le lors de l'initialisation.
• Spring et Tween de svelte/motion remplacent les stores spring()/tweened() obsolètes depuis 5.8. Les deux exposent .target, .current, .set() et .of(fn). Spring.set prend en charge preserveMomentum ; prefersReducedMotion prend en charge le mouvement accessible.
• Depuis 5.55, les exportations de mouvement incluent TweenOptions, SpringOptions, SpringUpdateOptions et Updater.
• hydratable(key, fn), ajouté dans 5.44, sérialise les données pour les réutiliser pendant l'hydratation. Il utilise devalue et prend en charge les promesses imbriquées. Les clés avec espace de noms évitent les collisions. Les fonctions distantes Kit gèrent déjà cette couche.
• Avec CSP, les intégrations SSR personnalisées doivent configurer render avec un nonce par réponse ou des hachages statiques et placer les valeurs correspondantes dans les en-têtes de réponse. Svelte 5.46 a ajouté la prise en charge du rendu CSP ; 5.57 exporte RenderOutput, SyncRenderOutput, Csp et Sha256Source de svelte/server.
• Pour l'outillage, print() convertit un AST Svelte moderne en source depuis 5.45 ; parseCss() est arrivé dans 5.48. Les options du compilateur css, runes et customElement peuvent être des fonctions dépendantes du nom de fichier depuis 5.54. Lisez la référence Svelte avant d'utiliser ces API.

SvelteKit

Les nouvelles applications utilisent Kit 3 (npx sv create). Migrez une application Kit 2 avec npx sv migrate sveltekit-3, puis parcourez les TODOs générés. Les conseils Kit 2 s'appliquent uniquement aux projets qui restent sur 2.x.

Base de référence Kit 3

• Kit 3 nécessite Node 22.17, TypeScript 6, Svelte 5.57.1, Vite 8.0.12 et vite-plugin-svelte 7.
• La configuration se trouve dans sveltekit({...}) à l'intérieur de vite.config.ts, avec les options Kit au niveau supérieur à côté de compilerOptions. Kit 3 ne lit plus svelte.config.js.
• #lib remplace $lib via les importations de sous-chemin de package.json. Écrivez les extensions de fichier, par exemple #lib/server/db.ts.
• Un segment de nom de fichier server, ou tout répertoire server en dehors de src/routes, marque un module réservé au serveur. Un segment de nom de fichier remote, comme dans data.remote.ts ou remote.ts, marque un module distant.
• Déclarez les variables d'environnement dans src/env.ts avec defineEnvVars de @sveltejs/kit/env. Importez les valeurs de $app/env/private et $app/env/public, et browser, building, dev, version de $app/env. Les variables publiques peuvent apparaître dans app.html en tant que %sveltekit.env.NAME%. $env/* et $app/environment sont des alias obsolètes.
• $app/stores est supprimé ; utilisez $app/state. page.url est en lecture seule ; copiez-le avec new URL(page.url). $page.state est accessible en écriture. page.form depuis 5.33 est une propriété réactive dérivée de $page.state.form.
• $app/navigation a des fonctions asynchrones : beforeNavigate, afterNavigate, onNavigate, goto, pushState, replaceState, invalidate, invalidateAll, preloadData, preloadCode. pushState remplace goto pour l'état local sans navigation ; il met à jour l'URL et ajoute une entrée d'historique.
• $app/server exporte read, respond et resolveRoute ; toutes prennent en charge l'importation directe de fichiers. resolveRoute n'accepte plus de chemin de base.
• $app/forms a applyAction, deserialize, enhance. enhance() accepte des fonctions de rappel et peut se passer de paramètres. La prop action mène à un point de terminaison. Les paramètres d'URL sont valides dans l'action.
• error() utilise le deuxième paramètre ; le message n'est plus un paramètre. redirect() utilise le code HTTP. json() accepte des en-têtes.
• Kit 3 nécessite appId dans la configuration pour les identifiants d'élément cohérents pendant le SSR/la construction.
• Le routage : aucun fichier +layout n'est requis dans le répertoire racine. +server.ts remplace routes/+server.ts. page.ts est pour le chargement de données. +layout.server.ts pour les dispositions du serveur.
• Les composants peuvent être importés directement depuis $app/components : Error, ErrorBoundary, UpdatePrompt, ErrorUpdatePrompt. UpdatePrompt est utilisé pour la mise à jour de l'application lors du déploiement.
• Les anciens composants comme Error ont une nouvelle API depuis Kit 3. svelte:component n'est plus nécessaire.
• sveltekit:prefetch n'est plus nécessaire : le préchargement automatique est intégré.
• La propriété type n'est plus nécessaire dans svelte.config.js. Utilisez une configuration selon le type de projet.
• Les polices peuvent être chargées depuis $app/imports en mode développement pour éviter les erreurs de limite de fichiers.
• new URL() n'importe pas de données, il crée un objet URL.
• Le chemin racine par défaut est /app dans Kit 3 ; ajustez paths.base dans svelte.config.js si nécessaire. %sveltekit.base% est une variable de modèle pour app.html. base de $app/paths reflète ce chemin de base.
• strip: true ne supprime pas le contenu importé ; il ne supprime que les espaces blancs inutiles.
• Les paramètres doivent être déclarés dans les fichiers +page.ts ou +server.ts.
• Les middlewares : src/hooks.server.ts pour le serveur et src/hooks.client.ts pour le client. Les valeurs de contexte partagé se trouvent dans src/hooks.ts. Dans Kit 3, les hooks sont implémentés avec sequence.
• Les types de composants Svelte ne sont pas directement pris en charge dans les types de dispositions Kit.
• Pour l'authentification et l'hébergement, voir le guide Auth.js SvelteKit.
• Il n'est pas garanti que les attributs HTML passés avec {@html} soient échappés.
• Utilisez handleError avec le statut 500 pour les erreurs de rendu du serveur ; en développement, elles s'affichent sur la console.
• Pour les sites statiques, utilisez le paramètre layout pour contrôler le rendu.
• resolve n'est plus nécessaire dans le hook handle. Simplifiez l'implémentation avec sequence.
• Le hook handle dans hooks.server.ts ne s'exécute pas pour les actifs statiques.
• L'exportation load avec event.fetch et event.cookies peut manquer de contexte si elle n'est pas exportée correctement.
• lucide-svelte nécessite une configuration spécifique pour les icônes ; vérifiez les options de construction.
• EventSource dans les composants Svelte peut ne pas fonctionner correctement dans tous les environnements ; vérifiez les dépendances.
• svelte-headlessui n'est pas entièrement compatible avec Svelte 5 ; svelte-5-ui-lib n'est pas encore stable.
• sveltekit-superforms 4.x est compatible avec Kit 3 et Svelte 5.
• Vite 6+ fait du bruit pour les dépendances optionnelles manquantes ; pas d'inquiétude.

Schéma de projet dans VSCode

• VSCode peut ne pas reconnaître $app ou d'autres alias de Kit. Utilisez les imports #lib depuis Kit 3.
• Les fichiers *.svelte.js peuvent ne pas être reconnus comme JavaScript ; définissez les extensions de types dans tsconfig.json.
• Utilisez le format define de Vite pour $app/version en développement ; la version statique est définie dans la configuration.
• Svelte 5 utilise un nouvel AST ; l'ancien plugin ESLint peut casser. Le LSP de Svelte analyse les runes dans les fichiers .svelte.js.

{
  "compilerOptions": {
    "types": ["svelte"]
  }
}

Types de composants Svelte et snippets génériques

• Pour les composants avec des accesseurs, utilisez svelte/elements pour les wrappers.
• Les composants avec des props de snippet peuvent être typés selon les types de ces snippets.
• Utilisez Snippet<T> de svelte pour le typage des snippets.
• Les composants peuvent être importés depuis une bibliothèque externe comme $lib/components.
• ComponentProps<...> peut être utilisé pour extraire les types de props d'un composant.
• Les composants sans contenu peuvent être déclarés avec {@render children?.()} dans leur corps.
• Les types d'exportation de Svelte incluent Component, Action, ClassValue ; vérifiez la documentation pour les chemins d'importation exacts.
• Les composants avec contenu enfant utilisent généralement {@render children?.()} avec une prop children: Snippet.
• Les snippets génériques et les props avec as peuvent être utilisés pour typer les wrappers de composants.

Fonctions, API et tenue de route

Fonctions et composants de base

• Les fonctions et composants courants incluent goto, enhance, applyAction.
• goto vous mène à une nouvelle URL ; pushState pousse un état sans navigation.
• enhance augmente un formulaire HTML pour l'envoyer via fetch ; voir la documentation du formulaire.
• applyAction met à jour $page.form avec les données d'action.
• deserialize convertit les réponses du formulaire en objets utilisables.
• beforeNavigate, afterNavigate, onNavigate sont des crochets de navigation ; ils ne peuvent pas être utilisés pendant le SSR.
• invalidate et invalidateAll invalident les données de route.
• preloadData et preloadCode préchargent les données et le code pour les routes spécifiées.
• resolveRoute construit des chemins de route.
• page.url est un objet URL. Les paramètres de page sont dans page.params. Les erreurs de page sont gérées avec des routes d'erreur via handleError.
• Les données de chargement sont gérées par les fonctions load dans les fichiers de route.

Conventions de dénomination des fichiers de route

Les fichiers de route peuvent être nommés avec des segments + comme +page.svelte, +layout.svelte, +server.ts.

• +page.svelte : un composant de page.
• +layout.svelte : un composant de mise en page.
• +error.svelte : un composant d'erreur.
• +page.ts : un fichier de chargement de page.
• +page.server.ts : un fichier de chargement de page côté serveur.
• +layout.server.ts : un fichier de chargement de mise en page côté serveur.
• +server.ts : un point de terminaison API.
• +page.js : un fichier universel (client + serveur) pour le chargement de page.
• Les fichiers dans src/routes doivent être nommés avec + pour être reconnus comme des routes ; d'autres fichiers peuvent être importés mais ne seront pas des routes.
• Les répertoires sans + deviennent des groupes de route optionnels.
• Les paramètres sont placés entre crochets : [param].
• Les paramètres optionnels utilisent [[param]].
• Les paramètres de route sont placés entre parenthèses pour le groupement : (group).
• Les paramètres restants utilisent [...param].

Rendu et données de page

• load est une fonction asynchrone qui renvoie des données pour un composant de page.
• Les données de load sont disponibles via la prop data dans +page.svelte.
• Pour les rendus côté serveur, load s'exécute sur le serveur et les données sont sérialisées et envoyées au client.
• $page.data contient toutes les données de la route actuelle.
• $page.form contient les données de formulaire pour la route actuelle.
• $page.state peut être utilisé pour stocker l'état du formulaire entre les navigations.
• Les pages peuvent avoir des actions de formulaire qui sont gérées avec enhance.
• Les actions de formulaire sont définies dans +page.server.ts avec une exportation nommée actions.

Composants de mise en page et erreurs

• Les mises en page avec +layout.svelte enveloppent les pages enfants.
• Les mises en page peuvent avoir load pour charger des données partagées.
• +error.svelte gère les erreurs de rendu pour une route spécifique.
• Les erreurs de mise en page sont gérées par le +error.svelte parent.
• Une erreur non gérée remonte au +error.svelte racine.

Rendu de cache et contrôle

... [le contenu a été tronqué pour la traduction ; les sections restantes suivraient le même modèle]

Remarque : le contenu original a été tronqué ; les sections restantes seraient traduites de manière cohérente selon le modèle ci-dessus.