Мы перенесли наши три фронтенд проекта с Parcel на Vite, и процесс прошел... гладко.
У нас есть три основных фронтенд проекта в Logto: интерфейс входа, Консоль и предварительный просмотр в реальном времени. Все эти проекты написаны на TypeScript, React и SASS модулях; в сумме они содержат около 100K строк кода.
Нам нравился Parcel за его простоту и настройку без необходимости конфигурации. Я до сих пор помню день, когда был шокирован, насколько легко было создать новый проект с Parcel. Вы можете просто запустить parcel index.html и вуаля, все необходимые зависимости установлены и проект работает. Если ты "опытный" разработчик, возможно, ты чувствуешь то же самое, сравнивая это с прежними днями когда нужно было настраивать Gulp и Webpack. Parcel — это настоящая волшебная палочка.
Простота Parcel была основной причиной, по которой мы оставались с ним так долго, несмотря на то, что иногда он был капризным. Например:
Так почему же мы решили перейти на что-то другое?
Кто-то даже открыл обсуждение, чтобы спросить мертв ли Parcel. Официальный ответ - нет, Parcel все еще жив, но он находится в состоянии «мы работаем над крупным рефакторингом и у нас нет времени на минорные версии». Для нас это выглядит как «смерть утки»: последнюю версию, которую мы можем использовать, выпустили больше года назад, и мы не знаем, когда выйдет следующая версия. Кажется, что Parcel мертв, он ведет себя как мертвец, так что для нас он мертв.
Мы узнали о Vite от Vitest. Несколько месяцев назад мы устали от поддержки ESM в Jest (в тестировании) и решили попробовать что-то новое. Vitest покорил наши сердца благодаря поддержке ESM на уровне ядра и совместимости с Jest. У него потрясающий опыт для разработчиков, и его поддерживает Vite.
Возможно, у вас в проекте можно настроить по-разному, но обычно вы найдете плагиновые замены, так как экосистема Vite развивается. Вот наши настройки на момент миграции:
Мы начали процесс миграции, создав новый проект на Vite, и поиграли с ним, чтобы понять, как он работает. Процесс прошел гладко, и реальная миграция заняла всего несколько дней.
Vite поддерживает монорепозитории, ESM, TypeScript, React и SASS из коробки. Нам нужно было только установить необходимые плагины и конфигурации, чтобы все заработало.
Vite имеет встроенную поддержку псевдонимов путей, например, в нашем tsconfig.json:
Нам нужно было только добавить такое же разрешение в наш vite.config.ts:
Обратите внимание, что путь для замены должен быть абсолютным, хотя он относительно корня проекта. Альтернативно, вы можете использовать плагин vite-tsconfig-paths, чтобы считывать псевдонимы путей из tsconfig.json.
Хотя Vite поддерживает HMR из коробки, для включения React Fast Refresh необходимо установить плагин. Мы использовали плагин @vitejs/plugin-react, который предоставлен командой Vite и отлично поддерживает такие возможности React, как Fast Refresh:
Мы используем плагин vite-plugin-svgr, чтобы конвертировать SVG в компоненты React. Все, что нужно - добавить плагин в конфигурацию Vite:
Однако мы не указали, при каких условиях SVG должен быть преобразован в компоненты React, так что все импорты были конвертированы. Плагин предлагает лучшую конфигурацию по умолчанию: конвертировать только те SVG, которые импортированы с расширением .svg?react. Мы обновили наши импорты соответственно.
Хотя Vite поддерживает SASS модули на уровне ядра, есть одно, на что нам нужно обратить внимание: как форматируются имена классов. Это может вызвать проблемы у пользователей и наши интеграционные тесты, если имена классов будут отформатированы непоследовательно. Одна строка конфигурации в vite.config.ts может решить эту проблему:
Кстати, Parcel и Vite имеют разные способы импорта SASS файлов:
Синтаксис * as, однако, работает в Vite, но он приведет к потере модульных имен классов, когда вы используете динамические ключи для доступа к объекту styles. Например:
Поскольку Vite использует Rollup под капотом, мы можем использовать официальный плагин @mdx-js/rollup, чтобы поддерживать MDX, а также его плагины. Конфигурация выглядит так:
Плагин remarkGfm используется для поддержки GitHub Flavored Markdown, а плагин rehypeMdxCodeProps - для передачи пропсов к блокам кода в файлах MDX, как это делает Docusaurus.
Мы хотим использовать диаграммы Mermaid в наших файлах MDX так же, как и другие языки программирования. Использование должно быть таким же простым, как и другие блоки кода:
Должно рендериться как:
%3btext-align:center%3b%7d%23mermaid-0 .edgeLabel p%7bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3b%7d%23mermaid-0 .edgeLabel rect%7bopacity:0.5%3bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3bfill:rgba(232%2c232%2c232%2c 0.8)%3b%7d%23mermaid-0 .labelBkg%7bbackground-color:rgba(232%2c 232%2c 232%2c 0.5)%3b%7d%23mermaid-0 .cluster rect%7bfill:%23ffffde%3bstroke:%23aaaa33%3bstroke-width:1px%3b%7d%23mermaid-0 .cluster text%7bfill:%23333%3b%7d%23mermaid-0 .cluster span%7bcolor:%23333%3b%7d%23mermaid-0 div.mermaidTooltip%7bposition:absolute%3btext-align:center%3bmax-width:200px%3bpadding:2px%3bfont-family:arial%2csans-serif%3bfont-size:12px%3bbackground:hsl(80%2c 100%25%2c 96.2745098039%25)%3bborder:1px solid %23aaaa33%3bborder-radius:2px%3bpointer-events:none%3bz-index:100%3b%7d%23mermaid-0 .flowchartTitleText%7btext-anchor:middle%3bfont-size:18px%3bfill:%23333%3b%7d%23mermaid-0 rect.text%7bfill:none%3bstroke-width:0%3b%7d%23mermaid-0 .icon-shape%2c%23mermaid-0 .image-shape%7bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3btext-align:center%3b%7d%23mermaid-0 .icon-shape p%2c%23mermaid-0 .image-shape p%7bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3bpadding:2px%3b%7d%23mermaid-0 .icon-shape rect%2c%23mermaid-0 .image-shape rect%7bopacity:0.5%3bbackground-color:rgba(232%2c232%2c232%2c 0.8)%3bfill:rgba(232%2c232%2c232%2c 0.8)%3b%7d%23mermaid-0 :root%7b--mermaid-font-family:arial%2csans-serif%3b%7d%3c/style%3e%3cg%3e%3cmarker orient='auto' markerHeight='8' markerWidth='8' markerUnits='userSpaceOnUse' refY='5' refX='5' viewBox='0 0 10 10' class='marker flowchart-v2' id='mermaid-0_flowchart-v2-pointEnd'%3e%3cpath style='stroke-width: 1%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' d='M 0 0 L 10 5 L 0 10 z'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='8' markerWidth='8' markerUnits='userSpaceOnUse' refY='5' refX='4.5' viewBox='0 0 10 10' class='marker flowchart-v2' id='mermaid-0_flowchart-v2-pointStart'%3e%3cpath style='stroke-width: 1%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' d='M 0 5 L 10 10 L 10 0 z'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='11' markerWidth='11' markerUnits='userSpaceOnUse' refY='5' refX='11' viewBox='0 0 10 10' class='marker flowchart-v2' id='mermaid-0_flowchart-v2-circleEnd'%3e%3ccircle style='stroke-width: 1%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' r='5' cy='5' cx='5'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='11' markerWidth='11' markerUnits='userSpaceOnUse' refY='5' refX='-1' viewBox='0 0 10 10' class='marker flowchart-v2' id='mermaid-0_flowchart-v2-circleStart'%3e%3ccircle style='stroke-width: 1%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' r='5' cy='5' cx='5'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='11' markerWidth='11' markerUnits='userSpaceOnUse' refY='5.2' refX='12' viewBox='0 0 11 11' class='marker cross flowchart-v2' id='mermaid-0_flowchart-v2-crossEnd'%3e%3cpath style='stroke-width: 2%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' d='M 1%2c1 l 9%2c9 M 10%2c1 l -9%2c9'/%3e%3c/marker%3e%3cmarker orient='auto' markerHeight='11' markerWidth='11' markerUnits='userSpaceOnUse' refY='5.2' refX='-1' viewBox='0 0 11 11' class='marker cross flowchart-v2' id='mermaid-0_flowchart-v2-crossStart'%3e%3cpath style='stroke-width: 2%3b stroke-dasharray: 1%2c 0%3b' class='arrowMarkerPath' d='M 1%2c1 l 9%2c9 M 10%2c1 l -9%2c9'/%3e%3c/marker%3e%3cg class='root'%3e%3cg class='clusters'/%3e%3cg class='edgePaths'%3e%3cpath marker-end='url(%23mermaid-0_flowchart-v2-pointEnd)' style='' class='edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link' id='L_A_B_0' d='M72.451%2c62L67.598%2c66.167C62.746%2c70.333%2c53.041%2c78.667%2c48.188%2c86.333C43.336%2c94%2c43.336%2c101%2c43.336%2c104.5L43.336%2c108'/%3e%3cpath marker-end='url(%23mermaid-0_flowchart-v2-pointEnd)' style='' class='edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link' id='L_A_C_1' d='M135.338%2c62L140.191%2c66.167C145.043%2c70.333%2c154.748%2c78.667%2c159.601%2c86.333C164.453%2c94%2c164.453%2c101%2c164.453%2c104.5L164.453%2c108'/%3e%3cpath marker-end='url(%23mermaid-0_flowchart-v2-pointEnd)' style='' class='edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link' id='L_B_D_2' d='M43.336%2c166L43.336%2c170.167C43.336%2c174.333%2c43.336%2c182.667%2c47.683%2c190.566C52.029%2c198.465%2c60.723%2c205.929%2c65.069%2c209.662L69.416%2c213.394'/%3e%3cpath marker-end='url(%23mermaid-0_flowchart-v2-pointEnd)' style='' class='edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link' id='L_C_D_3' d='M164.453%2c166L164.453%2c170.167C164.453%2c174.333%2c164.453%2c182.667%2c160.106%2c190.566C155.76%2c198.465%2c147.066%2c205.929%2c142.72%2c209.662L138.373%2c213.394'/%3e%3c/g%3e%3cg class='edgeLabels'%3e%3cg class='edgeLabel'%3e%3cg transform='translate(0%2c 0)' class='label'%3e%3cforeignObject height='0' width='0'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' class='labelBkg' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='edgeLabel'%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg class='edgeLabel'%3e%3cg transform='translate(0%2c 0)' class='label'%3e%3cforeignObject height='0' width='0'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' class='labelBkg' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='edgeLabel'%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg class='edgeLabel'%3e%3cg transform='translate(0%2c 0)' class='label'%3e%3cforeignObject height='0' width='0'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' class='labelBkg' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='edgeLabel'%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg class='edgeLabel'%3e%3cg transform='translate(0%2c 0)' class='label'%3e%3cforeignObject height='0' width='0'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' class='labelBkg' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='edgeLabel'%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3c/g%3e%3cg class='nodes'%3e%3cg transform='translate(103.89453125%2c 35)' id='flowchart-A-0' class='node default'%3e%3crect height='54' width='70.671875' y='-27' x='-35.3359375' style='' class='basic label-container'/%3e%3cg transform='translate(-5.3359375%2c -12)' style='' class='label'%3e%3crect/%3e%3cforeignObject height='24' width='10.671875'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='nodeLabel'%3e%3cp%3eA%3c/p%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg transform='translate(43.3359375%2c 139)' id='flowchart-B-1' class='node default'%3e%3crect height='54' width='70.671875' y='-27' x='-35.3359375' style='' class='basic label-container'/%3e%3cg transform='translate(-5.3359375%2c -12)' style='' class='label'%3e%3crect/%3e%3cforeignObject height='24' width='10.671875'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='nodeLabel'%3e%3cp%3eB%3c/p%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg transform='translate(164.453125%2c 139)' id='flowchart-C-3' class='node default'%3e%3crect height='54' width='71.5625' y='-27' x='-35.78125' style='' class='basic label-container'/%3e%3cg transform='translate(-5.78125%2c -12)' style='' class='label'%3e%3crect/%3e%3cforeignObject height='24' width='11.5625'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='nodeLabel'%3e%3cp%3eC%3c/p%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3cg transform='translate(103.89453125%2c 243)' id='flowchart-D-5' class='node default'%3e%3crect height='54' width='71.5625' y='-27' x='-35.78125' style='' class='basic label-container'/%3e%3cg transform='translate(-5.78125%2c -12)' style='' class='label'%3e%3crect/%3e%3cforeignObject height='24' width='11.5625'%3e%3cdiv style='display: table-cell%3b white-space: nowrap%3b line-height: 1.5%3b max-width: 200px%3b text-align: center%3b' xmlns='http://www.w3.org/1999/xhtml'%3e%3cspan class='nodeLabel'%3e%3cp%3eD%3c/p%3e%3c/span%3e%3c/div%3e%3c/foreignObject%3e%3c/g%3e%3c/g%3e%3c/g%3e%3c/g%3e%3c/g%3e%3c/svg%3e)
Поскольку наше приложение поддерживает светлую и темную темы, мы немного закодировали, чтобы заставить диаграммы Mermaid работать с темной темой. Была создана компонента React:
useTheme - это настраиваемый хук для получения текущей темы из контекста. Библиотека mermaid импортируется асинхронно, чтобы уменьшить размер загрузки на начальной странице.
Для блока кода в файле MDX у нас есть единый компонент, который выполняет работу:
Наконец, мы определяем MDX провайдер следующим образом:
Это не что-то специфичное для Vite, но все же стоит упомянуть, так как мы обновили наши страницы для использования ленивой загрузки во время миграции, и после этого ничего не сломалось.
React имеет встроенную функцию React.lazy для ленивой загрузки компонентов. Однако это может вызвать некоторые проблемы, когда вы быстро итератируете. Мы разработали небольшую библиотеку под названием react-safe-lazy, чтобы решить эти проблемы. Она является заменой для React.lazy, и подробное объяснение можно найти в этом посте в блоге.
Существует аккуратный плагин под названием vite-plugin-compression, чтобы создавать сжатые файлы. Он поддерживает как gzip, так и brotli сжатие. Конфигурация проста:
Одна из отличных функций Vite (или Rollup, который лежит в его основе) - это ручные чанки. Пока React.lazy используется для ленивой загрузки компонентов, мы можем иметь больше контроля над чанками, определяя ручные чанки, чтобы решить, какие компоненты или модули следует объединить вместе.
Например, мы можем сначала использовать vite-bundle-visualizer, чтобы проанализировать размер бандла и зависимости. Затем мы можем написать правильную функцию для разделения чанков:
В отличие от продакшн-сборки, Vite НЕ будет объединять ваш исходный код в режиме разработки (включая связанные зависимости в той же монорепозиторие) и будет обрабатывать каждый модуль как файл. При этом, браузер загрузит сотни модулей впервые, что может выглядеть странно, но в большинстве случаев это совершенно нормально. Вы можете ознакомиться с обсуждением здесь.
Если для вас это проблема, альтернативное, но не идеальное решение - указать связанные зависимости в опции optimizeDeps файла vite.config.ts:
Это "предварительно объединит" связанные зависимости и ускорит работу dev сервера. Недостатком является то, что HMR может не работать так, как ожидалось, для связанных зависимостей.
Кроме того, мы используем прокси, который обслуживает статические файлы в продакшене и проксирует запросы на сервер Vitest в режиме разработки. У нас есть несколько настроенных портов для избежания конфликтов, и это также легко настроить в файле vite.config.ts:
В отличие от Parcel, Vite использует современный подход к обработке переменных среды с использованием import.meta.env. Он автоматически подгружает .env файлы и заменяет переменные в коде. Однако, это требует, чтобы все переменные среды были префиксированы VITE_ (можно настроить).
Когда мы использовали Parcel, он просто заменял переменные process.env, не проверяя префикс. Поэтому мы придумали обходной путь, используя поле define, чтобы облегчить миграцию:
Это позволяет нам постепенно добавлять префикс к переменным среды и удалять поле define.
Вот и все! Мы успешно перенесли наши три фронтенд проекта с Parcel на Vite и надеемся, что эта короткая история поможет вам с вашей миграцией. Вот как конфигурация выглядит в конце: