3.9. Сборка ресурсов (Vite)

• 1. Введение
• 2. Установка и настройка
  • 2.1. Установка Node
  • 2.2. Установка Vite и плагина Laravel
  • 2.3. Настройка Vite
  • 2.4. Загрузка ваших скриптов и стилей
• 3. Запуск Vite
• 4. Работа с JavaScript
  • 4.1. Алиасы
  • 4.2. Vue
  • 4.3. React
  • 4.4. Inertia
  • 4.5. Обработка URL
• 5. Работа со стилями
• 6. Работа с Blade и маршрутами
  • 6.1. Обработка статических ресурсов с Vite
  • 6.2. Обновление при сохранении
  • 6.3. Алиасы
• Asset Prefetching
• Custom Base URLs
• Environment Variables
• Disabling Vite in Tests
• Server-Side Rendering (SSR)
• Script and Style Tag Attributes
  • Content Security Policy (CSP) Nonce
  • Subresource Integrity (SRI)
  • Arbitrary Attributes
• Advanced Customization
  • Correcting Dev Server URLs

1. Введение

Vite — это современный инструмент сборки фронтенда, который обеспечивает чрезвычайно быструю среду разработки и собирает ваш код для продакшена. При создании приложений с использованием Laravel вы обычно будете использовать Vite для объединения файлов CSS и JavaScript вашего приложения в готовые для продакшена ресурсы.

Laravel безупречно интегрируется с Vite, предоставляя официальный плагин и директиву Blade для загрузки ваших ресурсов в режиме разработки и продакшена.

1.1. Выбор между Vite и Laravel Mix

До перехода на Vite новые приложения Laravel использовали Mix, который работает на основе webpack, для сборки ресурсов. Vite ориентирован на обеспечение более быстрой и продуктивной работы при создании сложных JavaScript-приложений. Если вы разрабатываете одностраничное приложение (SPA), включая те, что создаются с использованием таких инструментов, как Inertia, Vite будет идеальным выбором.

Vite также хорошо работает с традиционными серверно-рендеримыми приложениями с небольшими вкраплениями JavaScript, включая те, что используют Livewire. Однако ему не хватает некоторых возможностей, которые поддерживает Laravel Mix, например, возможности копировать произвольные ресурсы в сборку, которые не используются напрямую в вашем JavaScript-приложении.

1.2. Миграция обратно на Mix

Вы начали новое Laravel-приложение, используя наш каркас Vite, но вам нужно вернуться к Laravel Mix и webpack? Без проблем. Пожалуйста, ознакомьтесь с нашим официальным руководством по миграции с Vite на Mix.

2. Установка и настройка

2.1. Установка Node

Вы должны убедиться, что Node.js (версии 16 и выше) и NPM установлены перед запуском Vite и плагина Laravel:

node -v
npm -v

Вы можете легко установить последнюю версию Node и NPM, используя простые графические установщики с официального сайта Node. Или, если вы используете Laravel Sail, вы можете вызвать Node и NPM через Sail:

./vendor/bin/sail node -v
./vendor/bin/sail npm -v

2.2. Установка Vite и плагина Laravel

В свежей установке Laravel вы найдете файл package.json в корневой структуре каталогов вашего приложения. Файл package.json по умолчанию уже включает все необходимое для начала использования Vite и плагина Laravel. Вы можете установить фронтенд-зависимости вашего приложения с помощью NPM:

npm install

2.3. Настройка Vite

Vite настраивается через файл vite.config.js в корне вашего проекта. Вы можете свободно настраивать этот файл в зависимости от ваших потребностей, а также устанавливать любые другие плагины, необходимые вашему приложению, такие как @vitejs/plugin-vue или @vitejs/plugin-react.

Плагин Laravel Vite требует, чтобы вы указали точки входа для вашего приложения. Это могут быть файлы JavaScript или CSS, включая языки предварительной обработки, такие как TypeScript, JSX, TSX и Sass.

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

Если вы создаете SPA, включая приложения, построенные с использованием Inertia, Vite лучше всего работает без точек входа для CSS:

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

