Vite di Laravel: Memahami Alur Aset dari Development hingga Build

Anda sudah mengubah resources/js/app.js, tetapi dari mana browser mengambil file itu? Saat npm run dev aktif, perubahan muncul selama pengembangan. Setelah menjalankan npm run build, Laravel tetap memanggil entry point yang sama meskipun file hasil build sudah memiliki nama dan lokasi berbeda.

Kebingungan biasanya muncul karena ada beberapa bagian yang bekerja bersama: konfigurasi Vite menentukan titik masuk, direktif Blade @vite menghubungkan template dengan aset, lalu mode development atau build menentukan aset mana yang dimuat. Memahami alur ini lebih berguna daripada sekadar menghafal dua perintah NPM.

Artikel ini mengikuti dokumentasi Laravel 13.x dan dokumentasi Vite yang diakses pada 28 September 2026 WITA. Sintaks dapat berubah mengikuti versi Laravel, laravel-vite-plugin, atau Vite yang dipakai proyek Anda. Contoh di bawah bersifat konseptual dan belum dijalankan pada proyek lokal.

Mulai dari entry point, bukan dari file hasil build

Entry point adalah file awal yang diserahkan kepada Vite untuk diproses. Pada aplikasi Laravel berbasis Blade, entry point yang umum adalah CSS dan JavaScript di bawah direktori resources, misalnya resources/css/app.css dan resources/js/app.js.

Laravel mendokumentasikan konfigurasi entry point di vite.config.js. Entry point tidak harus selalu berupa pasangan CSS dan JavaScript. Jika CSS diimpor dari JavaScript, proyek dapat memakai entry point JavaScript saja. Karena itu, konfigurasi proyek yang sudah dikustomisasi atau memakai starter kit perlu dibaca langsung; jangan menganggap semua aplikasi memiliki susunan identik.

Setelah entry point ditetapkan, file tersebut menjadi awal graf aset. Impor JavaScript, CSS, gambar, atau font yang terhubung dari sana dapat ikut diproses sesuai konfigurasi Vite. Ini berbeda dari memilih Blade, Livewire, Inertia, React, Vue, atau Svelte sebagai arsitektur frontend. Pilihan arsitektur dibahas terpisah; di sini fokusnya hanya jalur aset.

Peran @vite di template Blade

Direktif @vite menghubungkan template Blade dengan entry point yang sudah dikonfigurasi. Dokumentasi Laravel menjelaskan dua perilaku:

• ketika Vite development server terdeteksi, @vite menyisipkan Vite client agar alur development dan Hot Module Replacement dapat digunakan;
• dalam build mode, direktif tersebut memuat aset yang telah dikompilasi dan diberi versi, termasuk CSS yang diimpor oleh JavaScript.

Artinya, template sebaiknya menunjuk ke entry point, bukan menebak nama file hasil build. Nama hasil build dapat berubah ketika kontennya berubah. Integrasi Laravel/Vite menerjemahkan entry point ke aset yang tepat untuk mode aktif.

Development dan build menyelesaikan pekerjaan yang berbeda

Dokumentasi Laravel menyediakan dua perintah utama:

npm run dev
npm run build

npm run dev menjalankan development server Vite untuk alur pengembangan lokal. npm run build memproses, memberi versi, dan membundel aset agar siap menjadi keluaran build untuk produksi.

Perbedaan ini tidak membuktikan bahwa satu mode lebih cepat bagi pengguna, bahwa ukuran bundle pasti mengecil, atau bahwa aplikasi siap dideploy. Klaim seperti itu memerlukan pengukuran dan pemeriksaan pada proyek nyata. Aturan praktisnya lebih sederhana: gunakan development server ketika mengubah aset secara lokal, lalu hasilkan build sebelum proses rilis yang memang mengharuskan aset produksi. Cara menyimpan dan menyajikan hasil tersebut tetap bergantung pada lingkungan aplikasi Anda dan berada di luar cakupan artikel ini.

Satu alur kecil dari konfigurasi ke browser

Fragmen berikut mengikuti pola pada dokumentasi resmi Laravel 13.x. Ia hanya menunjukkan hubungan antarbagiannya; dependensi, versi plugin, dan hasil build belum diverifikasi pada proyek nyata.

Contoh konseptual:

// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/js/app.js',
            ],
            assets: ['resources/images/**'],
        }),
    ],
});

{{-- resources/views/layouts/app.blade.php --}}
<head>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    <img
        src="{{ Vite::asset('resources/images/logo.png') }}"
        alt="Logo aplikasi"
    >
</body>

Alurnya dapat dibaca dari atas ke bawah:

1. plugin Laravel memberi tahu Vite bahwa CSS dan JavaScript tersebut adalah entry point;
2. @vite meminta aset untuk entry point yang sama dari template Blade;
3. pada development, integrasi mengarah ke development server yang terdeteksi;
4. pada build mode, integrasi memuat aset hasil kompilasi dan versioning;
5. pola assets membuat Vite mengetahui aset yang hanya dirujuk langsung dari Blade, lalu Vite::asset mengembalikan URL berversi untuk aset tersebut setelah build.

