Migrer depuis Sapper

SvelteKit est le successeur de Sapper, et contient plusieurs éléments de son design.

Si vous avez une application Sapper que vous prévoyez de migrer vers SvelteKit, il y a plusieurs modifications que vous aurez besoin de faire. Vous pouvez prendre comme référence quelques exemples lors de votre migration.

package.jsonpermalink

type: "module"permalink

Ajoutez "type": "module" dans votre fichier package.json. Vous pouvez faire ceci séparemment du reste si vous utilisez Sapper 0.29.3 ou plus récent.

dependenciespermalink

Supprimez polka ou express si vous les utilisez, et tout middleware tel que sirv ou compression.

devDependenciespermalink

Supprimez sapper de vos devDependencies et remplacez-le par @sveltejs/kit et tout adaptateur que vous prévoyez d'utiliser (voir section suivante).

scriptspermalink

Tout script qui fait référence à sapper doit être mis à jour :

• sapper build devient vite build avec l'adaptateur Node
• sapper export devient vite build avec l'adaptateur statique
• sapper dev devient vite dev
• node __sapper__/build devient node build

Fichiers de projetpermalink

Le coeur de votre application, dans le dossier src/routes, peut rester à sa place, mais plusieurs fichiers de projet doivent être déplacés ou mis à jour.

Configurationpermalink

Votre fichier webpack.config.js ou rollup.config.js doit être remplacé par un fichier svelte.config.js, comme documenté ici. Les options du pré-processeur Svelte doivent être déplacées dans config.preprocess.

Vous devez ajouter un adaptateur. sapper build est vaguement équivalent à adapter-node tandis que sapper export est vaguement équivalent à adapter-static, bien que vous préfèrerez peut-être utiliser un adaptateur prévu pour la plateforme sur laquelle vous souhaitez déployer.

Si vous utilisiez des plugins pour traiter des types de fichiers qui ne sont pas automatiquement gérés par Vite, vous aurez besoin de trouver des équivalents Vite, et de les ajouter à votre configuration Vite.

src/client.jspermalink

Ce fichier n'a pas d'équivalent dans SvelteKit. Toute logique personnalisée (autre que sapper.start(...)) doit être incluse dans votre fichier +layout.svelte, dans un callback onMount.

src/server.jspermalink

Ce fichier est l'équivalent d'un serveur personnalisé lorsque vous utilisez adapter-node. Dans les autres cas, ce fichier n'a pas d'équivalent, puisque les applications SvelteKit peuvent être exécutées dans des environnements serverless.

src/service-worker.jspermalink

La plupart des imports depuis @sapper/service-worker ont des équivalents dans $service-worker :

• files est inchangé
• routes a été supprimé
• shell est maintenant build
• timestamp est maintenant version

src/template.htmlpermalink

Le fichier src/template.html doit être renommé src/app.html.

Supprimez %sapper.base%, %sapper.scripts% et %sapper.styles%. Remplacez %sapper.head% par %sveltekit.head% et %sapper.html% par %sveltekit.body%. La balise <div id="sapper"> n'est plus nécessaire.

src/node_modulespermalink

Une habitude classique dans les applications Sapper est de mettre votre librairie interne dans un dossier à l'intérieur de src/node_nodules. Ceci ne fonctionne pas avec Vite, nous utilisons à la place src/lib.

Pages et layoutspermalink

Fichiers renomméspermalink

Les routes sont maintenant définies à partir du nom de dossier exclusivement pour lever toute ambiguité, les noms de dossier menant à un fichier +page.svelte correspondent à la route. Voir la section Routing pour un aperçu du fonctionnement. Le tableau suivant présente une comparaison avant/après :

Votre composant de page d'erreur doit être renommé de _error.svelte en +error.svelte. Tout fichier _layout.svelte doit être renommé en +layout.svelte. Tout autre fichier est ignoré.

Importspermalink

Les imports goto, prefetch et prefetchRoutes depuis @sapper/app doivent être remplacés par les imports goto, preloadData et preloadCode respectivement depuis $app/navigation.

L'import stores depuis @sapper/app doit être remplacé – voir la section sur les Stores plus bas.

Tout fichier que vous importiez précédemment depuis des dossiers de src/node_modules doit maintenant être importé depuis $lib.

Préchargementpermalink

Comme précédemment, les pages et layout peuvent exporter une fonction qui permet de charger des données avant que le rendu n'ait lieu.

