1. Tailwind CSS v4 Nedir? (What is Tailwind v4?)

Tailwind CSS v4, utility-first CSS framework'ünün şimdiye kadarki en büyük sürüm yükseltmesidir (the biggest version upgrade ever). Önceki sürümlerden farklı olarak v4, sıfırdan yeniden tasarlandı (redesigned from scratch). Adam Wathan ve ekibi; framework'ün build performansını, geliştirici deneyimini (developer experience) ve modern CSS özelliklerine adaptasyonunu radikal biçimde iyileştirdi.

Alesta Web ekibi olarak Tailwind v4 sürümüyle ilgili gelen onlarca soruyu derledik ve bu rehberde tüm önemli noktalara değineceğiz. İşte v4'ün ana özelliklerinin kısa bir özeti (a brief summary of the main features):

• ✅ Oxide Engine: Rust ile yazılmış yeni build motoru (Rust-based build engine)
• ✅ CSS-First Configuration: JS config dosyaları yerine native CSS (native CSS instead of JS config)
• ✅ Tek import: @import "tailwindcss" ile tek satırda kurulum (one-line setup)
• ✅ Container Queries built-in: Eklenti gerektirmeden dahili destek
• ✅ 3D Transforms: Native 3D dönüşüm utility class'ları (native 3D transform utilities)
• ✅ OKLCH P3 Color Palette: Modern wide-gamut renkler
• ✅ Otomatik content detection: content: [] yapılandırması artık yok

2. Oxide Engine: Rust ile Yazılmış Yeni Build Motoru

Tailwind v4'ün kalbinde Oxide Engine bulunur. Adam Wathan ekibi, eski PostCSS tabanlı build pipeline'ını tamamen bıraktı (completely abandoned the old PostCSS-based pipeline) ve yerine Rust ile yazılmış, daha hızlı ve daha hafif bir motor geliştirdi. Lightning CSS adı verilen hızlı CSS parser'ı kullanan bu motor, modern CSS özelliklerini (modern CSS features) ve vendor prefix işlemlerini native olarak halleder.

Oxide Engine'in Faydaları (Benefits of Oxide Engine)

• Hız: Tam build (full build) 3.78x daha hızlı, incremental build 8.8x daha hızlı, no-op rebuild ise 100x+ daha hızlı (no-op rebuild 100x+ faster)
• Otomatik content detection: Artık content: [] yapılandırması gerekli değil — Tailwind dosyalarınızı kendiliğinden bulur (automatically detects your files)
• Native CSS nesting: Lightning CSS sayesinde CSS nesting native olarak çalışır
• Vendor prefix otomasyonu: Lightning CSS, hedef browser desteğinize göre otomatik prefix ekler (auto-prefixes based on target browsers)
• Daha az bağımlılık: autoprefixer ve postcss-import gibi paketlere gerek yok (no need for autoprefixer)

# Vite ile yeni proje (Vite plugin v4 için en hızlı yol — fastest path)
npm install tailwindcss @tailwindcss/vite

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

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

@import "tailwindcss";

3. CSS-First Configuration ve @theme Direktifi

Tailwind v3'te tema konfigürasyonu tailwind.config.js dosyasında JavaScript ile yapılırdı. v4 ile bu yaklaşım terk edildi (this approach was abandoned). Artık tüm tema konfigürasyonu doğrudan CSS dosyanızda @theme direktifi ile yapılır.

Eski Yöntem (v3) — JavaScript Config

// tailwind.config.js (v3 — DEPRECATED)
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#1e293b',
        secondary: '#475569'
      },
      fontFamily: {
        display: ['Inter', 'sans-serif']
      },
      screens: {
        '3xl': '120rem'
      }
    }
  }
}

Yeni Yöntem (v4) — CSS @theme Direktifi

/* style.css (v4 — yeni yöntem) */
@import "tailwindcss";

@theme {
  --color-primary: #1e293b;
  --color-secondary: #475569;
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 120rem;
  --radius-2xl: 1.5rem;
  --spacing-128: 32rem;
}

4. Yeni CSS Özellikleri (New CSS Features)

4.1 Container Queries Built-in

v3'te container query desteği @tailwindcss/container-queries plugin'i ile geliyordu. v4'te dahili olarak destekleniyor (built-in support). Artık ayrı plugin kurmanıza gerek yok.

<div class="@container">
  <div class="@md:flex @lg:grid @lg:grid-cols-3">
    Container'a göre layout değiştirir (changes layout per container)
  </div>
</div>

4.2 3D Transforms (3D Dönüşümler)

Tailwind v4 ile birlikte 3D dönüşüm utility class'ları geldi (3D transform utilities arrived).

<div class="rotate-x-45 rotate-y-30 perspective-distant">
  3D Card Effect
</div>

4.3 OKLCH P3 Color Palette

v4 ile birlikte color palette modernleştirildi. OKLCH renk uzayı kullanılıyor (uses OKLCH color space). Bu sayede modern OLED ve P3 ekranlarda daha canlı renkler görüntülenir (more vibrant colors on modern OLED and P3 displays).

