Skip to main content

Миграция

Переход с 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. Префикс _ теперь обозначает исключительно собственные private modules, в отличие от тех, которые имеют особое значение для SvelteKit (configurable via routes config).

Импорты

Импорт 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. page теперь имеет свойства url и params, но не имеет path или query.

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

Маршрутизация

Маршруты Regex больше не поддерживаются. Вместо этого используйте перебор маршрутов.

Ссылки

В Sapper все относительные URL-адреса разрешались по базовому URL-адресу — обычно /, если не использовалась опция basepath, а не по отношению к текущей странице.

Это вызвало проблемы и не используется в SvelteKit. Вместо этого URL-адреса разрешаются по текущей странице (или целевой странице для URL-адресов fetch в функциях load).

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

  • 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({ event, resolve }) {
   const response = await resolve(event);

   if (prerendering && response.headers.get('content-type') === 'text/html') {
     return new Response(minify(await response.text(), minification_options), {
     	status: response.status,
     	headers: response.headers
     });
   }

   return response;
}

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