Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Dashboard Admin, CRUD & Frontend / Integrasi Laravel dengan Tailw...
Dashboard Admin, CRUD & Frontend

Integrasi Laravel dengan Tailwind CSS 4: Setup, Konfigurasi, dan Troubleshooting

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
11 min read
13 views

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.

Overview

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."
  • "Kenapa class bg-brand-500 dari database tidak muncul di production?"
  • "Plugin @tailwindcss/forms dipasang di mana sekarang?"
  • "Setelah upgrade, tombol dan border tampil berbeda."

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.

Prerequisites

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.

Step-by-step Tutorial

Langkah 1: Proyek Baru Sudah Siap Pakai

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>

Langkah 2: Memasang di Proyek Lama (Tanpa Tailwind)

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).

Langkah 3: Pahami Deteksi Sumber dengan @source

Tailwind 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';

Langkah 4: Tema Kustom dengan @theme

Nilai 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).

Langkah 5: Font Lokal

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.

Langkah 6: Dark Mode yang Bisa Dipilih Pengguna

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']);

Langkah 7: Plugin Resmi

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>

Langkah 8: Komponen dan Utility Kustom

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; }

Langkah 9: Class Dinamis dari Database atau PHP

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.

Langkah 10: Migrasi dari Tailwind 3

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.

Langkah 11: Hidup Berdampingan dengan Bootstrap

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.

Langkah 12: Build Production dan Deploy

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:

  • folder 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.
  • file public/hot tidak ada di server production (file ini membuat Laravel mencari dev server Vite).

Troubleshooting

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 *));

Best Practices

Keamanan

  • Muat font dan aset dari server sendiri; ini juga menyederhanakan Content Security Policy.
  • Jangan pernah menyusun class dari input pengguna; selain tidak berfungsi, nilai mentah di atribut class tetap harus di-escape oleh Blade.

Performa

  • Biarkan Tailwind menghasilkan hanya class yang dipakai; hindari @source inline() yang terlalu luas.
  • Kecualikan folder besar yang tidak berisi class dengan @source not.
  • Gunakan satu file CSS untuk seluruh aplikasi publik, dan entry terpisah hanya bila memang ada area dengan gaya berbeda (misalnya admin).

Maintainability

  • Definisikan identitas visual (warna, font, radius) di @theme; jangan menulis nilai heksadesimal langsung di template.
  • Gunakan Blade Components untuk pola UI yang berulang, bukan menumpuk @apply.
  • Simpan pemetaan status → class di enum agar konsisten di seluruh aplikasi.
  • Lakukan upgrade Tailwind di branch terpisah dan periksa tampilan halaman-halaman utama sebelum merge.

Related Articles

Last Tested

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

Bagikan artikel:

Artikel lainnya