Збирання ресурсів (Vite)

Вступ
Встановлення & Налаштування
Запуск Vite
Робота з JavaScript
Робота зі стилями
Робота з Blade та маршрутами
Попереднє завантаження ресурсів
Спеціальні базові URL-адреси
Змінні середовища
Вимкнення Vite у тестах
Рендеринг на стороні сервера (SSR)
Атрибути тегів Script і Style
Розширене налаштування
- Спільне використання ресурсів з різних джерел на сервері розробки (CORS)
- Коригування URL-адрес серверу розробки

Вступ

Vite — це сучасний інструмент для збірки фронтенду, який забезпечує надзвичайно швидке середовище розробки та збирає ваш код для продакшну. Під час створення застосунків з Laravel ви зазвичай використовуєте Vite для збірки CSS та JavaScript файлів вашого застосунку у готові для продакшну ресурси.

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

Встановлення & Налаштування

Наступна документація обговорює, як вручну встановити та налаштувати плагін Laravel Vite. Однак, стартові набори Laravel вже включають все це налаштування і є найшвидшим способом почати роботу з Laravel та Vite.

Встановлення 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

Встановлення Vite та плагіна Laravel

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

npm install

Налаштування 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 command для вашого застосунку, плагін 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.

Завантаження ваших скриптів та стилів

З налаштованими точками входу 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 для увімкнення гарячої заміни модулів. У режимі збірки директива завантажить ваші скомпільовані та версійовані ресурси, включаючи імпортовані CSS.

Якщо потрібно, ви також можете вказати шлях збірки ваших скомпільованих ресурсів при виклику директиви @vite:

 <!doctype html>
<head>
    {{-- Заданий шлях збірки є відносним до публічного шляху. --}}
 
    @vite('resources/js/app.js', 'vendor/courier/build')
</head>

Вбудовані ресурси

Іноді може бути необхідно включити сирий вміст ресурсів, а не посилатися на версіоновану 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>

Запуск Vite

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

Або, виконання команди build здійснить версіонування та об'єднання ресурсів вашого застосунку і підготує їх для розгортання у виробниче середовище:

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

Якщо ви запускаєте сервер розробки в Sail на WSL2, вам можуть знадобитися деякі додаткові параметри конфігурації.

Робота з JavaScript

Псевдоніми (Aliases)

За замовчуванням, плагін 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',
        },
    },
});

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: {
                    // Плагін Vue переписуватиме URL-адреси ресурсів, коли вони використовуються
                    // у однокомпонентних файлах (Single File Components), щоб вони вказували 
                    // на вебсервер Laravel. Встановлення цього значення в `null` дозволяє
                    // плагіну Laravel натомість переписувати URL-адреси ресурсів так,
                    // щоб вони вказували на сервер Vite.
                    base: null,
 
                    // Плагін Vue буде обробляти абсолютні URL-адреси як абсолютні шляхи
                    // до файлів на диску. Встановлення цього значення в `false` залишить
                    // абсолютні URL-адреси без змін, щоб вони могли, як очікується,
                    // посилатися на ресурси в публічній директорії.
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

Laravel's стартові набори вже включають належну конфігурацію Laravel, Vue та Vite. Ці стартові набори пропонують найшвидший спосіб почати роботу з Laravel, Vue та Vite.

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.

Стартові комплекти Laravel вже включають належну конфігурацію Laravel, React та Vite. Ці стартові комплекти пропонують найшвидший спосіб почати роботу з Laravel, React та Vite.

Inertia

Плагін 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 з Inertia, ми рекомендуємо налаштувати попереднє завантаження ресурсів.

Laravel's стартові комплекти вже включають належну конфігурацію Laravel, Inertia та Vite. Ці стартові комплекти пропонують найшвидший спосіб почати роботу з Laravel, Inertia та Vite.

Обробка 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">

Робота зі стилями

Laravel's стартові набори вже включають належну конфігурацію Tailwind і Vite. Або, якщо ви хочете використовувати Tailwind і Laravel без використання одного з наших стартових наборів, перегляньте посібник з встановлення Tailwind для Laravel.

Усі Laravel застосунки вже містять Tailwind та належним чином налаштований файл vite.config.js. Тому вам потрібно лише запустити сервер розробки Vite або виконати команду dev компонувальника, яка запустить обидва сервери розробки Laravel та Vite:

composer run dev

CSS вашого застосунку може бути розміщено у файлі resources/css/app.css.

Робота з Blade та маршрутами

Обробка статичних ресурсів за допомогою Vite

When referencing assets in your JavaScript or CSS, Vite automatically processes and versions them. In addition, when building Blade based applications, Vite can also process and version static assets that you reference solely in Blade templates.

Однак, щоб досягти цього, вам потрібно зробити так, щоб 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') }}">

Оновлення при збереженні

Коли ваш застосунок побудований з використанням традиційного серверного рендерингу з 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 }
            }],
        }),
    ],
});