Cette fonction a été renommée de preload en load, et doit maintenant être définie dans un fichier +page.js (ou +layout.js) à côté du fichier +page.svelte (ou +layout.svelte) correspondant, et son API a changé. Elle n'attend plus deux arguments – page et session – mais un seul argument event.

Il n'y a plus d'objet this, et par conséquent plus de this.fetch, this.error ou this.redirect. À la place, vous pouvez récupérer la méthode fetch dans les méthodes fournies, et les méthodes error et redirect sont maintenant levées.

Storespermalink

Avec Sapper, vous obteniez les références des stores intégrés de cette façon :

ts
import { stores } from '@sapper/app';
const { preloading, page, session } = stores();

Le store page existe toujours ; preloading a été remplacé par un store navigating qui contient les propriétés from et to. Le store page contient maintenant les propriétés url et params, mais pas path ou query.

Vous y accédez de manière différente avec SvelteKit. stores est maintenant getStores, mais dans la plupart des cas ce n'est pas nécessaire puisque vous pouvez importer navigating et page directement depuis $app/stores.

Routingpermalink

Il n'est plus possible de définir des routes utilisant des expressions régulières. À la place, vous devez utiliser la fonctionnalité avancée des fonctions match.

Segmentspermalink

Auparavant, les composants de layout recevaient une prop segment indiquant le segment enfant. Ceci a été supprimé de SvelteKit ; vous devez maintenant utiliser la valeur $page.url.pathname, qui offre plus de flexibilité et vous permet notamment de récupérer le segment qui vous intéresse.

URLspermalink

Avec Sapper, toutes les URLs relatives étaient résolues par rapport à l'URL de base – en général /, à moins que l'option basepath ait été utilisée – plutôt que par rapport à la page courante.

Ceci a causé des problèmes et n'est donc plus le cas avec SvelteKit. À la place, les URLs relatives sont résolues par rapport à la page courante (ou la page de destination, pour les URLs en argument de fetch dans les fonctions load). Dans la plupart des cas, il est plus simple d'utiliser des URLs relatives à la racine (c'est-à-dire commencant par /), puisque leur signification ne dépend pas du contexte.

Attributs <a>permalink

• sapper:prefetch est maintenant data-sveltekit-preload-data
• sapper:noscroll est maintenant data-sveltekit-noscroll

Endpointspermalink

Avec Sapper, les routes de serveur recevaient des objets req et res exposés par le module http de Node (ou les versions augmentées par les frameworks comme Polka ou Express).

SvelteKit est conçu pour être agnostique de l'endroit où l'application est exécutée – cela peut être un serveur node, mais pourrait tout aussi bien être une plateforme serverless ou un Cloudflare Worker. Pour cette raison, vous ne pouvez plus directement interagir avec req ou res. Vos endpoints doivent être mis à jour pour correspondre à la nouvelle signature.

Pour supporter ce comportement indépendant de l'environnement d'exécution, fetch est maintenant disponible dans le contexte global, vous n'avez donc plus besoin d'importer node-fetch, cross-fetch ou toute autre implémentation serveur de fetch pour pouvoir vous en servir.

Intégrationspermalink

Voir la section sur les intégrations pour des informations détaillées sur les intégrations.

html-minifierpermalink

Sapper inclut html-minifier par défaut. SvelteKit ne l'inclut pas, mais vous pouvez l'ajouter comme dépendance de production et l'utiliser via un hook :

ts
import { minify } from 'html-minifier';
import { building } from '$app/environment';

const minification_options = {
	collapseBooleanAttributes: true,
	collapseWhitespace: true,
	conservativeCollapse: true,
	decodeEntities: true,
	html5: true,
	ignoreCustomComments: [/^#/],
	minifyCSS: true,
	minifyJS: false,
	removeAttributeQuotes: true,
	removeComments: false, // certains codes d'hydratation nécessitent des commentaires, vous ne devriez donc pas les enlever
	removeOptionalTags: true,
	removeRedundantAttributes: true,
	removeScriptTypeAttributes: true,
	removeStyleLinkTypeAttributes: true,
	sortAttributes: true,
	sortClassName: true
};

/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
	let page = '';

	return resolve(event, {
		transformPageChunk: ({ html, done }) => {
			page += html;
			if (done) {
				return building ? minify(page, minification_options) : page;
			}
		}
	});
}

Notez que prerendering vaut false lorsque vous utilisez vite preview pour tester le build de production de votre site. Pour vérifier les résultats de la minification, vous avez besoin d'inspecter directement les fichiers HTML compilés.