Tailwind CSS v4: Geçiş Kılavuzu ve Yeni Özellikler

Tailwind CSS v4, çerçevenin piyasaya sürülmesinden bu yana yapılan en önemli yeniden yazımdır. JavaScript yapılandırma dosyası kaldırıldı; yerini özel özelliklerin kullanıldığı CSS öncelikli yapılandırma aldı. Sınıf API'si büyük ölçüde değişmedi, ancak dahili bileşenler tamamen yeni: Rust tabanlı bir motor (oxide), P3 renk gamı ​​için birinci sınıf destek, yerel kapsayıcı sorguları ve PostCSS eklentileri yerine doğrudan CSS ile entegre olan bir derleme hattı.

Bu kılavuz size neyin değiştiğini, neden değiştiğini ve gerçek bir üretim uygulamasının Tailwind v3'ten v4'e nasıl geçirileceğini açıklamaktadır. Sizi şaşırtacak son değişiklikleri ve hemen benimsemeye değer yeni özellikleri ele alacağız.

Önemli Çıkarımlar

• tailwind.config.js kullanımdan kaldırıldı — yapılandırma, @theme yönergesi kullanılarak CSS'ye taşınıyor
• İçe aktarma @tailwind base/components/utilities yerine tek bir @import "tailwindcss" olarak değiştirildi
• Özel renkler artık --color-* ad alanı altındaki CSS özel özelliklerini kullanıyor
• content yapılandırması otomatiktir — Tailwind v4, dosyaları glob aracılığıyla otomatik olarak tarar
• Kapsayıcı sorguları artık @container ve @sm:, @lg: değişkenleriyle yerleşiktir
• Tüm yerleşik renkler için oklch() renk alanı aracılığıyla P3 renk gamı desteği
• @apply hala çalışıyor ancak CSS özel özellikleriyle daha az gerekli
• JIT motorunun yerini Oksit (Pas) aldı — çok daha hızlı derleme

---

Ne Değişti ve Neden

Tailwind v3, PostCSS'yi bir işlem hattı, bir JavaScript yapılandırma dosyası olarak kullandı ve JavaScript ile yazılmış bir JIT motoru aracılığıyla yardımcı program sınıfları oluşturdu. Bu iyi çalıştı ancak sınırlamaları vardı:

• Yapılandırma JavaScript gerektirdiğinden, yalnızca CSS araçlarından erişilemez hale gelir
• Özel özelliklerin Tailwind yapılandırmasından ayrı olarak ayarlanması gerekiyordu
• Konteyner sorguları bir eklenti gerektiriyordu
• Renk sistemi P3 gamını desteklemiyordu

Tailwind v4, yapılandırmayı CSS'nin kendisine taşıyarak, tarayıcının yerel CSS özel özellik sistemini kullanarak ve 5-10 kat daha hızlı derlemeler için motoru Rust'ta yeniden yazarak tüm bunları ele alıyor.

---

Kurulum

# Tailwind v4
pnpm add tailwindcss@^4.0.0 @tailwindcss/vite

# For Next.js
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

@tailwindcss/vite eklentisi doğrudan Vite ile entegre olur. Next.js için (PostCSS'yi dahili olarak kullanan), @tailwindcss/postcss kullanın.

---

CSS-İlk Yapılandırma

Bu en büyük kavramsal değişikliktir. globals.css kodunuz Tailwind konfigürasyonu için gerçeğin kaynağı haline gelir:

/* Before: globals.css with v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After: globals.css with v4 */
@import "tailwindcss";

/* Theme configuration replaces tailwind.config.js */
@theme {
  /* Custom colors as CSS custom properties */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-100: oklch(94% 0.04 250);
  --color-brand-500: oklch(62% 0.18 250);
  --color-brand-900: oklch(28% 0.09 250);

  /* Custom font families */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom shadows */
  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%), 0 1px 2px oklch(0% 0 0 / 8%);
}

tailwind.config.js kodunuz silinebilir (veya şimdilik saklanabilir; v4, geçiş sırasında her ikisini de destekler).

---

İçerik Algılama

Tailwind v4 şablon dosyalarını otomatik olarak algılar. V3'te titizlikle koruduğunuz content yapılandırması artık yok:

// v3 tailwind.config.js — you needed this
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
}

v4'te Tailwind projenizi mantıklı varsayılanları kullanarak otomatik olarak tarar. Alışılmadık konumlarda dosyalarınız varsa bunları açıkça ekleyebilirsiniz:

@import "tailwindcss";
@source "../scripts/*.ts"; /* Scan additional paths */
@source "../../packages/ui/src/**/*.tsx"; /* Monorepo workspace packages */

---

CSS Yapılandırma Güncellemesi Sonrası

Next.js projeleri (ve herhangi bir PostCSS tabanlı kurulum) için PostCSS yapılandırmanızı güncelleyin:

// Before: postcss.config.js with v3
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// After: postcss.config.mjs with v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