Псевдоніми (Aliases)

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

 /**
 * Ініціалізувати будь-які сервіси застосунку.
 */
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">

Попереднє завантаження ресурсів

Коли ви створюєте SPA, використовуючи функцію розділення коду Vite, необхідні ресурси завантажуються при кожній навігації сторінкою. Така поведінка може призвести до затримки відображення інтерфейсу користувача. Якщо це є проблемою для вашого обраного фронтенд-фреймворку, Laravel пропонує можливість завчасно завантажувати JavaScript та CSS ресурси вашого застосунку при початковому завантаженні сторінки.

Ви можете вказати Laravel заздалегідь завантажити ваші ресурси, викликавши метод Vite::prefetch у методі boot в сервіс-провайдері:

 <?php
 
namespace App\Providers;
 
use Illuminate\Support\Facades\Vite;
use Illuminate\Support\ServiceProvider;
 
class AppServiceProvider extends ServiceProvider
{
    /**
     * Зареєструвати будь-які сервіси застосунку.
     */
    public function register(): void
    {
        // ...
    }
 
    /**
     * Ініціалізувати будь-які сервіси застосунку.
     */
    public function boot(): void
    {
        Vite::prefetch(concurrency: 3);
    }
}

У наведеному вище прикладі, ресурси будуть попередньо завантажені з максимальною кількістю 3 одночасних завантажень при кожному завантаженні сторінки. Ви можете змінити кількість одночасних завантажень відповідно до потреб вашого застосунку або вказати відсутність обмеження на кількість одночасних завантажень, якщо застосунок повинен завантажити всі ресурси одразу:

 /**
 * Ініціалізувати будь-які сервіси застосунку.
 */
public function boot(): void
{
    Vite::prefetch();
}

За замовчуванням, попереднє завантаження почнеться, коли відбудеться подія завантаження сторінки. Якщо ви хочете налаштувати, коли почнеться попереднє завантаження, ви можете вказати подію, на яку Vite буде слухати:

 /**
 * Ініціалізувати будь-які сервіси застосунку.
 */
public function boot(): void
{
    Vite::prefetch(event: 'vite:prefetch');
}

З огляду на наведений вище код, попереднє завантаження тепер почнеться, коли ви вручну викличете подію vite:prefetch на об'єкті window. Наприклад, ви можете почати попереднє завантаження через три секунди після завантаження сторінки:

<script>
    addEventListener('load', () => setTimeout(() => {
        dispatchEvent(new Event('vite:prefetch'))
    }, 3000))
</script>

Користувацькі базові URL-адреси

Якщо ваші скомпільовані Vite ресурси розгорнуті на домені, відмінному від вашого застосунку, наприклад, через CDN, ви повинні вказати змінну середовища ASSET_URL у файлі .env вашого застосунку:

ASSET_URL=https://cdn.example.com

