shadcn/ui projesini Tailwind v4'e yükseltmek: adım adım geçiş

Tailwind v4 ile shadcn/ui'de neler değişti?

Changelog'a göre Tailwind v4 ve React 19 desteğinin ilk önizlemesi Şubat 2025'te yayımlandı. Tailwind v4 sayfası değişiklikleri şöyle sıralar:

• CLI artık projeleri Tailwind v4 ile başlatabiliyor.
• Yeni @theme yönergesi ve @theme inline seçeneği tam destekleniyor.
• Tüm bileşenler Tailwind v4 ve React 19 için güncellendi.
• forwardRef kullanımları kaldırıldı ve türler buna göre düzenlendi.
• Her ilkel parça artık stil için bir data-slot özniteliğine sahip.
• Bileşen stilleri düzeltildi ve sadeleştirildi.
• toast bileşeni sonner lehine kullanımdan kaldırılıyor.
• Düğmeler artık varsayılan imleci kullanıyor.
• default stili kullanımdan kaldırılıyor; yeni projeler new-york kullanacak.
• HSL renkleri OKLCH'ye dönüştürüldü.

Sayfa bu değişikliğin geriye dönük uyumu bozmadığını özellikle vurgular: Tailwind v3 ve React 18 kullanan uygulamalarınız çalışmaya devam eder. Siz yükseltene kadar yeni eklediğiniz bileşenler de v3 ve React 18 uyumlu olarak gelir; yalnızca yeni projeler Tailwind v4 ve React 19 ile başlar. Sayfanın "Try It Out" bölümünde CLI'nin canary sürümünden söz edilmesi, metnin önizleme döneminde yazıldığını gösterir. React 19 sayfasındaki güncel not ise tam desteğin latest sürümde olduğunu söyler; bu yüzden komutlarda npx shadcn@latest kullanın.

Neden elle yükseltme mümkün?

Tailwind v4 sayfası, shadcn/ui'nin büyük avantajlarından birinin elinizdeki kodun kendi yazacağınız kodun aynısı olması olduğunu söyler; arada gizli bir soyutlama yoktur. Bu yüzden bir bağımlılık yeni sürüm çıkardığında o bağımlılığın resmi yükseltme yolunu izlersiniz. shadcn/ui'nin yaptığı, bileşen dosyalarında ve globals.css içinde nelerin değişmesi gerektiğini adım adım göstermektir. Belgenin kendisi de tam belgelerin yolda olduğunu not eder; aşağıdaki adımlar sayfada yazan kadarıdır.

1. Tailwind'in yükseltme rehberini uygulayın

İlk adım Tailwind'in resmi yükseltme rehberini izlemektir. Rehber, kullanımdan kalkan yardımcı sınıfları kaldıran ve Tailwind yapılandırmasını güncelleyen @tailwindcss/upgrade@next codemod'unu kullanmanızı önerir. Bu adımın ayrıntıları Tailwind'e aittir; shadcn/ui tarafında asıl iş codemod'dan sonra başlar.

2. CSS değişkenlerini güncelleyin

Codemod, CSS değişkenlerinizi @theme yönergesi altında referanslar olarak taşır. Sonuç çalışır ama renkler hâlâ @layer base içinde çıplak HSL değerleri olarak durur ve hsl() sarmalayıcısı @theme içindedir:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 0 0% 3.9%;
  }
}

@theme {
  --color-background: hsl(var(--background));
  --color-foreground: hsl(var(--foreground));
}

Belge, renklerle ve diğer değişkenlerle çalışmayı kolaylaştırmak için dört değişiklik ister: :root ve .dark bloklarını @layer base dışına taşıyın, renk değerlerini hsl() ile sarın, @theme yönergesine inline seçeneğini ekleyin ve @theme içindeki hsl() sarmalayıcılarını kaldırın. Sonuç:

:root {
  --background: hsl(0 0% 100%);
  --foreground: hsl(0 0% 3.9%);
}