autoprefixer varsayılan olarak @tailwindcss/postcss'e dahil edilmiştir. Ayrı autoprefixer bağımlılığını kaldırın.

---

Renk Sistemi: OKLCH

Tailwind v4, yerleşik renk paleti için OKLCH'yi kullanır. OKLCH algısal olarak tekdüze bir renk alanıdır; HSL'den farklı olarak açıklığın ayarlanması aslında insan gözüne eşit adımlar gibi görünür.

/* v4 colors use OKLCH internally */
/* bg-blue-500 generates: */
background-color: oklch(62.8% 0.258 264.1);

/* Custom colors with OKLCH */
@theme {
  --color-ecosire-amber: oklch(78% 0.18 80);
  --color-ecosire-navy: oklch(22% 0.04 250);
}

OKLCH, daha geniş ekran gamına sahip ekranlar için (çoğu modern telefon ve Mac), sRGB'nin temsil edemeyeceği renkleri etkinleştirir. P3'ü desteklemeyen ekranlar için oklch() değerleri otomatik olarak rgb() değerine dönüştürülür.

---

Kapsayıcı Sorguları — Yerleşik

Kapsayıcı sorguları artık v4'te birinci sınıftır. Eklentiye gerek yok:

/* Define a container */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

<!-- Responsive based on parent container, not viewport -->
<div class="card-wrapper">
  <div class="@sm:flex-row @lg:grid-cols-3 flex flex-col">
    <!-- Layout changes based on container width, not screen width -->
  </div>
</div>

Bu, bileşen düzeyinde yanıt verme olanağı sağlar; bir kenar çubuğu kartı ve tam genişlikli bir kart, ayrı CSS olmadan farklı düzenlere sahip olabilir.

Adlandırılmış kapsayıcılar belirli ataları hedeflemenize olanak tanır:

<div class="card-wrapper [container-name:card]">
  <div class="@card/sm:text-lg text-base">
    Responsive to the 'card' container
  </div>
</div>

---

CSS Özel Özellikler Entegrasyonu

@theme'da tanımlanan özel özelliklere her yerden erişilebilir: CSS, JavaScript ve CSS değişkenlerini okuyan tasarım araçları:

@theme {
  --color-primary: oklch(62% 0.18 250);
  --spacing-section: 5rem;
}

// Access in JavaScript/TypeScript
const style = getComputedStyle(document.documentElement);
const primary = style.getPropertyValue('--color-primary');

<!-- Use in inline styles -->
<div style={{ color: 'var(--color-primary)' }}>
  Themed content
</div>

Bu, tailwind.config.js ve tokens.ts dosyasındaki paralel değerleri koruma modelinin yerini alır; artık CSS'de tek bir doğruluk kaynağı vardır.

---

Son Değişiklikler

1. Eklenti API değişiklikleri

addBase, addComponents, addUtilities kullanan v3 eklentileri v4 ile uyumlu değildir. Yeni katman sistemini kullanarak bunları CSS olarak yeniden yazın:

/* v3 plugin equivalent in v4 CSS */
@layer base {
  h1 {
    @apply text-3xl font-bold;
  }
}

@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium;
  }
}

2. @apply özel sınıflarla

Tailwind olmayan sınıflara sahip @apply v4'te daha kısıtlıdır. @apply öğesini yalnızca gerçek yardımcı program sınıflarıyla kullanın:

/* This works in v4 */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg;
}

/* This is deprecated — use regular CSS instead */
.btn-primary {
  @apply custom-shadow; /* custom-shadow is not a Tailwind utility */
}

3. tailwind.config.js theme.extend gitti

JS'deki yapılandırma artık birincil yol değil. CSS'de @theme kullanın. Her ikisine de sahipseniz CSS yapılandırması öncelikli olur.

4. Varsayılan renk paleti adlandırma

V4'te birkaç renk adı değiştirildi. Onları yakalamak için resmi kod modunu çalıştırın:

npx @tailwindcss/upgrade@next --config tailwind.config.js

---

Göç Stratejisi

Büyük bir üretim uygulaması için aşamalı olarak geçiş yapın:

Aşama 1: Güncelleme yüklemesi

pnpm remove tailwindcss autoprefixer postcss
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

postcss.config.mjs güncellemesini yapın:

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

globals.css güncellemesini yapın:

/* Replace the three @tailwind directives */
@import "tailwindcss";

Aşama 2: Codemod'u çalıştırın

npx @tailwindcss/upgrade@next

Bu, geçişin çoğunu otomatik hale getirir: renk adlarını günceller, yapılandırmayı CSS'ye dönüştürür ve manuel olarak ilgilenilmesi gereken sorunları işaretler.

Aşama 3: Yapılandırmayı CSS'ye taşıyın

tailwind.config.js tema değerlerinizi alın ve bunları CSS'nizdeki @theme dizinine taşıyın. Doğrulamadan sonra yapılandırma dosyasını silin.

4. Aşama: Yeni özellikleri benimseyin