Після налаштування URL-адреси ресурсів усі переписані URL-адреси до ваших ресурсів матимуть префікс із вказаним значенням:

https://cdn.example.com/build/assets/app.9dce8d17.js

Пам'ятайте, що абсолютні URL-адреси не переписуються Vite, тому вони не будуть мати префікс.

Змінні середовища

Ви можете впровадити змінні середовища у ваш JavaScript, додавши префікс VITE_ у файлі .env вашого застосунку:

VITE_SENTRY_DSN_PUBLIC=http://example.com

Ви можете отримати доступ до впроваджених змінних середовища через об'єкт import.meta.env:

import.meta.env.VITE_SENTRY_DSN_PUBLIC

Вимкнення Vite у тестах

Інтеграція Vite у Laravel спробує вирішити ваші ресурси під час запуску тестів, що вимагає від вас або запуску сервера розробки Vite, або збірки ваших ресурсів.

Якщо ви віддаєте перевагу імітувати Vite під час тестування, ви можете викликати метод withoutVite, який доступний для будь-яких тестів, що розширюють клас TestCase Laravel:

test('without vite example', function () {
    $this->withoutVite();
 
    // ...
});

use Tests\TestCase;
 
class ExampleTest extends TestCase
{
    public function test_without_vite_example(): void
    {
        $this->withoutVite();
 
        // ...
    }
}

Якщо ви хочете вимкнути Vite для всіх тестів, ви можете викликати метод withoutVite з методу setUp у вашому базовому класі TestCase:

<?php
 
namespace Tests;
 
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
 
abstract class TestCase extends BaseTestCase
{
    protected function setUp(): void
    {
        parent::setUp();
 
        $this->withoutVite();
    }
}

Серверний рендеринг (SSR)

Плагін Laravel Vite робить налаштування серверного рендерингу з Vite безболісним. Щоб почати, створіть точку входу SSR у resources/js/ssr.js і вкажіть точку входу, передавши параметр конфігурації до плагіна Laravel:

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

Щоб переконатися, що ви не забудете перебудувати точку входу SSR, ми рекомендуємо доповнити скрипт "build" у вашому package.json вашого застосунку для створення вашої збірки SSR:

"scripts": {
     "dev": "vite",
     "build": "vite build" 
     "build": "vite build && vite build --ssr" 
}

Потім, щоб зібрати та запустити SSR сервер, ви можете виконати наступні команди:

npm run build
node bootstrap/ssr/ssr.js

Якщо ви використовуєте SSR з Inertia, ви можете натомість використовувати команду Artisan inertia:start-ssr для запуску SSR сервера:

php artisan inertia:start-ssr

Laravel's стартові набори вже включають належну конфігурацію Laravel, Inertia SSR та Vite. Ці стартові набори пропонують найшвидший спосіб почати роботу з Laravel, Inertia SSR та Vite.

Атрибути тегів Script і Style

Політика Безпеки Вмісту (CSP) Nonce

Якщо ви бажаєте включити атрибут nonce у ваші теги script та style як частину вашої Політики Безпеки Вмісту, ви можете згенерувати або вказати nonce, використовуючи метод useCspNonce у межах власного middleware:

 <?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Vite;
use Symfony\Component\HttpFoundation\Response;
 
