Tailwind CSS v4: Yeni Mimari ve Geçiş Rehberi

Tailwind CSS v4: Yeni Mimari ve Performans Kazanımları

Tailwind CSS v4, çerçevenin bugüne kadarki en kapsamlı iç yeniden yapılandırmasını getiriyor. Bu rehber, orta seviye bir geliştiricinin v3'ten v4'e geçerken neyin değiştiğini anlamasına ve yeni mimarinin pratikte ne kazandırdığına odaklanır. Sürüm numarası veya tarih belirtmediğim yerlerde, ilgili ayrıntının resmi sürüm notlarından doğrulanması gerekir.

Önkoşullar

• Node.js tabanlı bir derleme akışı (Vite, PostCSS veya CLI).
• Tailwind CSS v3 ile en az bir projede çalışmış olmak.
• CSS değişkenleri (--custom-property) ve @layer mantığına aşinalık.

Mimari Neyi Değiştirdi?

v3'te yapılandırma ağırlıklı olarak tailwind.config.js dosyasında yaşar, üretim çıktısı PostCSS eklentisi üzerinden geçer ve tarama (content scanning) için yolları elle tanımlamanız gerekirdi. v4'te üç temel eksen değişiyor:

1. CSS-first yapılandırma. Tema değerleri (renkler, aralıklar, fontlar) @theme bloğu içinde CSS değişkeni olarak tanımlanabilir. JavaScript yapılandırması tamamen kalkmış değil; ancak tema tanımının CSS tarafına taşınması, değerlerin hem yardımcı sınıflarda hem de kendi CSS'inizde aynı kaynaktan okunmasını sağlar.

