Vite — чудовий інструмент, який дозволяє швидко створювати фронтенд-ресурси для вашого Laravel-додатку. Проте, як і з будь-яким іншим інструментом, на початку можуть виникнути деякі труднощі. Коли ви стикаєтеся з помилкою, це може затримати ваш прогрес, поки ви намагаєтеся зрозуміти, що пішло не так.
У цій статті я розгляну чотири типові помилки, які ви можете зустріти, використовуючи Vite з Laravel:
Сподіваюся, до кінця цієї статті ви краще зрозумієте, як виправити ці помилки та продовжити розробку свого додатку.
Для цілей цієї статті ми припустимо, що працюємо з новим додатком Laravel 11.
Типова помилка, з якою ви можете зіткнутися, — "Vite manifest не знайдено за адресою: public/build/manifest.json". Це відбувається під час завантаження сторінки, коли плагін Vite для Laravel не може знайти файл manifest, згенерований під час процесу збірки. Давайте розглянемо, що таке файл manifest і дві ймовірні ситуації, коли ця помилка може виникнути.
Якщо ви не змінювали команди у файлі package.json, що постачається з новою установкою Laravel 11, ви можете запустити одну з наведених команд, щоб зібрати свої ресурси і згенерувати файл manifest:
npm run dev — ця команда генерує ресурси для розробки.npm run build — ця команда генерує ресурси для продуктивності.Запустивши одну з цих команд, буде створено новий файл public/build/manifest.json, який виглядатиме приблизно так:
{
"resources/css/app.css": {
"file": "assets/app-rlbWHTKs.css",
"src": "resources/css/app.css",
"isEntry": true
},
"resources/js/app.js": {
"file": "assets/app-Xaw6OIO1.js",
"name": "app",
"src": "resources/js/app.js",
"isEntry": true
}
}Цей файл manifest.json зв'язує вихідні файли з CSS та JS, які обробив і зібрав Vite. Це означає, що у ваших Blade-шаблонах ви можете використовувати щось на кшталт:
@vite('resources/css/app.css')І на виході ви отримаєте наступний HTML:
<link rel="preload" as="style" href="http://example.test/build/assets/app-rlbWHTKs.css" />Отже, без файлу manifest.json інтеграція Vite з Laravel не знатиме, який зібраний файл відповідає вихідному файлу.
У більшості випадків виконання відповідного скрипта збірки (npm run dev або npm run build) створює файл manifest.json і вирішує проблему.
Якщо ви налаштували будь-які параметри Vite, можливо, плагін Vite для Laravel не може знайти файл manifest.json. Наприклад, якщо ви оновили файл vite.config.js, щоб зберігати зібрані файли у public/dist, додавши параметр buildDirectory:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.js'],
buildDirectory: 'dist',
refresh: true,
}),
],
});В цьому випадку зібрані файли зберігатимуться у public/dist, отже, файл manifest.json буде знаходитись за адресою public/dist/manifest.json. Але плагін Laravel Vite все ще шукає файл manifest.json у стандартному каталозі public/build, коли ви використовуєте директиву @vite у вашому Blade-шаблоні.
Щоб вирішити це, скористайтеся розширеними можливостями кастомізації плагіна Vite, щоб вказати місцезнаходження файлу manifest.json, замінивши директиву @vite у ваших Blade-шаблонах на:
{{ Vite::useBuildDirectory('dist')->withEntryPoints(['resources/css/app.css', 'resources/js/app.js']) }}Як видно з прикладу вище, ми використовуємо метод useBuildDirectory, щоб вказати каталог збірки. Ми також використовуємо метод withEntryPoints, щоб вказати точки входу, які раніше передавалися директиві @vite. Після цього плагін Laravel Vite зможе знайти файл manifest.json у правильному каталозі, і помилка має бути виправлена.
Ще одна поширена помилка під час використання Vite у проекті Laravel — "Не вдалося знайти файл у Vite manifest: resources/sass/app.scss". Ця помилка виникає, коли Vite не може знайти файл, вказаний у директиві @vite у ваших Blade-шаблонах.
Наприклад, ви могли б мати файл resources/sass/app.scss, який намагаєтеся включити у свій Blade-шаблон за допомогою директиви @vite:
@vite('resources/sass/app.scss')Розглянемо можливі причини та рішення цієї помилки.
По-перше, рекомендую перевірити, чи правильний шлях до файлу у Blade-шаблоні. Наприклад, ви можете використовувати @vite('resources/sass/app.scss'), тоді як файл насправді знаходиться за адресою resources/css/app.scss.
Також перевірте, чи існує вказаний файл у зазначеному місці.
Дублюйте (і навіть потрійно!) перевірте шляхи та назви файлів. Можливо, у шляху є помилка, або ви використали неправильне розширення файлу. Якщо шлях до файлу неправильний, вам потрібно його виправити, щоб вирішити помилку.
Ще одне потенційне рішення — спробувати зібрати ваші ресурси, використовуючи відповідний скрипт збірки (npm run dev або npm run build). Ви, можливо, використовуєте застарілий файл manifest, який не містить файл, що намагаєтеся включити у свій Blade-шаблон. Запуск скрипта збірки відновить новий файл manifest, який може включати файл, що ви намагаєтеся підключити, і виправить цю проблему.
Якщо ви все ще отримуєте цю помилку після перевірки наявності файлу та відновлення активів, це вказує на те, що Vite не обробив файл.
Швидкий спосіб це перевірити — подивитися на файл public/build/manifest.json і перевірити, чи вказаний файл у властивості src однієї з оброблених записів. Наприклад, якщо ми поглянемо на цей файл manifest.json, ми можемо побачити, що файл resources/sass/app.scss не вказано:
{
"resources/css/app.css": {
"file": "assets/app-rlbWHTKs.css",
"src": "resources/css/app.css",
"isEntry": true
},
"resources/js/app.js": {
"file": "assets/app-Xaw6OIO1.js",
"name": "app",
"src": "resources/js/app.js",
"isEntry": true
}
}Тоді як у цьому прикладі файл resources/sass/app.scss вказано:
{
"resources/js/app.js": {
"file": "assets/app-Xaw6OIO1.js",
"name": "app",
"src": "resources/js/app.js",
"isEntry": true
},
"resources/sass/app.scss": {
"file": "assets/app-DtFeYo_o.css",
"src": "resources/sass/app.scss",
"isEntry": true
}
}Якщо файл не вказано у manifest.json, ви хочете перевірити свій файл vite.config.js, щоб переконатися, що файл входить у процес збору. Наприклад, у цьому файлі vite.config.js ми можемо бачити, що файл resources/sass/app.scss не було включено в масив input:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.js'],
refresh: true,
}),
],
});Є багато причин, чому файл може не бути включено в процес збору. Наприклад, можливо, ви у процесі переходу з CSS на SCSS, і ви забули оновити файл vite.config.js, щоб включити шлях до нового файлу SCSS. Це те, що я забував робити багато разів!
У такому випадку ви можете оновити файл vite.config.js, щоб включити правильний шлях до файлу:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
input: ['resources/sass/app.scss', 'resources/js/app.js'],
refresh: true,
}),
],
});Запустивши свій скрипт збірки, ви тепер повинні включити файл resources/sass/app.scss у процес збору, і сподіваюся, проблема буде виправлена.
Ще одна помилка, з якою ви можете зіткнутися при використанні Vite — "Uncaught ReferenceError: $ не визначено", коли використовується jQuery. Ця помилка відбувається, коли у вашому коді JavaScript використовується змінна $, але jQuery не завантажено.
Можливо, причина цієї помилки в тому, що jQuery не було включено у ваш процес збору Vite. Перше, що потрібно перевірити — чи встановлено jQuery. Якщо ви використовуєте NPM для управління вашими JavaScript-залежностями, ви можете скористатися командою npm list, щоб дізнатися.
Наприклад, припустимо, що наш проект розташовано за адресою /Users/ashallen/www/my-laravel-app, ми можемо виконати таку команду для перевірки, чи встановлено jQuery:
npm list jqueryЯкщо jQuery встановлено, ви побачите щось на зразок цього:
my-laravel-app@ /Users/ashallen/www/my-laravel-app
└── jquery@3.7.1Якщо його не встановлено, вивід може виглядати так:
my-laravel-app@ /Users/ashallen/www/my-laravel-app
└── (empty)Якщо його не встановлено, ви можете встановити його як залежність для розробки, використовуючи наступну команду:
npm install jquery -DПісля встановлення jQuery вам потрібно буде зробити його доступним у всіх файлах, де ви хочете використовувати $. Наприклад, ви можете включити його у свій файл resources/js/app.js, якщо використовуєте його там:
import './bootstrap';
import $ from 'jquery';
// Тепер ви можете звертатися до змінної $ тут...Припустимо, у нас є файл resources/js/MyClass.js, який використовує jQuery. Ми створимо простий приклад файла чисто для демонстрації:
export default class MyClass {
init() {
$('body').on('click', function () {
console.log('Body clicked');
});
}
}Клас resources/js/MyClass.js має єдиний метод init, який прикріплює обробник подій на клік до елемента body. Коли тіло клацають, у консолі з'являється повідомлення.
Потім, у нашому файлі resources/js/app.js, імпортуємо клас resources/js/MyClass.js та викликаємо метод init:
import './bootstrap';
import $ from 'jquery';
import MyClass from "./MyClass.js";
new MyClass().init();Тепер, коли сторінка завантажується, помилка "Uncaught ReferenceError: $ не визначено" виникне, оскільки змінна $ недоступна у файлі resources/js/MyClass.js; вона доступна лише у файлі resources/js/app.js. Щоб вирішити цю помилку, у нас є два варіанти:
resources/js/MyClass.js.$ об'єкту window у файлі resources/js/app.js.Якщо ми вирішимо імпортувати jQuery у файлі resources/js/MyClass.js, можемо оновити файл таким чином:
import $ from 'jquery';
export default class MyClass {
init() {
$('body').on('click', function () {
console.log('Body clicked');
});
}
}Альтернативно, якщо ми оберемо призначити змінну $ об'єкту window у файлі resources/js/app.js, можемо оновити файл так:
import './bootstrap';
import MyClass from "./MyClass.js";
import $ from 'jquery';
// Призначення змінної $ об'єкту window
window.$ = $;
new MyClass().init();Після внесення будь-яких із цих змін помилка "Uncaught ReferenceError: $ не визначено" повинна, сподіваюся, зникнути.
Ці види помилок іноді важко помітити і виправити, особливо в продуктивних середовищах, де ви можете побачити помилку лише після розгортання вашого додатку. Саме тому я настійно рекомендую використовувати інструмент на кшталт Sentry, щоб допомогти вам відстежувати і налагоджувати ці помилки. Sentry — чудовий інструмент моніторингу помилок, який дозволяє відстежувати ваш фронтенд JavaScript-код і бекенд Laravel-код на наявність помилок та винятків. Це прекрасний спосіб отримати повну картину того, що йде не так у вашій програмі та швидше виправити помилки.
Ще одна помилка, з якою ви можете зіткнутися, запустивши команду Vite — "vite: Доступ заборонено". Ця помилка зазвичай виникає, коли ви намагаєтеся виконати команду Vite без достатніх прав доступу.
Наприклад, ви могли встановити свої залежності NPM, використовуючи sudo npm install замість npm install. Внаслідок цього директорія node_modules та її вміст могли стати власністю користувача root, а не вашого облікового запису користувача. Це означає, що необхідні файли не можуть бути доступні, коли ви намагаєтеся виконати команду Vite.
Зазвичай рішенням цієї проблеми є зміна власності директорії node_modules та її вмісту, щоб ви могли виконувати команди Vite. Один із можливих способів зробити це — рекурсивно змінити власність директорії node_modules та її вмісту на ваш обліковий запис користувача. Припустимо, що ваш обліковий запис користувача — ash-allen. Ви можете виконати наступну команду, щоб змінити власність:
sudo chown -R ash-allen ./node_modulesКоманда chown змінює власність директорії node_modules та її вмісту на обліковий запис користувача ash-allen. Ми використовуємо прапор -R для команди chown, щоб рекурсивно змінити власність директорії та вмісту. Після виконання цієї команди ви повинні мати можливість виконувати команди Vite, не стикаючись із помилкою "vite: Доступ заборонено".
У цій статті ми розглянули чотири поширені помилки, з якими ви можете зіткнутися, використовуючи Vite з Laravel:
Ми розглянули причини цих помилок і можливі рішення для кожної з них. Сподіваюся, тепер ви краще розумієте, як усунути ці помилки та знову зосередитися на розробці свого Laravel-додатку з Vite.