class AddContentSecurityPolicyHeaders
{
    /**
     * Обробка вхідного запиту.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        Vite::useCspNonce();
 
        return $next($request)->withHeaders([
            'Content-Security-Policy' => "script-src 'nonce-".Vite::cspNonce()."'",
        ]);
    }
}

Після виклику методу useCspNonce, Laravel автоматично додасть атрибути nonce до всіх згенерованих тегів script і style.

Якщо вам потрібно вказати nonce в іншому місці, включаючи Ziggy @route директиву, що входить до складу стартових наборів Laravel, ви можете отримати його за допомогою методу cspNonce:

@routes(nonce: Vite::cspNonce())

Якщо у вас вже є nonce, який ви хочете вказати Laravel використовувати, ви можете передати nonce методу useCspNonce:

Vite::useCspNonce($nonce);

Subresource Integrity (SRI) (Цілісність Підресурсів)

Якщо ваш маніфест Vite включає хеші integrity для ваших ресурсів, Laravel автоматично додасть атрибут integrity до будь-яких тегів скриптів і стилів, які він генерує, щоб забезпечити Цілісність Підресурсів. За замовчуванням, Vite не включає хеш integrity у свій маніфест, але ви можете увімкнути його, встановивши плагін NPM vite-plugin-manifest-sri:

npm install --save-dev vite-plugin-manifest-sri

Ви можете увімкнути цей плагін у вашому файлі vite.config.js:

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

Якщо потрібно, ви також можете налаштувати ключ маніфесту, де можна знайти хеш цілісності:

use Illuminate\Support\Facades\Vite;
 
Vite::useIntegrityKey('custom-integrity-key');

Якщо ви хочете повністю вимкнути це автоматичне виявлення, ви можете передати false методу useIntegrityKey:

Vite::useIntegrityKey(false);

Довільні атрибути

Якщо вам потрібно включити додаткові атрибути у ваші теги script і style, такі як атрибут data-turbo-track, ви можете вказати їх за допомогою методів useScriptTagAttributes і useStyleTagAttributes. Зазвичай ці методи слід викликати з Сервіс-провайдера:

 use Illuminate\Support\Facades\Vite;
 
Vite::useScriptTagAttributes([
    'data-turbo-track' => 'reload', // Вказати значення для атрибута...
    'async' => true, // Вказати атрибут без значення...
    'integrity' => false, // Виключити атрибут, який інакше був би включений...
]);
 
Vite::useStyleTagAttributes([
    'data-turbo-track' => 'reload',
]);

Якщо вам потрібно умовно додати атрибути, ви можете передати зворотний виклик, який отримає шлях до джерела активу, його URL, його фрагмент маніфесту та весь маніфест:

use Illuminate\Support\Facades\Vite;
 
Vite::useScriptTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $src === 'resources/js/app.js' ? 'reload' : false,
]);
 
Vite::useStyleTagAttributes(fn (string $src, string $url, array|null $chunk, array|null $manifest) => [
    'data-turbo-track' => $chunk && $chunk['isEntry'] ? 'reload' : false,
]);

Аргументи $chunk та $manifest будуть null, поки працює сервер розробки Vite.

Розширене налаштування

З коробки, плагін Vite для Laravel використовує розумні конвенції, які повинні працювати для більшості застосунків; однак, іноді вам може знадобитися налаштувати поведінку Vite. Щоб увімкнути додаткові параметри налаштування, ми пропонуємо наступні методи та опції, які можна використовувати замість директиви @vite Blade:

 <!doctype html>
<head>
    {{-- ... --}}
 
    {{
        Vite::useHotFile(storage_path('vite.hot')) // Налаштувати файл "hot"...
            ->useBuildDirectory('bundle') // Налаштувати директорію збірки...
            ->useManifestFilename('assets.json') // Налаштувати ім’я файлу маніфесту...
            ->withEntryPoints(['resources/js/app.js']) // Вказати точки входу...
            ->createAssetPathsUsing(function (string $path, ?bool $secure) { // Налаштувати генерацію шляхів на бекенді для зібраних ресурсів...
                return "https://cdn.example.com/{$path}";
            })
    }}
</head>

У файлі vite.config.js вам слід вказати ту саму конфігурацію:

 import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            hotFile: 'storage/vite.hot', // Налаштувати файл "hot"...
            buildDirectory: 'bundle', // Налаштувати директорію збірки...
            input: ['resources/js/app.js'], // Вказати точки входу...
        }),
    ],
    build: {
      manifest: 'assets.json', // Налаштувати ім’я файлу маніфесту...
    },
});

Спільне використання ресурсів з різних джерел на сервері розробки (CORS)

Якщо ви стикаєтеся з проблемами Cross-Origin Resource Sharing (CORS) у браузері під час отримання ресурсів з Vite dev server, можливо, вам потрібно надати вашому власному джерелу доступ до dev server. Vite у поєднанні з Laravel плагіном дозволяє наступні джерела без будь-якої додаткової конфігурації:

::1
127.0.0.1
localhost
*.test
*.localhost
APP_URL in the project's .env

Найпростіший спосіб дозволити користувацьке джерело для вашого проекту - це переконатися, що змінна середовища APP_URL вашого застосунку відповідає джерелу, яке ви відвідуєте у вашому браузері. Наприклад, якщо ви відвідуєте https://my-app.laravel, вам слід оновити ваш .env для відповідності:

APP_URL=https://my-app.laravel

Якщо вам потрібен більш детальний контроль над джерелами, наприклад, підтримка декількох джерел, ви повинні скористатися всеосяжною та гнучкою вбудованою конфігурацією сервера CORS від Vite. Наприклад, ви можете вказати декілька джерел у параметрі конфігурації server.cors.origin у файлі vite.config.js проекту:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            refresh: true,
        }),
    ],
    server: {  
        cors: {  
            origin: [  
                'https://backend.laravel',  
                'http://admin.laravel:8566',  
            ],  
        },  
    },  
});

Ви також можете включити шаблони regex, які можуть бути корисними, якщо ви хочете дозволити всі джерела для даного домену верхнього рівня, наприклад, *.laravel:

 import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            refresh: true,
        }),
    ],
    server: {  
        cors: {  
            origin: [ 
                // Підтримується: SCHEME://DOMAIN.laravel[:PORT] 
                /^https?:\/\/.*\.laravel(:\d+)?$/, 
            ], 
        }, 
    }, 
});

Коригування URL-адрес серверу розробки

Деякі плагіни в екосистемі Vite припускають, що URL-адреси, які починаються зі слеша, завжди вказуватимуть на dev-сервер Vite. Однак, через особливості інтеграції з Laravel, це не так.

Наприклад, плагін vite-imagetools генерує URL-адреси, як показано нижче, коли Vite обслуговує ваші ресурси:

<img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

Плагін vite-imagetools очікує, що вихідний URL буде перехоплений Vite, і плагін може обробляти всі URL, які починаються з /@imagetools. Якщо ви використовуєте плагіни, які очікують таку поведінку, вам потрібно буде вручну виправити URL. Ви можете зробити це у вашому файлі vite.config.js, використовуючи опцію transformOnServe.

У цьому конкретному прикладі ми додамо URL-адресу dev-сервера до всіх випадків /@imagetools у згенерованому коді:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { imagetools } from 'vite-imagetools';
 
export default defineConfig({
    plugins: [
        laravel({
            // ...
            transformOnServe: (code, devServerUrl) => code.replaceAll('/@imagetools', devServerUrl+'/@imagetools'),
        }),
        imagetools(),
    ],
});

Тепер, коли Vite обслуговує активи, він буде виводити URL-адреси, які вказують на dev-сервер Vite:

- <img src="/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">
+ <img src="http://[::1]:5173/@imagetools/f0b2f404b13f052c604e632f2fb60381bf61a520">

Вступ
Встановлення & Налаштування
Запуск Vite
Робота з JavaScript
Робота зі стилями
Робота з Blade та маршрутами
Попереднє завантаження ресурсів
Спеціальні базові URL-адреси
Змінні середовища
Вимкнення Vite у тестах
Рендеринг на стороні сервера (SSR)
Атрибути тегів Script і Style
Розширене налаштування
- Спільне використання ресурсів з різних джерел на сервері розробки (CORS)
- Коригування URL-адрес серверу розробки

	<!doctype html>
	<head>
	{{-- Заданий шлях збірки є відносним до публічного шляху. --}}

	@vite('resources/js/app.js', 'vendor/courier/build')
	</head>

	# Запустити сервер розробки Vite...
	npm run dev

	# Зібрати й версіонувати ресурси для продакшену...
	npm run build

	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: {
	// Плагін Vue переписуватиме URL-адреси ресурсів, коли вони використовуються
	// у однокомпонентних файлах (Single File Components), щоб вони вказували
	// на вебсервер Laravel. Встановлення цього значення в `null` дозволяє
	// плагіну Laravel натомість переписувати URL-адреси ресурсів так,
	// щоб вони вказували на сервер Vite.
	base: null,

	// Плагін Vue буде обробляти абсолютні URL-адреси як абсолютні шляхи
	// до файлів на диску. Встановлення цього значення в `false` залишить
	// абсолютні URL-адреси без змін, щоб вони могли, як очікується,
	// посилатися на ресурси в публічній директорії.
	includeAbsolute: false,
	},
	},
	}),
	],
	});

	<!-- Цей ресурс не обробляється Vite і не буде включений до збірки -->
	<img src="/taylor.png">

	<!-- Цей ресурс буде переписаний, версійований і включений до збірки за допомогою Vite -->
	<img src="../../images/abigail.png">

	/**
	* Ініціалізувати будь-які сервіси застосунку.
	*/
	public function boot(): void
	{
	Vite::macro('image', fn (string $asset) => $this->asset("resources/images/{$asset}"));
	}

