Миграция

Переход с Sapper permalink

SvelteKit – это преемник фреймворка Sapper и перенял много элементов из него.

Если у вас уже есть приложение, написанное на Sapper, которое вы планируете перевести на SvelteKit, то понадобится внести несколько изменений. Возможно, при переходе может оказаться полезным ознакомится с примерами использования.

package.json permalink

type : "module"

Добавьте "type": "module" в package.json. Вы можете выполнить этот шаг отдельно от остальных в рамках инкрементной миграции, если вы используете Sapper 0.29.3 или новее.

dependencies

Удалите polka или express, если вы их используете, а также любые промежуточные обработчики, такие как sirv или compression.

devDependencies

Удалите sapper из devDependencies и замените его на @sveltejs/kit и выбранный вами адаптер (на этапе конфигурации).

scripts

Все скрипты, которые ссылаются на sapper, должны быть обновлены:

Файлы проекта permalink

Большую часть вашего приложения, в src/routes, можно оставить там, где оно есть, но несколько файлов проекта необходимо будет переместить или обновить.

Конфигурация

Замените webpack.config.js или rollup.config.js на svelte.config.js, как описано в документации. Опции препроцессора переместите в config.preprocess.

Добавьте адаптер:

Если вы использовали плагины для типов файлов, которые не обрабатываются автоматически Vite, вам нужно будет найти их эквиваленты для Vite и добавить в Vite config.

src/client.js

У этого файла нет эквивалента в SvelteKit. Любая настраиваемая логика (за пределами sapper.start(...)) должна быть описана в __layout.svelte, внутри функции обратного вызова onMount.

src/server.js

Этот файл также не имеет прямого эквивалента, поскольку приложения SvelteKit могут работать в бессерверных средах. Однако вы можете использовать файл хуков для реализации логики сессии.

src/service-worker.js

Большая часть импорта из @sapper/service-worker имеет эквиваленты в $service-worker:

  • timestamp - без изменений
  • files - без изменений
  • shell => build
  • routes - удалён

src/template.html

Файл src/template.html следует переименовать в src/app.html.

Удалите %sapper.base%, %sapper.scripts% и %sapper.styles%. Замените %sapper.head% на %svelte.head% и %sapper.html% на %svelte.body%.

<div id="sapper"> больше не нужен, хотя вы можете монтировать приложение к любому элементу, указав его с помощью параметра конфигурации target.

src/node_modules

Распространенный шаблон в приложениях Sapper - поместить вашу внутреннюю библиотеку в каталоге внутри src/node_modules. Это не работает с Vite, поэтому мы используем src/lib вместо него.

Страницы и макеты permalink

Переименованные файлы

Компонент настраиваемой страницы ошибки следует переименовать из _error.svelte в __error.svelte. Любые _layout.svelte файлы также должны быть переименованы в __layout.svelte. Префикс _ теперь обозначает исключительно ваши собственные 'приватные' компоненты и модули, в отличие от тех, которые имеют особое значение для SvelteKit.

Импорты

Импорт goto, prefetch и prefetchRoutes из @sapper/app следует заменить идентичным импортом из $app/navigation.

Импорт stores из @sapper/app следует тоже заменить — подробнее в разделе Хранилища.

Любые файлы, которые вы ранее импортировали из каталогов в src/node_modules необходимо будет заменить на импорты из $lib.

Предварительная загрузка

Как и раньше, страницы и компоненты макета могут экспортировать функцию, которая позволяет загружать данные перед отрисовкой.

Эта функция была переименована из preload в load, и её API изменился. Вместо двух аргументов page и session функция теперь получает один объект, который включает в себя оба этих аргумента и функцию fetch (которая заменяет this.fetch), а так же новый объект stuff.

Больше нет объекта this и, следовательно, нет this.fetch, this.error или this.redirect. Вместо возвращения свойств напрямую, функция load теперь возвращает объект, который содержит поле props среди прочих.

Если на вашей странице есть метод load не забудьте вернуть что-нибудь из него, иначе вы получите ошибку Not found.

Хранилища

В Sapper вы получали ссылки на встроенные хранилища, таким образом:

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

Хранилища page и session всё ещё существуют; preloading был заменен на navigating который содержит свойства from и to.

В SvelteKit вы получаете к ним доступ по-другому. stores теперь называется getStores, но в большинстве случаев в этом нет необходимости, поскольку вы можете импортировать navigating, page и session прямо из $app/stores.

Атрибуты ссылок

  • sapper:prefetch => sveltekit:prefetch
  • sapper:noscroll => sveltekit:noscroll

Эндпоинты permalink

В Sapper, 'серверные маршруты', которые теперь называются эндпоинты, получали объекты req и res из Node-модуля http (или их расширенные версии из фреймворков вроде Polka или Express).

SvelteKit разработан так, чтобы не зависеть от того, где запущено приложение - оно может работать на сервере Node, на бессерверной платформе или в Cloudflare Worker. По этой причине вы больше не взаимодействуете напрямую с req и res. Ваши эндпоинты необходимо обновить, чтобы они соответствовали новой архитектуре.

Для поддержки независимого от среды поведения, fetch теперь доступен в глобальном контексте, поэтому вам не нужно импортировать node-fetch, cross-fetch или аналогичные реализации выборки на стороне сервера, чтобы использовать fetch.

Интеграции permalink

См. FAQ для получения подробной информации об интеграции.

HTML-минификатор

Sapper по умолчанию включает html-minifier. SvelteKit не включает это, но его можно добавить как хук:

 import { minify } from 'html-minifier';
 import { prerendering } from '$app/env';

 const minification_options = {
 	collapseBooleanAttributes: true,
 	collapseWhitespace: true,
 	conservativeCollapse: true,
 	decodeEntities: true,
 	html5: true,
 	ignoreCustomComments: [/^#/],
 	minifyCSS: true,
 	minifyJS: false,
 	removeAttributeQuotes: true,
 	removeComments: true,
 	removeOptionalTags: true,
 	removeRedundantAttributes: true,
 	removeScriptTypeAttributes: true,
 	removeStyleLinkTypeAttributes: true,
 	sortAttributes: true,
 	sortClassName: true
 };

 export async function handle({ request, resolve }) {
   const response = await resolve(request);

   if (prerendering && response.headers['content-type'] === 'text/html') {
     response.body = minify(response.body, minification_options);
   }

   return response;
 }

Обратите внимание, что prerendering имеет значение false при использовании svelte-kit preview для тестирования продакшн сборки сайта, поэтому для проверки результатов минификации необходимо напрямую проверить созданные файлы HTML.