Jika gambar sudah diimpor dari JavaScript atau direferensikan melalui CSS, Vite menangani aset itu sebagai bagian dari graf build. Opsi assets pada contoh di atas ditujukan untuk file yang perlu dirujuk langsung dari Blade melalui Vite::asset. Jangan menyalin kedua pola sekaligus tanpa memeriksa bagaimana file dipakai di proyek Anda.

Aset di resources dan file publik tidak selalu mengikuti jalur yang sama

Dokumentasi Vite menjelaskan bahwa aset yang diimpor dari source code menghasilkan URL yang diselesaikan oleh Vite. Pada development dan production build, URL akhirnya dapat berbeda; aset yang menjadi bagian dari graf build juga dapat memperoleh nama ber-hash.

Vite juga memiliki direktori public untuk file yang tidak dirujuk dari source code, harus mempertahankan nama persis, atau sengaja tidak ingin diimpor. File di sana dirujuk dengan path absolut dari root, misalnya /icon.png, dan disalin apa adanya ke root keluaran build. Karena file public tidak mengikuti pola impor dan hashing yang sama, pilih jalurnya berdasarkan kebutuhan file, bukan sekadar lokasi yang terasa mudah.

Untuk aplikasi Laravel berbasis Blade, dokumentasi Laravel menyediakan mekanisme assets dan Vite::asset bagi aset di resources yang hanya dirujuk dari Blade. Ini membuat hubungan file tetap berada dalam pipeline Vite tanpa mengharuskan impor palsu dari JavaScript.

VITE_ berarti boleh dibaca klien, bukan tempat menyimpan rahasia

Vite menyediakan import.meta.env untuk nilai lingkungan yang dipakai kode frontend. Secara default, variabel dengan awalan VITE_ diekspos ke source code sisi klien setelah bundling. Dokumentasi Vite memperingatkan agar awalan tersebut tidak dipakai untuk informasi sensitif seperti API key.

Gunakan VITE_ hanya untuk nilai yang memang boleh diketahui pengguna, misalnya URL halaman bantuan publik:

VITE_PUBLIC_SUPPORT_URL=https://example.com/help

const supportUrl = import.meta.env.VITE_PUBLIC_SUPPORT_URL;

Contoh itu bukan mekanisme perlindungan. Nilainya menjadi bagian dari kode yang dikirim ke klien dan harus diperlakukan sebagai informasi publik. Kredensial database, private API key, token layanan, dan rahasia lain harus tetap berada pada boundary server yang sesuai, bukan dipindahkan ke variabel VITE_.

Perlu diingat juga bahwa nilai variabel lingkungan yang diekspos Vite dibaca sebagai string. Jika aplikasi membutuhkan boolean atau angka, lakukan konversi dan validasi secara eksplisit; jangan mengandalkan bentuk teksnya sebagai tipe data akhir.

Cara menelusuri masalah aset tanpa menebak

Ketika aset tidak muncul, ikuti alurnya dalam urutan yang sama dengan pipeline:

1. pastikan file yang benar tercantum sebagai entry point atau terhubung melalui impor;
2. samakan nilai yang dipanggil @vite dengan entry point di vite.config.js;
3. tentukan apakah proyek sedang memakai development server atau hasil build;
4. untuk aset Blade-only, periksa apakah pola assets mencakup file dan apakah Vite::asset memakai path yang sama;
5. untuk konfigurasi frontend, pastikan hanya nilai publik yang memakai awalan VITE_.

Urutan ini sengaja tidak mencakup hosting, CDN, cache invalidation, atau CI/CD. Jika konfigurasi dasar sudah cocok tetapi aset tetap gagal dimuat, lanjutkan dengan memeriksa versi dependency, pesan terminal saat dev/build, dan request aset di browser pada lingkungan proyek Anda. Jangan menyimpulkan penyebab hanya dari nama file yang terlihat.

Kapan memakai alur ini, dan apa yang perlu divalidasi sendiri

Pakai integrasi Laravel/Vite ketika aplikasi Laravel Anda membutuhkan pipeline untuk CSS, JavaScript, dan aset terkait, lalu biarkan entry point serta @vite menjembatani development dan build mode. Gunakan impor source code untuk aset yang memang menjadi bagian dari graf modul; untuk aset yang hanya dipakai di Blade, evaluasi pola assets dan Vite::asset yang didokumentasikan Laravel. Gunakan direktori public hanya ketika karakter file memang cocok dengan aturan Vite untuk aset publik.

Sebelum membawa perubahan ke produksi, validasi versi Laravel, Vite, dan laravel-vite-plugin pada lockfile; jalankan perintah di proyek yang sebenarnya; periksa keluaran build serta URL aset; dan pastikan tidak ada secret di nilai yang dapat dibaca klien. Keputusan akhirnya sederhana: bila browser perlu menerima nilainya, perlakukan nilai itu sebagai publik. Bila nilainya harus rahasia, jangan masukkan ke pipeline frontend.