Перенос ломающих изменений в SvelteKit

В последнее время SvelteKit претерпел несколько серьезных изменений, включая полную перестройку маршрутизации, изменения в API нагрузки и переход на Vite CLI. Если вы пользовались им в прошлом, он может выглядеть совсем иначе, чем раньше. Только если посмотреть на августовские обновления, то в них было десять изменений. За этим сложно уследить, поэтому в этой заметке мы рассмотрим самые значительные изменения и расскажем, как перенести приложение, чтобы привести его в актуальное состояние.

До свидания маршрутизация на основе файлов

Самым большим изменением в SvelteKit является отказ от маршрутизации на основе файлов. По-прежнему существует каталог routes, где вы будете создавать свои маршруты, но теперь они основаны на каталогах и требуют префикса + для создания маршрута.

Маршрутизация старым способом

Раньше любой файл, добавленный в каталог routes, создавал маршрут с таким именем. Это затрудняло размещение файлов без более запутанного синтаксиса. Двойное подчеркивание, __, указывало на маршрут компоновки или ошибки, а одинарное подчеркивание, _, позволяло не создавать маршрут. Все было беспорядочно, и ничто не было сгруппировано.

📂 src
└ 📂 routes
  ├ 📄 index.svelte
  ├ 📄 about.svelte
  ├ 📄 __layout.svelte
  ├ 📄 __layout-nested.svelte
  ├ 📄 __error.svelte
  └ 📂 nested-route
    └ 📄 _component-for-nested.svelte  
    └ 📄 index@nested.svelte
Вход в полноэкранный режим Выход из полноэкранного режима

Маршрутизация по-новому

Теперь все маршруты основаны на каталогах, кроме домашнего или корневого маршрута, все новые маршруты должны находиться в папке. Старый index.svelte исчез в пользу +page.svelte, чтобы показать, что вы намеренно создаете маршрут. Также больше не требуется подчеркивание, _, для привязки компонента к маршруту. В новой структуре маршрутизации гораздо понятнее, к какому маршруту привязан каждый файл.

📂 src
└ 📂 routes
  ├ 📄 +page.svelte
  ├ 📄 +layout.svelte
  ├ 📄 +error.svelte
  └  📂 about
     ├ 📄 coc.svelte
     ├ 📄 +page.svelte
     └ 📄 +layout.svelte
Вход в полноэкранный режим Выход из полноэкранного режима

Ресурсы

Чтобы узнать больше о том, почему произошли эти изменения, на GitHub есть несколько действительно хороших обсуждений, а в документации подробно описана новая структура.

  • Документация по маршрутизации

  • Обсуждение изменений в RFC

  • Обзор изменений маршрутизации

  • Комментарий Рича об изменениях в маршрутизации

Капитальный ремонт макетов

Макеты в Svelte претерпели значительные изменения. Больше не нужно размещать несколько макетов в корне каталога routes, а затем именовать их в файле типа index@nested.svelte. Основные макеты теперь представляют собой файлы +layout.svelte и наследуются от корневого макета, независимо от степени их вложенности.

Макеты старым способом

📂 src
└ 📂 routes
  ├ 📄 index.svelte
  ├ 📄 __layout.svelte
  ├ 📄 __layout-nested.svelte
  └ 📂 nested-route
    └ 📄 index@nested.svelte
Вход в полноэкранный режим Выход из полноэкранного режима

Макеты по-новому

📂 src
└ 📂 routes
  ├ 📄 +page.svelte
  ├ 📄 +layout.svelte
  └  📂 about
     ├ 📄 +page.svelte
     └ 📄 +layout.svelte // will inherit the src/routes/+layout.svelte layout
Вход в полноэкранный режим Выход из полноэкранного режима

Групповые макеты

Также существует новое соглашение для совместного использования макетов с папкой, заключенной в круглые скобки(), называемой групповым каталогом. Групповые каталоги не влияют на URL пути вложенных маршрутов, по сути, они действуют как корневой маршрут. Файл +page.svelte может быть добавлен в корневой каталог (group), если маршрут / или home должен быть групповым. Поскольку макеты наследуются по нисходящей, вы можете захотеть использовать другой макет во вложенном маршруте. Для этого можно использовать синтаксис именованного макета +page@nested.svelte, где nested — имя макета, который вы хотите использовать. Чтобы полностью отказаться от макета и сбросить его, создайте файл +layout@.svelte в каталоге с файлом +page.svelte, который нужно сбросить.

📂 src
└ 📂 routes
  ├ 📄 +layout.svelte
  └  📂 (marketing) // group routes
     ├ 📂 about
       ├ 📂 embed
         ├ 📄 +page.svelte
         └ 📄 +layout@(marketing).svelte // this will skip the about layout
       └ 📄 +layout.svelte
     ├ 📂 coc
       ├ 📄 +page.svelte
       └ 📄 +layout@.svelte //this will opt out of all layouts
     ├ 📄 +page.svelte // lives at / not /marketing
     └ 📄 +layout.svelte