.dark {
  --background: hsl(0 0% 3.9%);
  --foreground: hsl(0 0% 98%);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

Bu düzenle değişken artık tam bir renk değeri taşır. Belgeye göre bu, tema değişkenlerine hem yardımcı sınıflarda hem de CSS dışında, örneğin JavaScript içinde renk değeri olarak erişmeyi çok daha basit hale getirir. Örnekte yalnızca iki değişken var; kendi dosyanızda bu işlemi tüm renk değişkenlerine uygulamanız gerekir. Değişkenlerin tam listesi shadcn tema yazısında. Belgedeki asıl blokta satır sonlarında // <-- Wrap in hsl gibi açıklamalar bulunur; CSS'te // geçerli bir yorum biçimi olmadığı için bunları kendi dosyanıza kopyalamayın.

3. Grafik renklerini güncelleyin

Tema renkleri artık hsl() ile birlikte geldiği için grafik yapılandırmanızdaki sarmalayıcı gereksizdir. chartConfig nesnesinde hsl(var(--chart-1)) yerine doğrudan var(--chart-1) yazarsınız:

const chartConfig = {
  desktop: {
    label: "Desktop",
    color: "var(--chart-1)",
  },
  mobile: {
    label: "Mobile",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig

Bu değişikliği unutursanız renk değeri hsl(hsl(...)) gibi geçersiz bir ifadeye dönüşür ve grafikler renksiz görünebilir. ChartConfig yapısının geri kalanı shadcn chart yazısında.

4. size-* yardımcısını kullanın

Tailwind v3.4 ile eklenen size-* sınıfı artık tailwind-merge tarafından tam desteklenir. Bu yüzden genişlik ve yüksekliği aynı olan öğelerde iki sınıf yerine tek sınıf yazabilirsiniz: w-4 h-4 yerine size-4. Bu adım zorunlu değildir ama cn() ile birleştirmeyi ve okumayı kolaylaştırır; cn ile tailwind-merge ilişkisi cn fonksiyonu yazısında. Güncel bileşen kaynaklarında da bu biçim kullanılır; örneğin button.tsx içindeki ikon boyutları size-9, size-8 ve size-10 olarak yazılmıştır.

5. Bağımlılıkları güncelleyin

Belge, Radix paketlerini ve bileşenlerin kullandığı diğer kütüphaneleri tek komutla en son sürüme çekmeyi önerir. Komut pnpm ile yazılmıştır; başka bir paket yöneticisi kullanıyorsanız aynı paketleri kendi güncelleme komutunuzla yükseltin:

pnpm up "@radix-ui/*" cmdk lucide-react recharts tailwind-merge clsx --latest

React 19'a da geçiyorsanız npm kullanıcıları bu aşamada peer dependency uyarılarıyla karşılaşabilir; çözüm seçenekleri React 19 peer dependency yazısında. Haziran 2025'ten beri ayrı @radix-ui/react-* paketleri yerine birleşik radix-ui paketine geçmek için npx shadcn@latest migrate radix komutu da vardır; bkz. shadcn CLI komutları.

6. forwardRef yapısını kaldırın

Bileşenlerinizdeki forwardRef kullanımlarını React ekibinin remove-forward-ref codemod'uyla ya da elle kaldırabilirsiniz. Elle yapmak için belgedeki adımlar şunlardır: React.forwardRef<...> yerine React.ComponentProps<...> kullanın, bileşenden ref={ref} satırını kaldırın, stil için işe yarayacak bir data-slot özniteliği ekleyin ve isterseniz bileşeni adlandırılmış bir fonksiyona çevirip displayName satırını silin. Belgedeki AccordionItem örneğinin öncesi:

const AccordionItem = React.forwardRef<
  React.ElementRef<typeof AccordionPrimitive.Item>,
  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Item>
>(({ className, ...props }, ref) => (
  <AccordionPrimitive.Item
    ref={ref}
    className={cn("border-b last:border-b-0", className)}
    {...props}
  />
))
AccordionItem.displayName = "AccordionItem"

Ve sonrası:

function AccordionItem({
  className,
  ...props
}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
  return (
    <AccordionPrimitive.Item
      data-slot="accordion-item"
      className={cn("border-b last:border-b-0", className)}
      {...props}
    />
  )
}

Dönüşümden sonra bileşen yine ref kabul eder; çünkü React.ComponentProps türü ref dahil tüm propları kapsar ve {...props} ile alttaki ilkele aktarılır. data-slot değerinin adı, güncel kaynaktaki adlandırmayı izlemelidir: bileşen adı küçük harfle ve tire ile yazılır. Bu dönüşüm React 19 ile ilgilidir; React temel kavramları için React rehberine bakabilirsiniz.

tailwindcss-animate yerine tw-animate-css

Tailwind v4 sayfasının changelog bölümüne göre 19 Mart 2025'te tailwindcss-animate kullanımdan kaldırıldı ve yerine tw-animate-css geldi. Yeni projelerde bu paket varsayılan olarak kurulur. Var olan projeler için dört adım vardır: tailwindcss-animate paketini bağımlılıklardan kaldırın, globals.css içindeki @plugin 'tailwindcss-animate' satırını silin, tw-animate-css paketini geliştirme bağımlılığı olarak kurun ve globals.css dosyasına içe aktarmasını ekleyin:

/* kaldırın */
@plugin 'tailwindcss-animate';

/* ekleyin */
@import "tw-animate-css";

Manuel kurulum sayfasındaki güncel globals.css dosyası da @import "tailwindcss"; satırının hemen ardından @import "tw-animate-css"; ile başlar. Güncel kaynakta dialog.tsx, dropdown-menu.tsx, sheet.tsx, popover.tsx ve tooltip.tsx gibi dosyalar açılış ve kapanış için animate-in ve fade-in-0 gibi animasyon sınıfları kullanır; bu sınıflar animasyon paketinden geldiği için içe aktarmayı unutmak animasyonların kaybolmasına yol açar.

Yükseltmek yerine yeni proje başlatmak

Bazen var olan projeyi adım adım taşımak yerine Tailwind v4 ile yeni bir proje açıp bileşenleri oraya eklemek daha az iş çıkarır; özellikle bileşenlerde çok az değişiklik yaptıysanız. Tailwind v4 sayfası framework'e özel başlangıç rehberlerine bağlantı verir: Next.js, Vite, Laravel, React Router, Astro, TanStack Start, Gatsby ve elle kurulum. Bu rehberlerle başlatılan bir projede globals.css doğrudan @theme inline yapısıyla ve OKLCH değerleriyle gelir, tw-animate-css kuruludur ve bileşenler forwardRef içermez. Monorepo şablonu da belgeye göre React 19 ve Tailwind CSS v4 kullanır.

Bu yolu seçerseniz kendi düzenlediğiniz bileşen dosyalarını yeni projeye kopyalamadan önce yukarıdaki altıncı adımı onlara da uygulamanız gerekir; aksi halde forwardRef kullanan eski dosyalarla güncel dosyalar yan yana durur. Kurulum ayrıntıları için shadcn kurulumu ve init, Next.js kurulumu ve Vite kurulumu yazılarına bakabilirsiniz. Hangi yolu seçerseniz seçin, yükseltmeden sonra uygulamanızı açık ve koyu temada tek tek gözden geçirmek, renk ve animasyon sorunlarını erken yakalamanın en kısa yoludur.

Yeni koyu tema renkleri

12 Mart 2025 notuna göre koyu tema renkleri daha erişilebilir olacak şekilde yeniden ele alındı. Bu güncelleme yalnızca doğrudan Tailwind v4 ile başlatılmış projeler içindir; v3'ten yükseltilmiş projeler etkilenmez ve eski koyu renkleri kullanmaya devam edebilir. Uygulamak isterseniz belgedeki sıra şöyledir:

git add .
git commit -m "..."
npx shadcn@latest add --all --overwrite

CLI tüm bileşenlerinizin üzerine yazacağı için önce değişikliklerinizi commit etmeniz istenir. Bileşenler güncellendikten sonra globals.css içindeki koyu tema renklerini tema belgesinin temel renkler listesindeki yeni OKLCH değerleriyle değiştirirsiniz. Son adım, git farkına bakıp bileşenlerde daha önce yaptığınız değişiklikleri yeniden uygulamaktır.

Yükseltme kontrol listesi

Sık yapılan hatalar

• Sadece Tailwind codemod'unu çalıştırıp durmak: Proje derlenir ama değişkenler @layer base içinde çıplak HSL olarak kalır.
• Değerleri hsl() ile sarıp @theme içindeki sarmalayıcıyı bırakmak: Renk çift sarılır ve geçersiz olur.
• chartConfig'i unutmak: Grafik renkleri bozulur.
• Belgedeki // açıklamalarını CSS'e kopyalamak: CSS bu yorum biçimini tanımaz.
• tailwindcss-animate eklentisini bırakmak: Kullanımdan kaldırılmıştır; tw-animate-css içe aktarmasını ekleyin.
• Yükseltilmiş projeye yeni koyu renk akışını uygulamak: Bu akış yalnızca Tailwind v4 ile başlatılmış projeler için tanımlanmıştır.
• --overwrite öncesi commit almamak: Bileşenlerdeki kendi değişiklikleriniz kaybolur.

Sık Sorulan Sorular

Tailwind v3 projemi hemen yükseltmek zorunda mıyım?

Hayır. Belgeye göre değişiklik geriye dönük uyumu bozmaz; Tailwind v3 ve React 18 ile çalışan uygulamalar çalışmaya devam eder ve yeni eklenen bileşenler de siz yükseltene kadar v3 uyumlu gelir.

Tailwind v4 projesinde components.json içinde tailwind.config ne olmalı?

Boş bırakılmalıdır. components.json belgesi Tailwind v4 için tailwind.config alanının boş kalmasını ister; ayrıntılar components.json ayarları yazısında.

HSL renklerimi OKLCH'ye çevirmem şart mı?

Belgedeki yükseltme adımları renkleri OKLCH'ye çevirmenizi istemez; ikinci adımın sonunda değerler hsl() ile sarılmış halde kalır ve bu düzen çalışır. OKLCH, yeni projelerin ve tema belgesindeki temel renk listesinin kullandığı biçimdir. 12 Mart 2025'teki yeni koyu tema renklerini almak isterseniz o değerler OKLCH olarak verildiği için bu noktada geçiş yapmış olursunuz; ancak bu akışın yalnızca doğrudan Tailwind v4 ile başlatılmış projeler için tanımlandığını unutmayın.

default stili kullanan bir projem var, ne yapmalıyım?

default stili kullanımdan kaldırıldı ve yeni projeler new-york ile başlar. style alanı da başlatmadan sonra değiştirilemediği için stil değişikliği pratikte bileşenleri yeni stille yeniden kurmak anlamına gelir.

Toast bileşenini kullanmaya devam edebilir miyim?

Belgeye göre toast bileşeni sonner lehine kullanımdan kaldırıldı. Var olan kodunuz çalışıyor olabilir ama yeni geliştirme için Sonner kullanmanız önerilir.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: shadcn/ui öğrenme rehberi · Tailwind CSS v4 yenilikleri · shadcn tema · React 19 uyumluluğu · cn ve data-slot · shadcn yenilikleri