Вместо этого вам следует импортировать ваш CSS через JavaScript. Обычно это делается в файле resources/js/app.js вашего приложения:

import './bootstrap';
import '../css/app.css'; 

Плагин Laravel также поддерживает несколько точек входа и расширенные параметры конфигурации, такие как точки входа для SSR.

Работа с защищённым сервером разработки

Если ваш локальный веб-сервер разработки обслуживает ваше приложение через HTTPS, вы можете столкнуться с проблемами при подключении к серверу разработки Vite.

Если вы используете Laravel Herd и защитили сайт, или вы используете Laravel Valet и выполнили команду secure для вашего приложения, плагин Laravel Vite автоматически обнаружит и использует сгенерированный TLS-сертификат для вас.

Если вы защитили сайт, используя хост, который не совпадает с именем каталога приложения, вы можете вручную указать хост в файле vite.config.js вашего приложения:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            detectTls: 'my-app.test', 
        }),
    ],
});

При использовании другого веб-сервера вам следует сгенерировать доверенный сертификат и вручную настроить Vite для использования сгенерированных сертификатов:

// ...
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`), 
        }, 
    }, 
});

Если вы не можете сгенерировать доверенный сертификат для вашей системы, вы можете установить и настроить плагин @vitejs/plugin-basic-ssl. При использовании недоверенных сертификатов вам потребуется принять предупреждение о сертификате для сервера разработки Vite в вашем браузере, следуя по ссылке "Local" в вашей консоли при выполнении команды npm run dev.

Запуск сервера разработки в Sail на WSL2

При запуске сервера разработки Vite в Laravel Sail на Windows Subsystem for Linux 2 (WSL2) вам следует добавить следующую конфигурацию в файл vite.config.js, чтобы браузер мог взаимодействовать с сервером разработки:

// ...
 
export default defineConfig({
    // ...
    server: { 
        hmr: {
            host: 'localhost',
        },
    }, 
});

Если изменения в файлах не отображаются в браузере во время работы сервера разработки, возможно, вам также нужно настроить параметр server.watch.usePolling в Vite.

2.4. Загрузка ваших скриптов и стилей

С настроенными точками входа Vite вы можете теперь ссылаться на них в директиве Blade @vite(), которую нужно добавить в <head> корневого шаблона вашего приложения:

<!DOCTYPE html>
<head>
    {{-- ...  --}}
 
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

Если вы импортируете ваш CSS через JavaScript, вам нужно добавить только точку входа для JavaScript:

<!DOCTYPE html>
<head>
    {{--  ...  --}}
 
    @vite('resources/js/app.js')
</head>

Директива @vite() автоматически обнаружит сервер разработки Vite и подключит клиент Vite для включения функции горячей замены модулей (Hot Module Replacement). В режиме сборки директива загрузит ваши скомпилированные и версионированные ресурсы, включая любой импортированный CSS.

При необходимости вы также можете указать путь к скомпилированным ресурсам при вызове директивы @vite():

<!doctype html>
<head>
    {{--  Указанный путь сборки является относительным по отношению к публичному пути (public path).  --}}
 
    @vite()('resources/js/app.js', 'vendor/courier/build')
</head>

2.4.1. Встраиваемые ресурсы

Иногда может возникнуть необходимость включить исходное содержимое ресурсов, а не ссылаться на версионированный URL ресурса. Например, вам может понадобиться включить содержимое ресурса непосредственно в вашу страницу при передаче HTML-контента генератору PDF. Вы можете вывести содержимое ресурсов Vite, используя метод content, предоставляемый фасадом Vite:

@use('Illuminate\Support\Facades\Vite')
 
<!doctype html>
<head>
    --{{ ... --}}
 
    <style>
        {!! Vite::content('resources/css/app.css') !!}
    </style>
    <script>
        {!! Vite::content('resources/js/app.js') !!}
    </script>
</head>

3. Запуск Vite

Существует два способа запуска Vite. Вы можете запустить сервер разработки с помощью команды dev, что удобно при локальной разработке. Сервер разработки автоматически обнаружит изменения в ваших файлах и мгновенно отобразит их в любых открытых окнах браузера.

Или, запустив команду build, вы сможете версионировать и собрать ресурсы вашего приложения, подготовив их для деплоя в продакшен:

# Запуск сервера разработки Vite...
npm run dev
 
# Сборка и версионирование ресурсов для production...
npm run build

Если вы запускаете сервер разработки в Sail на WSL2, вам могут понадобиться дополнительные параметры конфигурации.

4. Работа с JavaScript

4.1. Алиасы

По умолчанию плагин Laravel предоставляет общий алиас, который помогает быстро начать работу и удобно импортировать ресурсы вашего приложения:

{
    '@' => '/resources/js'
}

Вы можете перезаписать алиас '@', добавив свой собственный в конфигурационный файл vite.config.js:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel(['resources/ts/app.tsx']),
    ],
    resolve: {
        alias: {
            '@': '/resources/ts',
        },
    },
});

4.2. Vue

Если вы хотите разрабатывать фронтенд с использованием фреймворка Vue, вам также потребуется установить плагин @vitejs/plugin-vue:

npm install --save-dev @vitejs/plugin-vue

Затем вы можете включить этот плагин в свой конфигурационный файл vite.config.js. При использовании плагина Vue с Laravel вам потребуются несколько дополнительных параметров:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';
 
export default defineConfig({
    plugins: [
        laravel(['resources/js/app.js']),
        vue({
            template: {
                transformAssetUrls: {
                    // The Vue plugin will re-write asset URLs, when referenced
                    // in Single File Components, to point to the Laravel web
                    // server. Setting this to `null` allows the Laravel plugin
                    // to instead re-write asset URLs to point to the Vite
                    // server instead.
                    base: null,
 
                    // The Vue plugin will parse absolute URLs and treat them
                    // as absolute paths to files on disk. Setting this to
                    // `false` will leave absolute URLs un-touched so they can
                    // reference assets in the public directory as expected.
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

4.3. React

Если вы хотите разрабатывать свой фронтенд с использованием фреймворка React, вам также потребуется установить плагин @vitejs/plugin-react:

npm install --save-dev @vitejs/plugin-react

Затем вы можете включить этот плагин в свой конфигурационный файл vite.config.js:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';
 
export default defineConfig({
    plugins: [
        laravel(['resources/js/app.jsx']),
        react(),
    ],
});

Вам необходимо убедиться, что все файлы, содержащие JSX, имеют расширение .jsx или .tsx, не забыв при необходимости обновить точку входа, как показано выше.

Вам также потребуется добавить дополнительную директиву Blade @viteReactRefresh вместе с существующей директивой @vite().

@viteReactRefresh
@vite('resources/js/app.jsx')

Директива @viteReactRefresh должна вызываться перед директивой @vite.

4.4. Inertia

The Laravel Vite plugin provides a convenient resolvePageComponent function to help you resolve your Inertia page components. Below is an example of the helper in use with Vue 3; however, you may also utilize the function in other frameworks such as React:

Плагин Laravel Vite предоставляет удобную функцию resolvePageComponent, которая помогает загружать компоненты страниц Inertia. Ниже приведен пример использования этого хелпера с Vue 3; однако, вы также можете использовать эту функцию в других фреймворках, таких как React:

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
 
createInertiaApp({
  resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .mount(el)
  },
});

Если вы используете функцию Vite для разделения кода (code splitting) с Inertia, мы рекомендуем настроить предзагрузку ресурсов.

4.5. Обработка URL

При использовании Vite и ссылках на ресурсы в HTML, CSS или JS вашего приложения необходимо учитывать несколько моментов. Во-первых, если вы ссылаетесь на ресурсы с абсолютным путем, Vite не включит их в сборку; поэтому убедитесь, что ресурс доступен в вашей публичной директории. Следует избегать использования абсолютных путей при использовании отдельной точки входа для CSS, так как в режиме разработки браузеры будут пытаться загружать эти пути с сервера разработки Vite, где находится CSS, а не из вашей публичной директории.

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

Рассмотрим следующую структуру проекта:

public/
  taylor.png
resources/
  js/
    Pages/
      Welcome.vue
  images/
    abigail.png

Следующий пример демонстрирует, как Vite будет обрабатывать относительные и абсолютные URL:

<!-- Этот ресурс не обрабатывается Vite и не будет включен в сборку -->
<img src="/taylor.png">
 
<!-- Этот ресурс будет перезаписан, версионирован и собран Vite -->
<img src="../../images/abigail.png">

5. Работа со стилями

Вы можете узнать больше о поддержке CSS в Vite в документации Vite. Если вы используете плагины PostCSS, такие как Tailwind, вы можете создать файл postcss.config.js в корне вашего проекта, и Vite автоматически применит его:

export default {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};

6. Работа с Blade и маршрутами

6.1. Обработка статических ресурсов с Vite

При ссылках на ресурсы в вашем JavaScript или CSS, Vite автоматически обрабатывает и версионирует их. Кроме того, при создании приложений на основе Blade, Vite также может обрабатывать и версионировать статические ресурсы, на которые вы ссылаетесь только в шаблонах Blade.

Однако, чтобы это работало, вам нужно сообщить Vite о ваших ресурсах, импортировав статические файлы в точку входа приложения. Например, если вы хотите обрабатывать и версионировать все изображения, хранящиеся в resources/images, и все шрифты, хранящиеся в resources/fonts, вам следует добавить следующее в точку входа вашего приложения resources/js/app.js:

import.meta.glob([
  '../images/**',
  '../fonts/**',
]);

Эти ресурсы теперь будут обработаны Vite при запуске npm run build. После этого вы можете ссылаться на них в шаблонах Blade, используя метод Vite::asset, который вернет версионированный URL для данного ресурса:

<img src="{{ Vite::asset('resources/images/logo.png') }}">

6.2. Обновление при сохранении

Когда ваше приложение построено с использованием традиционного серверного рендеринга с Blade, Vite может улучшить ваш процесс разработки, автоматически обновляя браузер при изменении файлов представлений в вашем приложении. Чтобы начать, вы можете просто указать опцию refresh как true.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: true,
        }),
    ],
});

Когда опция refresh установлена в true, сохранение файлов в следующих каталогах приведет к полной перезагрузке страницы в браузере во время работы команды npm run dev:

• app/Livewire/**
• app/View/Components/**
• lang/**
• resources/lang/**
• resources/views/**
• routes/**

Отслеживание изменений в каталоге routes/** полезно, если вы используете Ziggy для генерации ссылок на маршруты во фронтенде вашего приложения.

Если эти пути по умолчанию не соответствуют вашим требованиям, вы можете указать собственный список путей для отслеживания:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: ['resources/views/**'],
        }),
    ],
});

Под капотом плагин Laravel Vite использует пакет vite-plugin-full-reload, который предлагает несколько расширенных опций конфигурации для точной настройки поведения этой функции. Если вам требуется такой уровень настройки, вы можете задать определение config:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            refresh: [{
                paths: ['path/to/watch/**'],
                config: { delay: 300 }
            }],
        }),
    ],
});

6.3. Алиасы

В JavaScript-приложениях часто создаются алиасы для каталогов, к которым регулярно осуществляется доступ. Однако вы также можете создавать алиасы для использования в Blade с помощью метода macro класса Illuminate\Support\Facades\Vite. Обычно "макросы" следует определять в методе boot сервис-провайдера:

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Vite::macro('image', fn (string $asset) => $this->asset("resources/images/{$asset}"));
}

После того как макрос был определен, его можно вызывать в ваших шаблонах. Например, мы можем использовать макрос image, определенный выше, чтобы ссылаться на ресурс, расположенный по пути resources/images/logo.png:

<img src="{{ Vite::image('logo.png') }}" alt="Laravel Logo">