Laravel: Перенос проекта с Webpack на Vite

Vite — фронтенд инструмент следующего поколения, который с теперь используется в Laravel по умолчанию.

Документация Laravel содержит целый раздел объясняющий как он работает и как его использовать. Но большинству из нас интереснее использовать его в существующем проекте. Вот для чего эта статья.

Примечание: В этой статье основное внимание уделяется миграции базового приложения Laravel на Vite. Если вы используете такие инструменты, как React или Vue, то могут быть существенные различия в миграции с webpack на vite.

Почему Vite

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

Основное преимущество — общее улучшение производительности. Vite быстрее запускает новый сервер, объединяет и обновляет ресурсы, чем другие инструменты, такие как webpack.

Vite использует новые достижения в экосистеме, такие как доступность нативных модулей ES в браузере и рост количества инструментов JavaScript, написанных на компилируемых языках. Подробное объяснение содержится в разделе Почему Vite официальной документации.

Зависимости

Убедитесь, что у вас установлена последняя версия Laravel (на текущий момент 9.19), чтобы воспользоваться новым инструментом Vite. Затем нужно установить две новые зависимости:

npm install --save-dev vite laravel-vite-plugin

Так же, изменится секция script файла package.json из-за новых сценариев Vite:

"scripts": {
    "dev": "vite",
    "build": "vite build"
},

Это всё, что нам нужно в секции scripts.

Поскольку Vite является заменой webpack, мы можем удалить зависимость laravel-mix и удалить файл webpack.mix.js из нашего приложения.

npm remove laravel-mix && rm webpack.mix.js

Ваш package.json должен выглядеть примерно так:

    "private": true,
    "scripts": {
        "dev": "vite",
        "build": "vite build"
    },
    "devDependencies": {
        "axios": "^0.25",
        "laravel-vite-plugin": "^0.2.1",
        "lodash": "^4.17.19",
        "postcss": "^8.4.14",
        "postcss-import": "^14.0.1",
        "vite": "^2.9.11",
    }
}

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

Теперь нужно настроить Vite. Создайте в корне вашего Laravel приложения новый файл vite.config.js:

import laravel from 'laravel-vite-plugin'
import {defineConfig} from 'vite'

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

Мы используем пакеты vite и laravel-vite-plugin, а также определяем пути к ресурсам.

Подключение Vite в шаблонах

В заголовке файла шаблонов нужно подключить загрузку ресурсов через новую директиву blade @vite:

@vite(['resources/css/app.css', 'resources/js/app.js'])

Больше не нужно использовать mix или загружать его вручную.

Запуск Vite

Для запуска Vite используйте npm-сценарий npm run dev заданный нами являющийся псевдонимом для npm run vite.

Он быстро скомпилирует ваши ресурсы! Для подготовки ресурсов к продакшену используйте npm run build.

В фоновом режиме Vite используете новые ресурсы скомпилированные в каталог public/build. Значит можно удалить старые каталоги ресурсов, в моём случае public/css и public/js.

Может измениться импорт JS модулей

Vite поддерживает только модули ES, поэтому require больше не работает, и вам нужно использовать import в своих модулях.

Этот пример больше не работает с Vite:

require('my-package');

Этот пример работает с Vite:

import myPackage from 'my-package';

Использование Tailwind CSS

Если в laravel проекте используется Tailwind CSS, стили перестанут работать. Теперь для работы с Tailwind CSS нужен PostCSS.

Создайте файл postcss.config.js, если вы ещё не сделали это, и задайте в нём два плагина:

module.exports = {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};

Также необходимо установить эти пакеты, но если вы используете Tailwind CSS, они уже должны быть установлены у вас.

Vite ищет файл конфигурации PostCSS и автоматически применяет его. Это всё. Ваши Tailwind CSS стили должны работать.

Переменные среды

Нужно внедрить переменные среды в JavaScript через .env файл, добавив к ним префикс VITE_.

Например, данные переменные Laravel Pusher вам больше не нужны.

MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

Если хотите использовать их в JavaScript — переименуйте:

VITE_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
VITE_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

Автоматическая миграция на Vite

Laravel Shift — отличный сервис для миграции приложения Laravel на новую версию всего одним кликом мыши.

Так же была выпущена новая миграция, которая переносит Laravel Mix на Vite.

Авто обновление шаблонов при изменении

Одна из наиболее заметных особенностей Vite — Hot Module Replacement для Vue.js и React.

Но она также подходит для обновления браузера после изменения файла. По умолчанию это не работает с blade-файлами, но есть рабочее решение.

Просто обновите конфигурацию Vite c помощью пользовательского плагина blade:

import laravel from 'laravel-vite-plugin'
import {defineConfig} from 'vite'

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
        {
            name: 'blade',
            handleHotUpdate({ file, server }) {
                if (file.endsWith('.blade.php')) {
                    server.ws.send({
                        type: 'full-reload',
                        path: '*',
                    });
                }
            },
        }
    ],
});

Этого достаточно для авто обновления браузера после изменения blade-файла. И это происходит молниеносно!

Решение проблем

Блокировка браузера

Некоторые браузеры, такие как Brave, по умолчанию блокируют запрос Vite. Вы увидите ошибки в консоли браузера. Это может помешать Vite скомпилировать ваши ресурсы. Поэтому обязательно проверьте свой браузер, если увидите ошибки блокировки запроса.

HTTPS и Valet

Если вы запускаете Laravel Valet локально с сайтами защищёнными HTTPS, то можете столкнуться с проблемой. Но, уже найдено решение.

Если изложить решение кратко, то вам нужно сконфигурировать Vite использовать сертификаты генерируемые Valet:

// ...
+import fs from 'fs';

+const host = 'my-app.test';

export default defineConfig({
    // ...
+    server: {
+        host,
+        hmr: { host },
+        https: {
+            key: fs.readFileSync(`/path/to/${host}.key`),
+            cert: fs.readFileSync(`/path/to/${host}.crt`),
+        },
+    },
});

Успешные pull request

Это может вам помочь увидеть как другие уже перенесли свои Laravel проекты на Vite:

• Larastreamers
• Laravel.io
• Spatie

Заключение

Мне нравится Vite, и я надеюсь это руководство поможет вам быстрее перевести на него существующий проект. Я то-то упустил? Свяжитесь со мной в Твиттере.

Хотите узнать больше о Vite? Вот несколько отличных ресурсов:

• Auto-Refresh Livewire Components While Keeping States With Vite
• Official upgrade guide
• Official Vite documentation