Вход в полноэкранный режим Выход из полноэкранного режима

Ресурсы

Эти изменения были не самыми простыми, и даже документацию сейчас трудновато разобрать, но она есть. Обсуждение изменений на GitHub показалось мне более полезным и понятным.

  • Документы по макетам

  • Документы по расширенной компоновке

  • Обсуждение изменений в RFC

Устранение путаницы при загрузке

Функция load — это то, как маршрут SvelteKit получает внешние данные, например, из базы данных или стороннего API. Раньше всегда существовала путаница в том, где выполняется функция load — на сервере или на клиенте, и никогда не было ясно, просачиваются ли секреты на клиент. Теперь функция load перенесена из файла .svelte в файл конечной точки.

Загрузка старым способом

Раньше функция load находилась в теге сценария context="module" внутри файла .svelte или данные для маршрута волшебным образом возвращались из конечной точки. Не так давно произошло еще одно изменение в способе загрузки данных в компонент. Хотя официальное название было page endpoints, мы, приверженцы, продолжали бороться за явно более круто звучащие shadow endpoints. Они автоматически загружали данные из конечной точки непосредственно в маршрут .svelte, возвращая данные, а затем экспортируя одноименное свойство в маршрут.

📂 src
└ 📂 routes
  ├ 📄 index.svelte
  ├ 📄 index.js
  ├ 📄 about.svelte
  ├ 📄 about.js
  ├ 📄 __layout.svelte
  ├ 📄 __layout-nested.svelte
  ├ 📄 __error.svelte
  └ 📂 nested-route
    ├ 📄 index.js
    └ 📄 index@nested.svelte
Вход в полноэкранный режим Выход из полноэкранного режима
// in a .svelte route
<script context="module">
  export const load = () => {
    let propName = "arbitrary data"
    return {
      props: {
    propName
      }
    }
  }
</script>

<script>
  export let propName
</script>

<h1>Use the {propName}</h1>
Войти в полноэкранный режим Выход из полноэкранного режима

Загрузить новый способ

Теперь функция load переместилась в файл конечной точки, а магическая загрузка данных в файл .svelte по-прежнему существует и передается в маршрут с помощью свойства data. Есть два новых файла, которые можно использовать для загрузки данных в маршрут. +page.js (или +page.ts для TypeScript) запускается на сервере во время рендеринга на стороне сервера и снова на клиенте при навигации на стороне клиента. Существует также +page.server.js, который будет выполняться только на сервере, что делает его безопасным для ключей API и защищенных SDK, которые вы не хотите передавать клиенту. Вам также больше не нужно возвращать данные внутри объекта props. Вы сами определяете, где загружать эти данные: только на сервере или и на сервере, и на клиенте. В файле маршрута +page.svelte реквизит теперь называется просто data.

📂 src
└ 📂 routes
  ├ 📄 +page.svelte
  ├ 📄 +page.js
  ├ 📄 +layout.svelte
  ├ 📄 +error.svelte
  └  📂 about
     ├ 📄 +page.svelte
     ├ 📄 +page.server.js
     └ 📄 +layout.svelte
Вход в полноэкранный режим Выход из полноэкранного режима
// in a +page.js or +page.server.js endpoint
// copy over your load function from before
export const load = () => {
  let propName = "arbitrary data"
  return {
    // remove the props object 
    propName
  }
}
Войти в полноэкранный режим Выход из полноэкранного режима
// in a +page.svelte route
<script>
  export let data
</script>

<h1>Use the {data.propName}</h1>
Войти в полноэкранный режим Выход из полноэкранного режима

Поведение страницы

Экспорты, определяющие поведение страницы, также переместились из <script context="module"> в файл конечной точки +page.js.

Ресурсы

Вот некоторые ссылки на документацию по новым файлам конечных точек и загрузке данных.

  • +page.js Docs

  • +page.server.js Docs

  • Документы по загрузке данных

Все на Vite

SvelteKit полностью вошел в экосистему Vite, вытащив конфигурацию Vite и став плагином Vite. Когда-то давно SvelteKit работал на Snowpack. Они приняли решение о переходе после выхода Vite версии 2 в 2021 году и добавления поддержки других фреймворков, помимо Vue. Это был только базовый инструмент сборки, а SvelteKit все еще передавал конфигурацию Vite через собственный файл svelte.config.js и использовал собственную команду sveltekit CLI для запуска скриптов разработки и сборки. Это был экспериментальный метод, и целью было перейти к более стандартному способу взаимодействия фреймворков с Vite — через плагин. Это позволит обеспечить поддержку от первого лица для таких инструментов, как Vitest и Storybook, которые ищут файл конфигурации Vite. С новыми изменениями SvelteKit — это просто проект Vite, который использует плагин @sveltejs/kit/vite и переключился на Vite CLI для сценариев разработки и сборки. Теперь в корне проекта SvelteKit есть файл vite.config.js, который включает плагин вместе с любой другой конфигурацией Vite.

Vite Старый способ

// svelte.config.js
import adapter from '@sveltejs/adapter-auto';
import preprocess from 'svelte-preprocess';

/** @type {import('@sveltejs/kit').Config} */
const config = {
// Consult https://github.com/sveltejs/svelte-preprocess
// for more information about preprocessors
preprocess: preprocess(),

  kit: {
    adapter: adapter(),
    vite: {
      // vite config stuff
    }
  };

export default config;
Вход в полноэкранный режим Выход из полноэкранного режима
// package.json
{
  "scripts": {
    "dev": "svelte-kit dev",
    "build": "svelte-kit build",
    "preview": "svelte-kit preview",
  }
}
Войти в полноэкранный режим Выход из полноэкранного режима

Vite Новый способ

// vite.config.js
import { sveltekit } from '@sveltejs/kit/experimental/vite';

export default {
  plugins: [ sveltekit() ]
};
Войти в полноэкранный режим Выйти из полноэкранного режима
// package.json
{
  "scripts": {
      "dev": "vite dev",
      "build": "vite build",
      "preview": "vite preview",
  }
}
Войти в полноэкранный режим Выход из полноэкранного режима

Перенос изменений

Большие изменения всегда приносят пользователям много разочарований. Мейнтейнеры SvelteKit приняли это во внимание и создали целое руководство по миграции и команду npx svelte-migrate routes, которая пытается сделать многие изменения за вас. Сценарий переименовывает файлы внутри каталога routes, комментирует все, что находится в теге сценария контекстного модуля, и выбрасывает ошибки, чтобы сообщить вам о необходимости обновления до реквизита data. Однако, ни один инструмент не может позаботиться обо всем, и все равно будут изменения, которые необходимо обновить вручную. В зависимости от того, сколько времени прошло с момента обновления, вам может потребоваться изменить несколько вещей. Вот обзорные шаги, которые необходимо выполнить.

  1. Удалите старые файлы блокировки и модули node_modules.

    rm -rf node_modules package-lock.json # or yarn-lock or pnpm-lock
    
  2. Обновите зависимости через менеджер пакетов.

    npm i # or yarn or pnpm
    
  3. Выполните команду миграции. Маршруты будут переименованы и помещены в новую структуру каталогов, а файлы конечных точек попытаются переместиться в соответствующий тип.

    npx svelte-migrate routes
    
  4. Обновите все props в файлах +page.svelte до data.

    - export let propName
    + export let data
    
  5. Удалите все <script context="module">, перешедшие в конечный файл.

    // in a +page.js or +page.server.js endpoint
    // copy over your load function from the .svelte file
    export const load = () => {
        let propName = "arbitrary data"
        return {
          // remove the props object 
          propName
        }
    }
    
  6. Убедитесь, что ваши скрипты были обновлены до Vite CLI в package.json.

    // package.json
    {
      "scripts": {
        "dev": "vite dev",
        "build": "vite build",
        "preview": "vite preview",
      }
    }
    
  7. Попробуйте запустить его!

    npm run dev # or yarn or pnpm
    

Эти шаги — лишь общий обзор самых больших изменений. В зависимости от того, когда вы последний раз обновлялись, могут быть и другие шаги, которые необходимо выполнить. Ошибки SvelteKit довольно хороши и могут помочь вам пройти через любые другие изменения, которые вам нужно сделать. Также в вашем приложении могут быть уникальные ситуации, которые потребуют дополнительной работы. Добавив файл +page.server.js, убедитесь, что вы загружаете данные туда, куда вам нужно. Надеюсь, это поможет вам пройти большую часть пути.

Ресурсы

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

  • Руководство по миграции
  • Документация SvelteKit

Движение вперед

В последнее время в SvelteKit произошло так много изменений, что многие из нас надеются увидеть свет в конце тоннеля в ближайшее время. Будем надеяться, что эти быстрые изменения означают, что мы приближаемся к версии 1.0. Надеюсь, эта заметка помогла преодолеть разрыв между последними изменениями. Идите вперед и мигрируйте!

Другие ресурсы

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

  • Бюллетень августовских обновлений в Svelte

  • Структура проекта

  • Обсуждение изменений маршрутизации

  • Обсуждение изменений в макете

В нескольких подкастах рассказывалось о последних изменениях. Если вы предпочитаете слушать, а не читать, посмотрите эти выпуски Svelte Radio и SyntaxFM.

  • Svelte Radio — SvelteKit быстро меняется
  • Svelte Radio — Поговорим о маршрутизации с Ричем Харрисом
  • SyntaxFM — Supper Club x Рич Харрис, автор Svelte

Оцените статью
devanswers.ru
Добавить комментарий