	<?php

	namespace App\Providers;

	use Illuminate\Support\Facades\Vite;
	use Illuminate\Support\ServiceProvider;

	class AppServiceProvider extends ServiceProvider
	{
	/**
	* Зареєструвати будь-які сервіси застосунку.
	*/
	public function register(): void
	{
	// ...
	}

	/**
	* Ініціалізувати будь-які сервіси застосунку.
	*/
	public function boot(): void
	{
	Vite::prefetch(concurrency: 3);
	}
	}

	/**
	* Ініціалізувати будь-які сервіси застосунку.
	*/
	public function boot(): void
	{
	Vite::prefetch();
	}

	/**
	* Ініціалізувати будь-які сервіси застосунку.
	*/
	public function boot(): void
	{
	Vite::prefetch(event: 'vite:prefetch');
	}

	<?php

	namespace App\Http\Middleware;

	use Closure;
	use Illuminate\Http\Request;
	use Illuminate\Support\Facades\Vite;
	use Symfony\Component\HttpFoundation\Response;

	class AddContentSecurityPolicyHeaders
	{
	/**
	* Обробка вхідного запиту.
	*
	* @param \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response) $next
	*/
	public function handle(Request $request, Closure $next): Response
	{
	Vite::useCspNonce();

	return $next($request)->withHeaders([
	'Content-Security-Policy' => "script-src 'nonce-".Vite::cspNonce()."'",
	]);
	}
	}

	use Illuminate\Support\Facades\Vite;

	Vite::useScriptTagAttributes([
	'data-turbo-track' => 'reload', // Вказати значення для атрибута...
	'async' => true, // Вказати атрибут без значення...
	'integrity' => false, // Виключити атрибут, який інакше був би включений...
	]);

	Vite::useStyleTagAttributes([
	'data-turbo-track' => 'reload',
	]);

	<!doctype html>
	<head>
	{{-- ... --}}

	{{
	Vite::useHotFile(storage_path('vite.hot')) // Налаштувати файл "hot"...
	->useBuildDirectory('bundle') // Налаштувати директорію збірки...
	->useManifestFilename('assets.json') // Налаштувати ім’я файлу маніфесту...
	->withEntryPoints(['resources/js/app.js']) // Вказати точки входу...
	->createAssetPathsUsing(function (string $path, ?bool $secure) { // Налаштувати генерацію шляхів на бекенді для зібраних ресурсів...
	return "https://cdn.example.com/{$path}";
	})
	}}
	</head>