1.2. Установка

Livewire — это пакет для Laravel, поэтому перед установкой и использованием Livewire вам нужно иметь запущенное Laravel-приложение. Если вам нужна помощь в настройке нового Laravel-приложения, пожалуйста, ознакомьтесь с официальной документацией Laravel.

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

composer require livewire/livewire

Вот и всё — правда. Если вы хотите больше вариантов настройки, продолжайте читать. В противном случае вы можете сразу перейти к использованию Livewire.

/livewire/livewire.js возвращает код состояния 404

По умолчанию Livewire предоставляет маршрут в вашем приложении для обслуживания своих JavaScript-ресурсов: /livewire/livewire.js. Это подходит для большинства приложений, однако, если вы используете Nginx с пользовательской конфигурацией, вы можете получить 404 от этой конечной точки. Чтобы исправить эту проблему, вы можете либо скомпилировать JavaScript-ресурсы Livewire самостоятельно, либо настроить Nginx для их обработки.

1. Публикация файла конфигурации

Livewire не требует настройки ("zero-config"), что означает, что вы можете использовать его, следуя соглашениям, без дополнительной конфигурации. Однако, если это необходимо, вы можете опубликовать и настроить файл конфигурации Livewire, выполнив следующую Artisan-команду:

php artisan livewire:publish --config

Это создаст новый файл livewire.php в каталоге config вашего Laravel-приложения.

2. Ручное подключение фронтенд-ресурсов Livewire

По умолчанию Livewire автоматически подключает JavaScript и CSS-ресурсы, необходимые для работы, на каждую страницу, содержащую Livewire-компонент.

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

<html>
<head>
    ...
    @livewireStyles
</head>
<body>
    ...
    @livewireScripts
</body>
</html>

Подключая эти ресурсы вручную на странице, вы даёте Livewire понять, что не нужно автоматически добавлять их.

AlpineJS идет в комплекте с Livewire

Поскольку Alpine включён в JavaScript-ресурсы Livewire, вы должны добавлять @livewireScripts на каждой странице, где вы хотите использовать Alpine, даже если на этой странице не используется Livewire.

Хотя это требуется редко, вы можете отключить автоматическое подключение ресурсов Livewire, обновив параметр inject_assets в файле конфигурации вашего приложения config/livewire.php:

'inject_assets' => false,

Если вы предпочитаете заставить Livewire подключать свои ресурсы на одной или нескольких страницах, вы можете вызвать следующий глобальный метод из текущего маршрута или сервис-провайдера.

\Livewire\Livewire::forceAssetInjection();

3. Настройка эндпоинта для обновления Livewire

Каждое обновление в компоненте Livewire отправляет сетевой запрос на сервер по следующему эндпоинту: https://example.com/livewire/update

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

В таких случаях вы можете зарегистрировать собственный эндпоинт любым удобным вам способом, и, если вы сделаете это внутри Livewire::setUpdateRoute(), Livewire будет использовать этот эндпоинт для всех обновлений компонентов:

Livewire::setUpdateRoute(function ($handle) {
    return Route::post('/custom/livewire/update', $handle);
});

Теперь вместо использования /livewire/update Livewire будет отправлять обновления компонентов на /custom/livewire/update.

Поскольку Livewire позволяет вам зарегистрировать собственный маршрут для обновлений, вы можете указать любое дополнительное middleware, которое вы хотите использовать с Livewire, непосредственно внутри setUpdateRoute():

Livewire::setUpdateRoute(function ($handle) {
    return Route::post('/custom/livewire/update', $handle)
        ->middleware([...]); 
});

4. Настройка URL-адреса ресурсов

По умолчанию Livewire обслуживает свои JavaScript-ресурсы по следующему URL-адресу: https://example.com/livewire/livewire.js. Кроме того, Livewire ссылается на этот ресурс с помощью тега script следующим образом:

<script src="/livewire/livewire.js" ...

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

Чтобы использовать собственный эндпоинт для JavaScript-ресурсов, вы можете зарегистрировать свой маршрут внутри Livewire::setScriptRoute():

Livewire::setScriptRoute(function ($handle) {
    return Route::get('/custom/livewire/livewire.js', $handle);
});

Теперь Livewire будет загружать свой JavaScript следующим образом:

<script src="/custom/livewire/livewire.js" ...

5. Ручная сборка Livewire и Alpine

По умолчанию Alpine и Livewire загружаются с использованием тега <script src="livewire.js">, что означает отсутствие контроля над порядком загрузки этих библиотек. Как следствие, импорт и регистрация плагинов Alpine, как показано в примере ниже, больше не будут работать:

// Предупреждение: Этот пример демонстрирует, как делать НЕ нужно...
 
import Alpine from 'alpinejs'
import Clipboard from '@ryangjchandler/alpine-clipboard'
 
Alpine.plugin(Clipboard)
Alpine.start()

Чтобы решить эту проблему, нам нужно сообщить Livewire, что мы хотим самостоятельно использовать версию ESM (ECMAScript module) и предотвратить вставку тега скрипта livewire.js. Для этого мы должны добавить директиву @livewireScriptConfig в файл макета (resources/views/components/layouts/app.blade.php):

<html>
<head>
    <!-- ... -->
    @livewireStyles
    @vite(['resources/js/app.js'])
</head>
<body>
    {{ $slot }}
 
    @livewireScriptConfig 
</body>
</html>

Когда Livewire обнаруживает директиву @livewireScriptConfig, он перестаёт автоматически подключать скрипты Livewire и Alpine. Если вы используете директиву @livewireScripts для ручной загрузки Livewire, обязательно удалите её. Убедитесь, что директива @livewireStyles добавлена, если она ещё не присутствует.

Заключительный шаг — это импорт Alpine и Livewire в наш файл app.js, что позволит нам зарегистрировать любые пользовательские ресурсы и, в конечном итоге, запустить Livewire и Alpine:

import { Livewire, Alpine } from '../../vendor/livewire/livewire/dist/livewire.esm';
import Clipboard from '@ryangjchandler/alpine-clipboard'
 
Alpine.plugin(Clipboard)
 
Livewire.start()
Пересоберите ваши ресурсы после выполнения composer update

Если вы вручную собираете Livewire и Alpine, убедитесь, что вы пересобираете ресурсы после каждого выполнения команды composer update.

Несовместимо с Laravel Mix

Laravel Mix не будет работать, если вы вручную собираете Livewire и AlpineJS. Вместо этого мы рекомендуем вам перейти на Vite.

6. Публикация фронтенд-ресурсов Livewire

Публикация ресурсов не является обязательной

Публикация ресурсов Livewire не является обязательной для его работы. Делайте это только в случае особой необходимости.

Если вы предпочитаете, чтобы JavaScript-ресурсы обслуживались вашим веб-сервером, а не через Laravel, используйте команду livewire:publish:

php artisan livewire:publish --assets

Чтобы поддерживать ресурсы в актуальном состоянии и избегать проблем при будущих обновлениях, мы настоятельно рекомендуем добавить следующую команду в ваш файл composer.json:

{
    "scripts": {
        "post-update-cmd": [
            // Другие скрипты
            "@php artisan vendor:publish --tag=livewire:assets --ansi --force"
        ]
    }
}