Overview
Masalah yang diselesaikan. Aset frontend (CSS, JavaScript, gambar, font) harus dikompilasi, diberi versi agar cache browser tidak membandel, dan dimuat dengan benar di Blade. Pemula sering mentok pada Vite manifest not found, gaya Tailwind yang tidak muncul, atau bingung memilih antara Tailwind dan Bootstrap, serta kapan menjalankan npm run dev dan npm run build.
Hasil akhir:
Memahami peran Vite dan
laravel-vite-plugin.Proyek yang memakai Tailwind CSS (bawaan skeleton) atau Bootstrap 5 dengan benar.
Alur kerja pengembangan (HMR) dan build produksi.
Cara memuat gambar, font, dan JavaScript tambahan lewat Vite.
Prerequisites
Komponen | Kebutuhan |
|---|---|
PHP | 8.3+ (Laravel 13) atau 8.2+ (Laravel 12) |
Laravel | 12.x atau 13.x (sudah menyertakan Vite) |
Node.js | LTS terbaru (di Laragon 8.x tersedia Node.js 22 LTS) |
npm | Terpasang bersama Node.js |
Proyek | Proyek Laravel yang berjalan |
Periksa:
node -v
npm -v
Step-by-Step Tutorial
1. Cara Kerja Vite di Laravel
resources/css/app.css ┐
resources/js/app.js ┘──► Vite ──┬── mode dev: server HMR (hot reload), tanpa berkas build
└── mode build: public/build/ (berkas minify + manifest.json)
Blade: @vite(['resources/css/app.css', 'resources/js/app.js'])
└── dev: memuat dari server Vite (lewat berkas public/hot)
└── build: membaca public/build/manifest.json lalu memuat berkas ber-hash
Perintah yang dipakai (di package.json):
"scripts": {
"dev": "vite",
"build": "vite build"
}
Perintah | Kapan dipakai |
|---|---|
| Sekali setelah clone proyek, atau setelah menambah paket |
| Saat mengembangkan. Biarkan berjalan, perubahan langsung terlihat |
| Sebelum deploy atau untuk menguji tampilan produksi |
2. Pasang Dependensi dan Jalankan
cd C:\laragon\www\toko
npm install
npm run dev
VITE v7.x.x ready in 520 ms
➜ Local: http://localhost:5173/
➜ press h + enter to show help
LARAVEL v13.x.x plugin v2.x.x
➜ APP_URL: http://toko.test
Angka versi pada mesin Anda dapat berbeda. Biarkan jendela terminal ini terbuka.
3. Struktur Berkas Bawaan
vite.config.js
package.json
resources/
├── css/app.css
└── js/
├── app.js
└── bootstrap.js ← (bila ada) inisialisasi axios dll.
public/
├── build/ ← hasil build (jangan di-commit)
└── hot ← penanda server dev aktif (otomatis, jangan di-commit)
vite.config.js bawaan:
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.js'],
refresh: true,
}),
tailwindcss(),
],
});
Opsi refresh: true membuat browser memuat ulang otomatis saat Anda mengubah berkas Blade.
4. Memuat Aset di Blade
<!DOCTYPE html>
<html lang="id">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>@yield('title', config('app.name'))</title>
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
@yield('content')
</body>
</html>
Direktif @vite otomatis memilih mode dev atau build.
Opsi A: Tailwind CSS
Skeleton Laravel terbaru sudah menyertakan Tailwind CSS memakai plugin Vite resmi (@tailwindcss/vite), sehingga biasanya tidak ada yang perlu dipasang.
A1. Verifikasi Setup
resources/css/app.css:
@import 'tailwindcss';
@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';
@source '../../storage/framework/views/*.php';
@source '../**/*.blade.php';
@source '../**/*.js';
@theme {
--font-sans: 'Instrument Sans', ui-sans-serif, system-ui, sans-serif;
}
Direktif @source memberi tahu Tailwind di mana mencari nama kelas. Isi persisnya bisa sedikit berbeda antar versi skeleton, jadi ikuti berkas bawaan proyek Anda.
A2. Pasang Manual pada Proyek yang Belum Memilikinya
npm install tailwindcss @tailwindcss/vite
Tambahkan plugin ke vite.config.js (seperti contoh di atas), lalu buat resources/css/app.css berisi @import 'tailwindcss';.
A3. Coba di Halaman
<div class="mx-auto max-w-md rounded-xl bg-white p-6 shadow">
<h1 class="text-xl font-semibold text-slate-800">Halo Tailwind</h1>
<p class="mt-2 text-slate-600">Gaya ini dihasilkan oleh Vite.</p>
<button class="mt-4 rounded bg-indigo-600 px-4 py-2 text-white hover:bg-indigo-500">
Simpan
</button>
</div>
A4. Kustomisasi Tema (Tailwind 4)
Kustomisasi dilakukan di CSS lewat @theme, bukan lagi tailwind.config.js:
@theme {
--color-brand-500: #0ea5a4;
--color-brand-600: #0d8f8e;
--font-display: 'Poppins', sans-serif;
}
<button class="bg-brand-500 hover:bg-brand-600 text-white">Beli</button>
Jika proyek Anda memakai Tailwind versi 3 (dengan tailwind.config.js dan postcss.config.js), tetap berjalan, tetapi konfigurasinya berbeda. Ikuti dokumentasi sesuai versi yang terpasang di package.json.
Opsi B: Bootstrap 5
Jika Anda memilih Bootstrap, lepaskan Tailwind agar tidak bentrok.
B1. Lepas Tailwind (bila bawaan)
npm uninstall tailwindcss @tailwindcss/vite
Hapus baris import tailwindcss ... dan tailwindcss() dari 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,
}),
],
});
B2. Pasang Bootstrap dan Sass
npm install bootstrap @popperjs/core
npm install --save-dev sass
B3. Buat Berkas SCSS
mkdir resources\sass
New-Item resources\sass\app.scss
resources/sass/app.scss:
// kustomisasi variabel SEBELUM impor Bootstrap
$primary: #0ea5a4;
$font-family-sans-serif: 'Poppins', system-ui, -apple-system, sans-serif;
$border-radius: .5rem;
@import 'bootstrap/scss/bootstrap';
Versi Sass terbaru mencetak peringatan deprecation terkait @import. Itu hanya peringatan dan tidak menghentikan build. Untuk meredamnya sementara, tambahkan di vite.config.js:
css: {
preprocessorOptions: {
scss: {
quietDeps: true,
silenceDeprecations: ['import', 'global-builtin', 'color-functions', 'mixed-decls'],
},
},
},
B4. Impor JavaScript Bootstrap
resources/js/app.js:
import * as bootstrap from 'bootstrap';
// jadikan tersedia secara global bila dibutuhkan (mis. untuk skrip inline)
window.bootstrap = bootstrap;
document.querySelectorAll('[data-bs-toggle="tooltip"]').forEach(el => new bootstrap.Tooltip(el));
B5. Ubah Direktif @vite
@vite(['resources/sass/app.scss', 'resources/js/app.js'])
B6. Alternatif Sederhana (Tanpa Kustomisasi Variabel)
Cukup impor CSS jadi dari paket di app.js, tanpa Sass:
import 'bootstrap/dist/css/bootstrap.min.css';
import * as bootstrap from 'bootstrap';
window.bootstrap = bootstrap;
@vite(['resources/js/app.js'])
B7. Coba di Halaman
<div class="container py-5">
<div class="card shadow-sm">
<div class="card-body">
<h1 class="h4">Halo Bootstrap</h1>
<button class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#demo">Buka Modal</button>
</div>
</div>
</div>
<div class="modal fade" id="demo" tabindex="-1">
<div class="modal-dialog"><div class="modal-content p-4">Modal berjalan.</div></div>
</div>
Aset Lain Lewat Vite
Gambar dan Font
Letakkan di resources/ agar diberi versi (hash) otomatis:
resources/images/logo.png
resources/fonts/poppins.woff2
<img src="{{ Vite::asset('resources/images/logo.png') }}" alt="Logo">
Untuk gambar statis yang tidak butuh versi, taruh di public/ dan panggil dengan asset('images/logo.png').
Pustaka JavaScript Tambahan
npm install alpinejs chart.js
// resources/js/app.js
import Alpine from 'alpinejs';
import Chart from 'chart.js/auto';
window.Alpine = Alpine;
window.Chart = Chart;
Alpine.start();
Beberapa Titik Masuk (Halaman Khusus)
// vite.config.js
laravel({
input: [
'resources/css/app.css',
'resources/js/app.js',
'resources/js/admin.js', // dimuat hanya di layout admin
],
refresh: true,
}),
@vite(['resources/css/app.css', 'resources/js/admin.js'])
Build untuk Produksi
npm run build
vite v7.x.x building for production...
✓ 54 modules transformed.
public/build/manifest.json 0.33 kB
public/build/assets/app-4ed993c7.css 38.12 kB │ gzip: 7.40 kB
public/build/assets/app-a1b2c3d4.js 82.55 kB │ gzip: 30.18 kB
✓ built in 1.84s
Dua pilihan strategi deploy:
Strategi | Cara | Keterangan |
|---|---|---|
Build di server |
| Butuh Node.js di server |
Build di CI, kirim hasilnya | Build di GitHub Actions, unggah | Server tidak perlu Node.js (disarankan) |
Contoh langkah build di CI:
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run build
Troubleshooting
Gejala | Penyebab | Solusi |
|---|---|---|
| Belum build dan server dev tidak berjalan | Jalankan |
Halaman tanpa gaya setelah deploy |
| Build di server/CI, pastikan folder terunggah |
Gaya Tailwind tidak muncul |
| Periksa |
Kelas Tailwind dinamis tidak berfungsi ( | Tailwind tidak bisa memindai nama kelas hasil rangkaian string | Tulis nama kelas lengkap di kode |
Perubahan tidak terlihat di browser |
| Jalankan ulang dev server; hapus |
| Kebijakan eksekusi PowerShell |
|
|
| Hapus |
| Antivirus atau proses yang mengunci berkas | Tutup |
| Bootstrap belum terpasang |
|
Bootstrap modal/dropdown tidak berfungsi | JS Bootstrap belum diimpor |
|
Gaya Tailwind dan Bootstrap bertabrakan | Keduanya dimuat | Pilih salah satu, atau pakai awalan/pisahkan halaman |
HMR gagal dengan domain | Mixed content atau host berbeda | Atur |
| Berkas tidak terdaftar di | Tambahkan ke |
Build gagal di server karena memori | RAM kecil | Build di CI, atau tambah swap sementara |
Perintah diagnosis:
npm ls vite laravel-vite-plugin
npm run build -- --debug
Best Practices
Keamanan
Jalankan
npm auditsecara berkala, dan perbarui dependensi yang rentan.Jangan memuat skrip dari CDN pihak ketiga tanpa
integrity. Lebih baik dibundel lewat Vite agar bisa memakai Content Security Policy yang ketat.Jangan memasukkan rahasia ke berkas frontend. Variabel
VITE_*akan terlihat publik di browser.
Performa
Selalu deploy hasil
npm run build, jangan pernah server dev.Impor hanya yang diperlukan:
import Chart from 'chart.js/auto'memuat semuanya, sedangkan impor modul tertentu lebih hemat.Gunakan impor dinamis untuk kode yang jarang dipakai:
const { default: Chart } = await import('chart.js/auto');
Gunakan format gambar modern (WebP/AVIF) dan
loading="lazy".Tailwind secara otomatis membuang kelas yang tidak dipakai saat build.
Maintainability
Pilih satu kerangka CSS per proyek (Tailwind atau Bootstrap).
Jangan commit
public/build,public/hot, dannode_modules(sudah bawaan.gitignore).Commit
package-lock.jsonagar versi paket konsisten, dan pakainpm cidi CI.Dokumentasikan versi Node.js (
.nvmrcatau kolomenginesdipackage.json).Pisahkan titik masuk berat (admin, grafik) dari halaman publik.
Related Articles
Cara Mengelola Dependency Laravel Menggunakan Composer dan NPM dengan Benar
Panduan Lengkap Instalasi Laravel di Windows Menggunakan Laragon
Admin Dashboard Laravel dengan Bootstrap 5 dan DataTables AJAX
Last Tested
Catatan jujur: disusun dari dokumentasi Laravel, Vite, Tailwind CSS 4, dan Bootstrap 5.3, tetapi belum dijalankan ulang di proyek nyata oleh penulis. Isi
vite.config.jsdanapp.cssbawaan dapat berbeda antar versi skeleton. Selalu ikuti berkas di proyek Anda.
Komponen | Versi acuan penulisan | Versi saat Anda menguji |
|---|---|---|
Node.js | 22 LTS | |
npm | 10.x | |
Vite | Sesuai | |
laravel-vite-plugin | Sesuai | |
Tailwind CSS | 4.x | |
Bootstrap | 5.3.x | |
Laravel | 13.x (kompatibel dengan 12.x) | |
Tanggal uji |