Uygun olduğunda görünüm tabanlı duyarlı kesme noktalarını kapsayıcı sorgularla değiştirin. P3 gamı ​​desteği kazanmak amacıyla özel renkler için OKLCH'yi benimseyin.

---

Performans İyileştirmeleri

Tailwind v4'ün Oksit motoru (Rust) ölçülebilir derecede daha hızlı yapılar sunar:

Büyük uygulamalar için bu, geliştirme aşamasında gözle görülür derecede daha hızlı HMR ve önemli ölçüde daha kısa CI oluşturma süreleri anlamına gelir.

---

Gerçek Dünyadan Geçiş Örneği

İşte bir tasarım sisteminin temel konfigürasyonu için pratik bir öncesi/sonrası:

// Before: tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef3c7',
          500: '#f59e0b',
          900: '#78350f',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
      },
      boxShadow: {
        card: '0 1px 3px rgba(0,0,0,0.12)',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
};

/* After: globals.css (v4) */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

@theme {
  --color-brand-50: oklch(97% 0.04 85);
  --color-brand-500: oklch(78% 0.18 85);
  --color-brand-900: oklch(33% 0.08 85);

  --font-sans: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%);
}

CSS'ye özgü yapılandırma daha özlüdür ve yapılandırmayı okumak için node_modules bağımlılığını ortadan kaldırır.

---

Sıkça Sorulan Sorular

tailwind.config.js dosyasını hemen silmem gerekiyor mu?

Hayır — Tailwind v4, geçiş sırasında hem JS yapılandırmasını hem de CSS yapılandırmasını aynı anda destekler. JS yapılandırması hala çalışıyor ancak CSS'deki @theme gibi özellikler yalnızca JS olmadan kullanılabilir. Aşamalı olarak geçiş yapın: önce v4 ile uygulama oluşturmayı edinin, ardından yapılandırmayı yavaş yavaş CSS'ye taşıyın, ardından kendinize güvendiğinizde JS yapılandırmasını silin.

Mevcut Tailwind v3 sınıflarım v4'te çalışmaya devam edecek mi?

Yardımcı program sınıflarının büyük çoğunluğu değişmedi. Bazı renk adları güncellendi (bazı bağlamlarda gri → nötr) ve kullanımdan kaldırılan birkaç yardımcı program kaldırıldı. Çoğu sorunu otomatik olarak yakalamak için npx @tailwindcss/upgrade@next komutunu çalıştırın. Ana uyumsuzluklar eklentilerde ve özel tema yapılandırmasındadır, HTML/JSX'teki sınıfları nasıl kullandığınızda değil.

OKLCH tüm tarayıcılarda destekleniyor mu?

OKLCH tüm modern tarayıcılarda desteklenir (Chrome 111+, Firefox 113+, Safari 15.4+). Tailwind v4, gerektiğinde eski tarayıcılar için yedekler oluşturur. P3 renk gamı ​​(genişletilmiş renkler) için destek, hem geniş gamlı bir ekran hem de destekleyici bir tarayıcı gerektirir; Tailwind, daha dar gamlı ekranlar için rgb() geri dönüşler oluşturur.

Tailwind v4'ü shadcn/ui ile nasıl kullanırım?

shadcn/ui 2.0+, Tailwind v4'ü destekler. components.json kodunuzu v4 CSS değişkenleri biçimini kullanacak şekilde güncelleyin. Bileşen kitaplığı, temalandırma için doğal olarak Tailwind v4'ün @theme sistemiyle eşleşen CSS özel özelliklerini kullanır. V4 uyumlu yapılandırmayı elde etmek için mevcut bir projede npx shadcn@latest init komutunu çalıştırın.

Yeni yapılandırma için TypeScript türleri var mı?

Tailwind v4'ün yapılandırması CSS'dir, dolayısıyla yapılandırmanın kendisi için TypeScript türü yoktur. IDE desteği, özel özellikleri anlayan CSS dil hizmetlerinden gelir. TypeScript'teki tema değerlerine erişmek için (Grafikler, animasyonlar vb. için), çalışma zamanında CSS özel özelliklerini okumak üzere getComputedStyle kullanın veya derlemenizin bir parçası olarak CSS'nizden bir belirteç dosyası oluşturun.

---

Sonraki Adımlar

Tailwind CSS v4, yeni projeler için benimsenmeye ve mevcut projeler için planlama yapmaya değer önemli bir yükseltmedir. ECOSIRE'ın ön uç yığını, kapsamlı bir tasarım sistemiyle 249 sayfalık Next.js 16 uygulamasında Tailwind CSS v4.1'i üretimde çalıştırıyor.

Tailwind v4 geçişi konusunda yardıma mı ihtiyacınız var veya sıfırdan oluşturulmuş bir tasarım sistemi mi istiyorsunuz? Nasıl yardımcı olabileceğimizi görmek için ön uç mühendislik hizmetlerimizi keşfedin.