Migrasi Tailwind v3 → v4 (90 menit guide)

TL;DR

• Recommended migrate Tailwind v3 → v4 untuk semua project SMB Indonesia 2026.
• Build speedup 5-10x measured konsisten across 6 project klien.
• Effort 60-120 menit untuk project medium + 1-2 hari testing staging.
• Verdict: do it. Stay v3 hanya jika project deprecated atau migrate cost > maintain cost (rare).

Konteks

Saya migrate 6 project klien Tailwind v3 → v4 dari Q4 2025 - Q2 2026:

• SaaS dental Jakarta (Next.js 15, 12K LOC): 75 menit migration + 3 hari testing
• Ecommerce klinik kecantikan (Astro, 8K LOC): 50 menit + 2 hari testing
• Marketing site fotografer Tangerang (Astro, 2K LOC): 35 menit + 1 hari testing
• Admin warung scale (SvelteKit, 6K LOC): 90 menit + 2 hari testing
• Portfolio personal (Astro, 1K LOC): 25 menit + 0.5 hari testing
• Internal dashboard HR (Next.js, 18K LOC): 120 menit + 5 hari testing

Average: 65 menit migration + 2 hari testing. Zero rollback. Build time speedup 5-12x.

Pricing (Juni 2026)

Tailwind v3 dan v4 sama-sama gratis dan open-source. Migration cost = waktu dev:

• Solo dev senior (rate Rp 250rb/jam): 65 menit = Rp 270rb
• Mid-level (Rp 150rb/jam): 65 menit = Rp 165rb
• Junior (Rp 80rb/jam): 100 menit = Rp 135rb

Plus testing time: 1-2 hari × 4 jam = 4-8 jam (Rp 320rb - 2 juta tergantung rate).

Total migration cost untuk project medium: Rp 500rb - 2.3 juta. ROI: build speedup 10s+ per dev iteration, akumulasi positive dalam 1-2 minggu coding.

Step-by-step (90 menit average)

Step 1: Backup dan branch (5 menit)

git checkout -b migrate/tailwind-v4
git push -u origin migrate/tailwind-v4

Pastikan main branch protected. Saya pakai PR review gating untuk migration besar.

Step 2: Update dependency (5 menit)

bun remove tailwindcss postcss autoprefixer
bun add tailwindcss@latest

Untuk Vite (Astro, Vite-based):

bun add @tailwindcss/vite

Untuk Next.js:

bun add @tailwindcss/postcss

Step 3: Update bundler config (10 menit)

Astro (astro.config.mjs):

import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

Next.js (postcss.config.mjs):

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

SvelteKit:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
export default { plugins: [tailwindcss()] };

Step 4: Convert tailwind.config.js → @theme (20 menit)

V3 config:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#FF6B35',
        accent: '#1A1A2E',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
};

V4 setara di CSS file utama:

/* src/styles/global.css */
@import "tailwindcss";

@theme {
  --color-brand: #FF6B35;
  --color-accent: #1A1A2E;
  --font-sans: "Inter", sans-serif;
}

Naming convention: --color-*, --font-*, --spacing-*, --radius-*. Auto-generate utility class.

Step 5: Replace deprecated utility (15 menit)

Cari dan replace pattern lama:

V3 deprecated	V4 modern
text-opacity-50	text-black/50
bg-opacity-50	bg-white/50
border-opacity-50	border-gray-500/50
divide-opacity-X	divide-color/X
placeholder-opacity-X	placeholder:color/X
flex-shrink-0	shrink-0 (sudah valid v3, alias)

Pakai sed atau Cursor Composer untuk batch replace.

Step 6: Fix default border color (10 menit)

V3 default: border-gray-200. V4 default: currentColor.

Add fallback class jika project Anda relied di v3 default:

@layer base {
  *, ::before, ::after {
    border-color: var(--color-gray-200, currentColor);
  }
}

Atau eksplisit per element: <div class="border border-gray-200">.

Step 7: Test build (10 menit)

bun run build

Cek:

• Build success
• CSS bundle size (should be similar atau lebih kecil)
• Visual regression test (lihat preview deploy)

Step 8: Browser test (15 menit)

Buka 5-10 page penting:

• Halaman utama (marketing)
• Halaman login/signup
• Dashboard/admin
• Form submission
• Modal/dialog

Cek visual matching dengan v3 production. Untuk SaaS dental saya pakai Playwright visual regression — 95% match auto-pass, 5% manual review.

Step 9: Deploy ke staging (5 menit)

git push origin migrate/tailwind-v4
# Create PR
# Preview deploy auto trigger

Test staging 1-2 hari sebelum merge ke main.

Step 10: Merge + monitor production (variable)

Merge PR. Production deploy auto.

Monitor 1 minggu:

• Error rate (Sentry)
• Page load metric
• User-reported issue

Common gotcha

1. Container query syntax change

V3:

<div class="@container">
  <div class="@md:flex">

V4: Same syntax, tapi pastikan @tailwindcss/container-queries plugin uninstall — built-in di v4.

2. Arbitrary value escaping

V3 string interpolation cukup forgiving. V4 lebih strict:

<!-- V3 OK, V4 break -->
<div class="bg-[url(image.jpg)]">

<!-- V4 correct -->
<div class="bg-[url('image.jpg')]">

3. Plugin migration

V3 JS plugin tetap work di v4 (legacy mode), tapi performance tidak optimal. Migrate ke CSS-first plugin jika ada equivalent.

Contoh: @tailwindcss/forms punya CSS-first version di v4.

4. Theme function syntax

V3:

.custom { color: theme('colors.brand'); }

V4 (still works tapi prefer CSS var):

.custom { color: var(--color-brand); }

5. Build cache invalidation

Setelah migrate, hapus cache:

rm -rf .next .astro dist node_modules/.vite
bun install
bun run build

Performance gain

Build time before/after (measured di MacBook Air M2):

Project	V3 build	V4 build	Speedup
SaaS dental	12.3s	1.6s	7.7x
Ecommerce klinik	8.9s	1.2s	7.4x
Marketing fotografer	4.2s	0.5s	8.4x
Admin warung	9.8s	1.3s	7.5x
Portfolio personal	2.1s	0.3s	7x
Dashboard HR	18.5s	2.4s	7.7x

Konsisten 7-8x speedup. Untuk dev daily iteration: save 5-15 detik per build × 30-50 build/hari = save 4-12 menit/hari.

Konteks Indonesia

Untuk SMB Indonesia 2026:

• Project klien yang masih v3: migrate. ROI positif dalam 2 minggu.
• Project warisan yang deprecated: skip — tidak worth migrate jika tidak active development.
• Project baru: start langsung v4. Default sejak Astro 6, Next.js 15, Nuxt 4.

Klien dental Jakarta: migrate dilakukan weekend. Tim 1 dev senior. Total cost Rp 1.2 juta (8 jam termasuk testing). Build time daily save ~10 menit/dev × 5 dev = 50 menit/hari = 10+ jam/bulan. ROI 2 minggu.

Verdict

Recommended migrate Tailwind v3 → v4 untuk semua project SMB Indonesia aktif.

Migrate sekarang jika:

• Project active development (3+ commit/minggu)
• Build time pernah jadi pain point
• Stack Anda Astro 6 / Next.js 15 / SvelteKit (semua native support v4)

Postpone jika:

• Project maintenance mode (rare update)
• Custom plugin v3 banyak yang belum ada equivalent v4
• Tim Anda di tengah feature release besar — migrate setelah release

Skip jika:

• Project end-of-life (akan deprecated dalam 6 bulan)

Untuk component library yang fit v4: shadcn vs Park UI vs Bits UI.