2. Otomatik içerik algılama. v4, kaynak dosyaları büyük ölçüde kendisi tarar; content dizisini elle doldurma zorunluluğu azalır. Yine de dinamik olarak oluşturulan sınıf adları (örneğin şablondan birleştirilen string'ler) için güvenli listeye (@source inline(...)) ihtiyaç duyabilirsiniz.

3. Yeni motor. Tarama ve dönüştürme mantığı yeniden yazıldı; bu, artımlı derleme hızını ve çıktı boyutunu doğrudan etkiler. Kesin hız rakamları sürüme ve projeye göre değişir; bu yüzden "şu kadar hızlı" gibi bir sayı vermek yanıltıcı olur.

Kurulum ve Geçiş Adımları

Aşağıdaki akış, Vite tabanlı bir projeyi varsayar. Adımlar sıralıdır; her birinden sonra beklenen davranışı not düştüm.

1. Paketleri güncelle

npm install tailwindcss @tailwindcss/vite

v4'te Vite için ayrı bir eklenti paketi kullanılır. PostCSS üzerinden ilerliyorsanız @tailwindcss/postcss paketini tercih edin; ikisini aynı projede karıştırmayın.

2. Vite yapılandırmasına eklentiyi ekle

// vite.config.js
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

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

Beklenen davranış: Geliştirme sunucusu açıldığında CSS çıktısı otomatik üretilir; ayrı bir PostCSS zinciri kurmanız gerekmez.

3. CSS girişini sadeleştir

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

v3'teki @tailwind base; @tailwind components; @tailwind utilities; üçlüsü yerine tek satır @import kullanılır. Eski direktifleri bırakmak, beklenmeyen çıktıya yol açar.

4. Temayı CSS üzerinden tanımla

@import "tailwindcss";

@theme {
  --color-brand-500: oklch(0.62 0.19 260);
  --font-display: "Inter", sans-serif;
  --spacing-gutter: 1.25rem;
}

Beklenen davranış: bg-brand-500, font-display ve p-gutter gibi yardımcı sınıflar bu değişkenlerden türetilir. Aynı değişkenleri kendi CSS'inizde var(--color-brand-500) ile kullanabilirsiniz; tek kaynak, iki tüketim.

Yaygın Hatalar

• Eski @tailwind direktiflerini bırakmak. v4 girişinde @import "tailwindcss"; beklenir. Karışık kullanım derleme hatası veya eksik çıktı üretir.
• tailwind.config.js içindeki tüm tema değerlerinin otomatik taşınacağını sanmak. CSS-first yaklaşıma geçerken tema tanımını gözden geçirmeniz gerekir; JavaScript yapılandırması hâlâ desteklenen senaryolar var, ancak varsayım yapmayın.
• Dinamik sınıf adları. bg-${color}-500 gibi şablon string'leri hâlâ güvenilir değildir. Tam sınıf adlarını yazın veya güvenli listeye ekleyin.
• İçerik taramasını tamamen unutmak. Otomatik algılama çoğu durumu kapsar; monorepo veya alışılmadık klasör yapılarında @source ile açıkça yol vermeniz gerekebilir.
• PostCSS ve Vite eklentisini aynı anda kullanmak. Tek bir entegrasyon yolu seçin.

Güvenlik ve Üretim Notları

Tailwind bir CSS üreticisidir; çalışma zamanı güvenlik açığı yüzeyi tipik olarak küçüktür. Yine de iki noktaya dikkat edin:

• Kullanılmayan sınıfların ayıklanması. v4'te otomatik tarama, kullanılmayan yardımcı sınıfları çıktıdan çıkarır. Bu, çıktı boyutunu küçültür ama aynı zamanda "CSS'te vardı, neden kayboldu?" sürprizlerinin kaynağıdır. Üretim öncesi gerçek sayfalarda görsel doğrulama yapın.
• Tema değişkenlerinde gizli veri. @theme bloğuna marka renkleri veya tasarım token'ları koymak normaldir; ancak API anahtarı, kullanıcıya özel URL gibi değerleri buraya koymayın. CSS çıktısı istemciye açıktır.
• Bağımlılık zinciri. Yeni eklenti paketleri (@tailwindcss/vite, @tailwindcss/postcss) sürüm kilidi ile sabitlenmeli; kilit dosyasını sürüm kontrolünde tutun.

Performans Tarafında Ne Beklemeli?

Yeniden yazılan motor, tarama ve üretim adımlarını hızlandırmayı hedefler. Pratikte gözlemleyebileceğiniz etkiler:

• Artımlı derlemede daha kısa geri bildirim. Sınıf ekleyip kaydettiğinizde tarayıcıya yansıma süresi kısalır.
• Daha küçük çıktı. Kullanılmayan yardımcı sınıfların ayıklanması ve değişken tabanlı tema, tekrar eden tanımları azaltır.
• Daha az yapılandırma. content listesini elle yönetme ihtiyacının azalması, yanlış yapılandırmadan kaynaklanan "sınıf üretilmedi" hatalarını düşürür.

Bu kazanımların büyüklüğü projenin boyutuna, kullandığınız entegrasyona ve tema karmaşıklığına bağlıdır. Kendi projenizde ölçmeden kesin bir yüzde söylemek doğru olmaz; üretim derlemenizi v3 ve v4 için ayrı ayrı çalıştırıp çıktı boyutunu ve süreyi karşılaştırın.

Geçişte Pratik Kontrol Listesi

1. Paketleri ve entegrasyon eklentisini güncelleyin, ikisini karıştırmayın.
2. CSS girişini @import "tailwindcss"; olacak şekilde sadeleştirin.
3. Tema değerlerini @theme bloğuna taşıyın; kullandığınız özel token'ları tek tek doğrulayın.
4. Dinamik sınıf üreten yerleri gözden geçirin, gerekirse @source inline(...) ile açıkça listeyin.
5. Geliştirme ve üretim derlemesini çalıştırıp çıktı boyutunu ve görsel doğruluğu karşılaştırın.
6. Kilit dosyasını güncelleyip sürümü sabitleyin.

Kapanış

v4'ün asıl kazanımı, tek tek özelliklerden çok yapılandırma modelinin değişmesi: tema artık CSS'in kendi dilinde tanımlanıyor, tarama büyük ölçüde otomatikleşiyor ve motor yeniden yazıldığı için derleme akışı sadeleşiyor. Geçişin riski de tam burada: eski alışkanlıkları (direktifler, content listesi, JS ağırlıklı tema) olduğu gibi taşımak yerine yeni modele uyarlamak gerekiyor. Sürüme özel ayrıntılar için resmi dokümantasyonu ve sürüm notlarını esas alın; bu rehberdeki adımlar mimari farkları anlamak için bir çerçeve sunar, sürüm numarası iddiası taşımaz.