4.4 Modern Gradient API

<!-- Konik gradient (Conic gradient) -->
<div class="bg-conic from-red-500 via-yellow-500 to-blue-500">
  Conic Gradient
</div>

<!-- Radial gradient -->
<div class="bg-radial from-pink-500 to-purple-700">
  Radial Gradient
</div>

<!-- OKLCH interpolation -->
<div class="bg-linear-to-r/oklch from-blue-500 to-green-500">
  Smooth OKLCH transition
</div>

4.5 @starting-style ve Diğer Modern CSS

v4, modern CSS özelliklerine native destek verir (native support for modern CSS features): cascade layers, @starting-style, :has() selector, anchor positioning, scroll-driven animations.

5. v3'ten v4'e Migration Rehberi (Migration Guide)

Eğer mevcut bir Tailwind v3 projeniz varsa, migration için resmi upgrade tool kullanın (use the official upgrade tool):

# Node.js 20+ gerekli (Node.js 20+ required)
npx @tailwindcss/upgrade

Manuel Migration Adımları (Manual Migration Steps)

npm uninstall tailwindcss postcss autoprefixer
npm install tailwindcss@latest @tailwindcss/postcss

// postcss.config.mjs (yeni format)
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

/* ESKİ (v3 — DEPRECATED) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* YENİ (v4) */
@import "tailwindcss";

/* style.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(70% 0.15 250);
  --font-display: "Inter Variable", sans-serif;
  --breakpoint-xs: 30rem;
  --shadow-card: 0 4px 12px oklch(0% 0 0 / 0.08);
}

6. Breaking Changes ve Dikkat Edilecekler (Watch Out!)

Class İsim Değişiklikleri (Class Name Changes)

Browser Desteği (Browser Support)

Tailwind v4 modern CSS özellikleri kullandığı için minimum browser sürümleri yükseltildi (minimum browser versions raised):

• Safari 16.4+ (Mart 2023+)
• Chrome 111+ (Mart 2023+)
• Firefox 128+ (Temmuz 2024+)

7. Pratik Kullanım Örnekleri (Practical Examples)

7.1 Modern Buton Komponenti (Modern Button Component)

<button class="bg-blue-500 hover:bg-blue-600 text-white px-6 py-3
  rounded-lg shadow-sm hover:shadow-md transition-all
  duration-200 active:scale-95">
  Beni Tıkla / Click Me
</button>

7.2 Container Query ile Responsive Kart (Responsive Card with Container Query)

<div class="@container">
  <article class="@md:flex @md:gap-6 p-6 bg-white rounded-xl shadow-sm">
    <img class="@md:w-32 w-full rounded-lg" src="..." alt="Kart görseli - card image" />
    <div class="@md:flex-1">
      <h3 class="text-lg font-semibold">Başlık (Title)</h3>
      <p class="text-gray-600">Açıklama metni...</p>
    </div>
  </article>
</div>

7.3 OKLCH Renkler ile Gradient

<div class="bg-linear-45/oklch from-pink-500 to-purple-700
  h-64 rounded-2xl flex items-center justify-center">
  <h2 class="text-white text-4xl font-bold">
    Modern Gradient
  </h2>
</div>

8. Performans Karşılaştırması (Performance Benchmark)

Tailwind ekibi tarafından yapılan resmi benchmark sonuçları (official benchmark results), tailwindcss.com projesinin kendi build süreleri üzerinden ölçülmüştür:

9. Sık Karşılaşılan Hatalar ve Çözümleri (Common Errors and Solutions)

Hata 1: "Cannot find module 'tailwindcss/colors'"

Error: Cannot find module 'tailwindcss/colors' (module not found)

Hata 2: PostCSS Plugin Hatası

[postcss] It looks like you're trying to use tailwindcss directly
as a PostCSS plugin (direct usage detected).

Hata 3: Custom Class'lar Çalışmıyor

<!-- Çalışmayan örnek (Not working example) -->
<div class="bg-brand-primary">...</div>

@theme {
  --color-brand-primary: oklch(60% 0.18 250);
}

Hata 4: Eski Class'lar Stil Vermiyor (Old Classes No Longer Style)

Migration sonrası bazı class'lar görsel değişiklik gösteriyor: shadow, ring, rounded-sm gibi. Alesta Web ipucu: manuel arama-değiştirme yerine npx @tailwindcss/upgrade tool'unu kullanın (use the upgrade tool instead of manual find-replace).

10. 📚 Kaynaklar ve Referanslar / Sources and References

Bu makaledeki bilgiler aşağıdaki güvenilir kaynaklardan derlenmiştir (information compiled from the following reliable sources):

• Tailwind CSS v4 Resmi Duyurusu (Official Announcement)
• Tailwind v4 Upgrade Guide (Resmi migration rehberi)
• Lightning CSS (Oxide Engine'in tabanı)
• Tailwind CSS GitHub Repository

Alesta Web olarak tüm bilgileri doğruladık ve test ettik (we verified and tested all information in production projects).