Tailwind CSS v4: Apa yang Berubah dan Cara Migrasi dari v3

Tailwind CSS v4 membawa tiga perubahan besar: konfigurasi pindah dari tailwind.config.js ke file CSS lewat direktif @theme, mesin baru yang membuat build jauh lebih cepat, dan deteksi file sumber otomatis sehingga daftar content tidak perlu ditulis lagi. Kelas utility yang kamu pakai sehari-hari sebagian besar tetap sama, jadi migrasi biasanya lebih banyak menyentuh konfigurasi daripada markup.

Instalasi Tailwind CSS v4 dengan Vite

npm install tailwindcss @tailwindcss/vite

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

export default defineConfig({
  plugins: [
    laravel({ input: ['resources/css/app.css', 'resources/js/app.js'], refresh: true }),
    tailwindcss(),
  ],
});

/* resources/css/app.css */
@import "tailwindcss";

Satu baris import menggantikan tiga direktif @tailwind base/components/utilities di v3. Proyek Laravel baru sudah memakai susunan ini secara bawaan.

Konfigurasi di CSS dengan @theme

@import "tailwindcss";

@theme {
  --font-sans: "Plus Jakarta Sans", ui-sans-serif, system-ui, sans-serif;
  --color-brand-500: #00a9a5;
  --color-brand-700: #007674;
  --breakpoint-3xl: 1920px;
}

Variabel di @theme otomatis menghasilkan utility: bg-brand-500, text-brand-700, font-sans, dan 3xl:. Nilainya juga tersedia sebagai CSS variable biasa, misalnya var(--color-brand-500), sehingga bisa dipakai di CSS kustom atau JavaScript.

Perubahan Lain yang Perlu Diketahui

Langkah Migrasi dari v3

1. Buat branch baru dan pastikan proyek bersih di Git.
2. Jalankan alat upgrade resmi:

npx @tailwindcss/upgrade

1. Periksa diff: alat ini memperbarui dependensi, memindahkan konfigurasi ke CSS, dan mengganti nama kelas yang berubah di template.
2. Cek kelas yang berganti nama atau perilaku, misalnya skala shadow, rounded, dan blur yang bergeser satu tingkat (shadow-sm di v3 menjadi shadow-xs di v4), serta warna default border dan ring.
3. Cek kelas dinamis. Kelas yang dirangkai dari string, seperti `bg-${color}-500`, tetap tidak terdeteksi. Tulis nama kelas lengkap.
4. Uji tampilan di halaman-halaman utama, termasuk mode gelap.

Contoh Komponen

<a href="/tools" class="inline-flex items-center gap-2 rounded-lg bg-brand-700 px-4 py-2
   font-semibold text-white hover:bg-brand-500 focus-visible:outline-2
   focus-visible:outline-offset-2 focus-visible:outline-brand-700">
  Coba tools gratis
</a>

Perhatikan pilihan warna teks: teal terang seperti #00a9a5 punya kontras rendah terhadap putih, jadi untuk teks dan tombol pilih varian yang lebih gelap. Cek rasio kontras agar memenuhi WCAG AA.

Mode Gelap dan Varian Kustom

Secara default, varian dark: mengikuti pengaturan sistem operasi. Kalau situsmu punya tombol ganti tema yang menyimpan pilihan di atribut HTML, definisikan ulang variannya:

@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

Sekarang dark:bg-slate-900 aktif saat elemen <html data-theme="dark">, bukan hanya saat sistem dalam mode gelap. Pola yang sama dipakai untuk varian lain, misalnya tampilan khusus saat pengguna sudah login.

Dukungan Browser

Tailwind v4 mengandalkan fitur CSS modern seperti cascade layers dan @property, dan menargetkan Safari 16.4, Chrome 111, dan Firefox 128 ke atas. Kalau pengguna aplikasimu banyak memakai browser lama, misalnya perangkat kantor yang tidak diperbarui, tetap di v3 sampai kondisinya memungkinkan.

Kesalahan yang Sering Terjadi

• Memakai plugin PostCSS dan plugin Vite sekaligus, sehingga CSS diproses dua kali.
• Plugin v3 yang belum kompatibel. Cek dukungan v4 untuk plugin seperti typography dan forms sebelum migrasi.
• Folder di luar proyek tidak terdeteksi, misalnya view di paket vendor. Tambahkan dengan @source "../vendor/nama-paket/resources/views";.

Langkah Berikutnya

Tailwind sering dipakai bersama framework React; lihat Next.js untuk backend developer. Untuk menyiapkan editor agar autocomplete kelas Tailwind bekerja, baca setup VS Code untuk produktivitas.