Integrasi Laravel dengan Tailwind CSS 4: Setup, Konfigurasi, dan Troubleshooting
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
Tailwind CSS 4 mengubah cara konfigurasi: tidak ada lagi tailwind.config.js wajib, tema didefinisikan di CSS, dan integrasi dengan Vite lewat plugin resmi. Panduan ini membahas setup di Laravel 13, kustomisasi tema, dark mode, plugin, class dinamis, migrasi dari v3, hidup berdampingan dengan Bootstrap, dan solusi masalah yang paling sering muncul.
Developer yang terbiasa dengan Tailwind 3 sering bingung saat pertama kali memakai Tailwind 4:
tailwind.config.js-nya di mana? Warna kustom saya tidak terbaca."bg-brand-500 dari database tidak muncul di production?"@tailwindcss/forms dipasang di mana sekarang?"Perubahan utamanya:
| Aspek | Tailwind 3 | Tailwind 4 |
|---|---|---|
| Konfigurasi | tailwind.config.js |
Di file CSS dengan @theme, @plugin, @source |
| Import | @tailwind base; @tailwind components; @tailwind utilities; |
@import "tailwindcss"; |
| Deteksi file sumber | Daftar content manual |
Otomatis, bisa ditambah lewat @source |
| Integrasi build | Plugin PostCSS tailwindcss |
Plugin Vite @tailwindcss/vite (atau @tailwindcss/postcss) |
| Nilai tema | Objek JavaScript | CSS custom properties (--color-*, --font-*) |
| Dark mode berbasis class | darkMode: 'class' |
@custom-variant dark (...) |
Hasil akhir: proyek Laravel dengan Tailwind 4 yang terkonfigurasi untuk aplikasi RW: warna dan font identitas, dark mode yang bisa diganti pengguna, plugin forms dan typography, deteksi class dari Blade dan paket vendor, serta penanganan class dinamis.
| Komponen | Versi |
|---|---|
| PHP | 8.3+ |
| Laravel | 13.x |
| Node.js | 20.19+ atau 22.12+ (disarankan 22 LTS) |
| Vite | 7.x atau 8.x |
| Tailwind CSS | 4.3.x |
| Browser target | Safari 16.4+, Chrome 111+, Firefox 128+ |
Tailwind 4 memakai fitur CSS modern (cascade layers, @property, color-mix()). Bila aplikasi harus mendukung browser yang jauh lebih lama, tetap gunakan Tailwind 3.4.
Proyek Laravel 13 baru sudah menyertakan Tailwind 4. Periksa tiga file berikut:
// package.json (sebagian)
{
"devDependencies": {
"@tailwindcss/vite": "^4.3.0",
"laravel-vite-plugin": "^2.0",
"tailwindcss": "^4.3.0",
"vite": "^7.0"
}
}
// vite.config.js
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(),
],
});
/* 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';
Angka versi persis di package.json bisa berbeda; yang penting paket tailwindcss dan @tailwindcss/vite berada di versi mayor 4.
Jalankan:
npm install
npm run dev # development dengan hot reload
npm run build # build production ke public/build
Muat di layout:
<head>
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
npm install tailwindcss @tailwindcss/vite
Tambahkan tailwindcss() ke plugins di vite.config.js (seperti Langkah 1), lalu ganti isi resources/css/app.css dengan baris @import 'tailwindcss'; dan direktif @source yang sesuai.
Tidak perlu postcss.config.js maupun tailwind.config.js bila memakai plugin Vite. Bila proyek Anda memiliki postcss.config.js lama yang memanggil tailwindcss, hapus entri itu (lihat Troubleshooting).
@sourceTailwind 4 memindai file proyek secara otomatis untuk menemukan nama class yang dipakai, dengan mengabaikan file di .gitignore (misalnya vendor/, node_modules/, storage/). Karena itu Anda perlu menambahkan sumber yang terabaikan secara eksplisit:
@import 'tailwindcss';
/* View pagination bawaan Laravel ada di vendor (diabaikan .gitignore) */
@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';
/* View paket pihak ketiga yang memakai class Tailwind */
@source '../../vendor/livewire/flux/stubs/**/*.blade.php';
/* View hasil kompilasi Blade (berguna untuk komponen dari paket) */
@source '../../storage/framework/views/*.php';
/* Folder modul di luar resources/ */
@source '../../modules/**/*.blade.php';
Path @source relatif terhadap lokasi file CSS (resources/css/).
Untuk mengecualikan folder yang tidak perlu dipindai (mempercepat build):
@source not '../../resources/views/emails';
@themeNilai tema didefinisikan sebagai variabel CSS. Setiap variabel --color-* otomatis menghasilkan utility bg-*, text-*, border-*, dan seterusnya.
/* resources/css/app.css */
@import 'tailwindcss';
@source '../**/*.blade.php';
@theme {
/* Font */
--font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
--font-display: "Plus Jakarta Sans", var(--font-sans);
/* Warna identitas RW */
--color-brand-50: oklch(0.97 0.02 165);
--color-brand-100: oklch(0.93 0.04 165);
--color-brand-500: oklch(0.55 0.10 165);
--color-brand-600: oklch(0.48 0.10 165);
--color-brand-700: oklch(0.41 0.09 165);
--color-brand-900: oklch(0.27 0.06 165);
/* Warna status */
--color-lunas: var(--color-emerald-600);
--color-tunggak: var(--color-amber-600);
/* Breakpoint tambahan */
--breakpoint-3xl: 112rem;
/* Radius dan bayangan */
--radius-card: 0.875rem;
--shadow-card: 0 1px 2px rgb(0 0 0 / 0.04), 0 4px 16px rgb(0 0 0 / 0.06);
}
<button class="rounded-card bg-brand-600 px-4 py-2 font-display text-white shadow-card hover:bg-brand-700">
Simpan
</button>
<span class="text-lunas">Lunas</span>
Untuk mengganti seluruh palet bawaan (bukan menambah), kosongkan namespace terlebih dahulu:
@theme {
--color-*: initial;
--color-white: #fff;
--color-black: #000;
--color-brand-500: oklch(0.55 0.10 165);
/* ... */
}
Karena nilai tema adalah variabel CSS, nilainya juga bisa dipakai di CSS biasa atau JavaScript:
.kartu-statistik {
border-left: 4px solid var(--color-brand-500);
}
const brand = getComputedStyle(document.documentElement).getPropertyValue('--color-brand-500');
Ini berguna untuk menyamakan warna grafik Chart.js dengan tema (lihat artikel Dashboard Statistik).
Hindari memuat font dari CDN pihak ketiga (alasan privasi, CSP, dan kecepatan). Simpan di proyek:
npm install @fontsource-variable/inter
@import '@fontsource-variable/inter';
@import 'tailwindcss';
@theme {
--font-sans: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
}
Vite akan menyalin file font ke public/build dan menulis URL yang benar.
Secara bawaan, varian dark: mengikuti pengaturan sistem operasi (prefers-color-scheme). Untuk tombol "Mode gelap" manual, definisikan varian berbasis class:
@custom-variant dark (&:where(.dark, .dark *));
<html lang="id" class="{{ request()->cookie('tema') === 'gelap' ? 'dark' : '' }}">
<body class="bg-white text-slate-900 dark:bg-slate-950 dark:text-slate-100">
// resources/js/tema.js
const root = document.documentElement;
export function setTema(tema) { // 'terang' | 'gelap' | 'sistem'
const gelap = tema === 'gelap' || (tema === 'sistem' && matchMedia('(prefers-color-scheme: dark)').matches);
root.classList.toggle('dark', gelap);
document.cookie = `tema=${tema}; path=/; max-age=31536000; samesite=lax`;
}
Menyimpan pilihan di cookie (bukan hanya localStorage) memungkinkan server merender class dark sejak awal, sehingga tidak ada kilatan tampilan terang saat halaman dimuat. Daftarkan cookie tema di pengecualian enkripsi cookie bila nilainya dibaca langsung:
// bootstrap/app.php
$middleware->encryptCookies(except: ['tema']);
npm install -D @tailwindcss/forms @tailwindcss/typography
@import 'tailwindcss';
@plugin '@tailwindcss/forms';
@plugin '@tailwindcss/typography';
@tailwindcss/forms menormalkan tampilan input, select, dan checkbox agar mudah diberi gaya.@tailwindcss/typography menyediakan class prose untuk konten panjang, misalnya isi pengumuman RW:<article class="prose prose-slate max-w-none dark:prose-invert">
{!! $pengumuman->isi !!} {{-- sudah disanitasi saat disimpan --}}
</article>
Untuk pola yang berulang, utamakan Blade Components (lihat artikel Membuat Reusable Blade Components). Gunakan CSS kustom hanya untuk hal yang benar-benar bersifat global:
/* Utility kustom: mendukung varian seperti hover:, md:, dark: */
@utility scrollbar-tipis {
scrollbar-width: thin;
scrollbar-color: var(--color-slate-300) transparent;
}
/* Gaya dasar elemen */
@layer base {
[x-cloak] { display: none !important; }
h1, h2, h3 { font-family: var(--font-display); }
}
/* Kelas komponen, bila memang diperlukan */
@layer components {
.btn {
@apply inline-flex items-center gap-2 rounded-lg px-4 py-2 text-sm font-semibold transition;
}
.btn-primary {
@apply bg-brand-600 text-white hover:bg-brand-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand-600;
}
}
Bila memakai @apply di file CSS terpisah (misalnya CSS milik komponen Vue/Svelte, atau file yang tidak mengimpor tailwindcss), tambahkan referensi agar tema dikenali:
@reference "../../css/app.css";
.judul { @apply text-brand-700 font-display; }
Tailwind hanya menghasilkan class yang tertulis utuh di file sumber. Kode seperti ini tidak akan berfungsi di production:
{{-- SALAH: Tailwind tidak bisa menebak bg-emerald-100 / bg-amber-100 --}}
<span class="bg-{{ $warna }}-100 text-{{ $warna }}-700">{{ $status }}</span>
Solusi yang benar: tulis nama class lengkap di kode, lalu pilih dengan peta.
// app/Enums/StatusIuran.php
enum StatusIuran: string
{
case Lunas = 'lunas';
case Tunggak = 'tunggak';
case Dispensasi = 'dispensasi';
public function badgeClass(): string
{
return match ($this) {
self::Lunas => 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900/40 dark:text-emerald-300',
self::Tunggak => 'bg-amber-100 text-amber-800 dark:bg-amber-900/40 dark:text-amber-300',
self::Dispensasi => 'bg-sky-100 text-sky-700 dark:bg-sky-900/40 dark:text-sky-300',
};
}
}
<span class="rounded-full px-2 py-0.5 text-xs font-medium {{ $iuran->status->badgeClass() }}">
{{ $iuran->status->label() }}
</span>
Bila class benar-benar berasal dari data (misalnya warna kategori yang dipilih admin dari daftar terbatas), daftarkan secara eksplisit dengan @source inline():
@source inline("{bg,text,border}-{red,amber,emerald,sky,violet}-{100,500,700}");
Sintaks kurung kurawal diekspansi menjadi semua kombinasi. Batasi daftarnya; setiap kombinasi menambah ukuran CSS.
Gunakan alat resmi pada branch terpisah:
git switch -c upgrade-tailwind-4
npx @tailwindcss/upgrade
Alat ini memperbarui dependensi, memindahkan konfigurasi dari tailwind.config.js ke CSS, dan mengganti nama utility yang berubah di file template. Setelah itu, periksa perbedaan perilaku yang paling sering terasa:
| Perubahan | Dampak | Penyesuaian |
|---|---|---|
Warna border bawaan menjadi currentColor |
Elemen border tanpa warna tampil lebih gelap |
Tambahkan warna eksplisit (border-slate-200) |
ring bawaan 1px, bukan 3px |
Fokus terlihat lebih tipis | Gunakan ring-3 bila ingin seperti sebelumnya |
Skala shadow-sm, rounded-sm, blur-sm bergeser satu tingkat |
Bayangan dan sudut sedikit berbeda | Periksa visual; nama lama shadow → shadow-sm, dst. |
bg-opacity-*, text-opacity-* dihapus |
Opasitas tidak berlaku | Gunakan sintaks bg-black/50 |
Tombol tidak lagi cursor: pointer bawaan |
Kursor panah di tombol | Tambahkan cursor-pointer atau aturan di @layer base |
| Placeholder memakai warna teks dengan opasitas | Warna placeholder berubah | Atur placeholder:text-slate-400 |
Bila konfigurasi JavaScript lama masih diperlukan sementara waktu (misalnya plugin kustom yang belum dipindahkan), muat secara eksplisit:
@import 'tailwindcss';
@config '../../tailwind.config.js';
Lakukan pemeriksaan visual halaman demi halaman setelah migrasi. Alat upgrade menangani sebagian besar perubahan nama, tetapi tidak menilai tampilan.
Bila panel admin memakai Bootstrap (artikel Admin Dashboard dengan Bootstrap 5) dan halaman publik memakai Tailwind, pisahkan entry Vite dan jangan memuat keduanya di halaman yang sama.
Bila terpaksa memakai keduanya dalam satu halaman (misalnya saat migrasi bertahap), beri prefix pada utility Tailwind:
@import 'tailwindcss' prefix(tw);
<div class="tw:flex tw:gap-4 card"> {{-- card dari Bootstrap, flex dari Tailwind --}}
Prefix mencegah bentrok nama seperti .container, .hidden, dan .collapse, tetapi tidak mencegah perbedaan reset dasar (preflight). Uji tampilan dengan teliti.
npm ci
npm run build
vite v7.x building for production...
✓ 42 modules transformed.
public/build/manifest.json 0.42 kB
public/build/assets/app-Bq3c1x9z.css 38.17 kB │ gzip: 7.92 kB
public/build/assets/app-D6eKp0Xy.js 46.85 kB │ gzip: 17.10 kB
✓ built in 1.31s
Pastikan:
public/build tidak di-commit bila build dilakukan di server/CI (masukkan ke .gitignore), atau di-commit bila server production tidak memiliki Node.js. Pilih satu cara dan konsisten.public/hot tidak ada di server production (file ini membuat Laravel mencari dev server Vite).| Error / Gejala | Penyebab | Solusi |
|---|---|---|
| Tidak ada gaya sama sekali | @vite tidak dipanggil atau npm run dev tidak berjalan |
Periksa layout; jalankan npm run dev atau npm run build |
It looks like you're trying to use tailwindcss directly as a PostCSS plugin |
postcss.config.js lama masih memanggil tailwindcss |
Hapus entri itu; gunakan @tailwindcss/vite, atau @tailwindcss/postcss bila memang memakai PostCSS |
Warna kustom dari tailwind.config.js tidak terbaca |
Tailwind 4 tidak memuat file config secara otomatis | Pindahkan ke @theme, atau tambahkan @config |
| Class dari paket vendor tidak muncul | Folder vendor/ diabaikan oleh deteksi otomatis |
Tambahkan @source ke path view paket |
| Class dinamis hilang di production | Nama class disusun dari string | Tulis class utuh dengan peta/enum, atau @source inline() |
Cannot apply unknown utility class saat @apply |
File CSS terpisah tidak mengenal tema | Tambahkan @reference ke file CSS utama |
Halaman production mencoba memuat localhost:5173 |
File public/hot ikut ter-deploy |
Hapus public/hot; jangan commit file ini |
| Error Node saat build | Versi Node terlalu lama untuk Vite | Gunakan Node 22 LTS |
| Tampilan berbeda di Safari lama | Browser tidak mendukung fitur CSS modern | Tetapkan target browser minimum, atau gunakan Tailwind 3.4 untuk kebutuhan tersebut |
| Dark mode tidak merespons tombol | Varian dark masih berbasis media query |
Tambahkan @custom-variant dark (&:where(.dark, .dark *)); |
Keamanan
class tetap harus di-escape oleh Blade.Performa
@source inline() yang terlalu luas.@source not.Maintainability
@theme; jangan menulis nilai heksadesimal langsung di template.@apply.| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| Tailwind CSS | 4.3.x |
| @tailwindcss/vite | 4.3.x |
| Vite | 7.x |
| Node.js | 22 LTS |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Panduan Membuat Server-Side Processing DataTables untuk Dataset Berukuran Besar
Berikutnya
Cara Membangun Form Dinamis Laravel dengan Alpine.js dan Validasi Backend
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk