shadcn/ui Manuel Kurulum: Bağımlılıklar, CSS, cn ve components.json

1. Tailwind CSS'i kurun

Bileşenler Tailwind CSS ile stillendirildiği için projenizde Tailwind bulunmalıdır. Manuel kurulum sayfası bu adım için Tailwind'in kendi kurulum belgesine yönlendirir; yani kullandığınız çatıya uygun Tailwind kurulumunu oradan yaparsınız. Sayfadaki CSS örneği @import "tailwindcss"; satırıyla başladığı için Tailwind v4 kurulumu varsayılır. Tailwind'in kendisini öğrenmek için Tailwind CSS rehberi yazısına bakabilirsiniz.

2. Bağımlılıkları ekleyin

Bileşenlerin ortak olarak ihtiyaç duyduğu paketler tek komutla kurulur:

npm install class-variance-authority clsx tailwind-merge lucide-react tw-animate-css

Her paketin projedeki rolü, depodaki bileşen kodundan ve belgelerden anlaşıldığı kadarıyla şöyledir:

Bu liste ortak bağımlılıklardır. Her bileşenin ayrıca kendi bağımlılıkları olabilir; örneğin Button için bileşen sayfasının manuel sekmesi @radix-ui/react-slot paketini ister. Bu ek paketleri bileşenleri eklerken kurarsınız (aşağıdaki yedinci adım).

3. Takma adı yapılandırın

Bileşen dosyaları birbirini ve yardımcı fonksiyonları @/ ile başlayan yollarla içe aktarır. Bu yolların çözülebilmesi için tsconfig.json dosyasına baseUrl ve paths alanları eklenir:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Bu örnekte @/* proje kökünü gösterir; yani @/lib/utils yolu kökteki lib/utils.ts dosyasına çözülür. Belge @ takma adının bir tercih olduğunu, isterseniz başka takma adlar kullanabileceğinizi belirtir. Farklı bir takma ad seçerseniz components.json içindeki aliases değerlerini de aynı biçimde yazmanız gerekir. Kodunuz src klasöründeyse eşlemeyi ./src/* olarak ayarlarsınız; paths ayarının TypeScript tarafı için TypeScript paths ve alias ayarları yazısına bakın. Vite gibi bazı araçlar takma adın ayrıca kendi yapılandırmalarında da tanımlanmasını ister (Vite kurulumu).

4. Global CSS dosyasını yazın

Dördüncü adım en uzun olanıdır: tema değişkenlerini global CSS dosyanıza eklersiniz. Belgedeki örnek dosya src/styles/globals.css adını taşır. Dosyanın tamamı yaklaşık 120 satırdır; yapısını görmek için kısaltılmış hâlini aşağıda veriyoruz:

@import "tailwindcss";
@import "tw-animate-css";

@custom-variant dark (&:is(.dark *));

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  /* card, popover, secondary, muted, accent, destructive, border, input, ring, chart-1..5, sidebar-* */
  --radius: 0.625rem;
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  /* ... */
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  /* ... */
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

Dosya beş bölümden oluşur. İlk iki satır Tailwind'i ve animasyon paketini içe aktarır. @custom-variant dark satırı karanlık mod varyantını .dark sınıfına bağlar. :root bloğu açık tema renklerini, .dark bloğu ise aynı değişkenlerin karanlık tema değerlerini tanımlar; renkler oklch() biçimindedir. @theme inline bloğu bu değişkenleri Tailwind'e tanıtır: örneğin --color-background tanımı sayesinde bg-background sınıfı kullanılabilir hâle gelir. Son olarak @layer base bloğu tüm öğelere varsayılan kenarlık ve odak halkası rengini, body öğesine de arka plan ve yazı rengini verir.

Bu yapının ayrıntıları serinin başka yazılarında anlatılıyor: değişkenlerin anlamı ve yeni renk ekleme tema ve CSS değişkenleri yazısında, karanlık mod geçişi dark mode kurulumu yazısında. CSS değişkenlerinin ve oklch renk biçiminin CSS tarafı için CSS değişkenleri ve CSS renk değerleri yazılarına bakabilirsiniz. Değerlerin tamamını belge sayfasından kopyalamanızı öneririz; elle eksik bırakılan bir değişken, onu kullanan bileşenin rengini bozar.

5. cn yardımcısını ekleyin

Neredeyse her bileşen sınıf adlarını cn fonksiyonuyla birleştirir. Bu fonksiyon lib/utils.ts dosyasında tanımlanır:

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Fonksiyon önce clsx ile koşullu sınıfları tek bir dizeye çevirir, sonra twMerge ile çakışan Tailwind sınıflarını ayıklar. Böylece bir bileşene dışarıdan verdiğiniz className, bileşenin kendi sınıflarıyla çakıştığında beklediğiniz sınıf geçerli olur. Bu davranışın örnekleri cn fonksiyonu yazısında.

6. components.json dosyasını oluşturun

Son hazırlık adımı proje köküne bir components.json dosyası koymaktır. Belgedeki örnek şöyledir:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Bu dosyada kendi projenize göre en sık değiştireceğiniz alanlar şunlardır: tailwind.css dördüncü adımda yazdığınız CSS dosyasının gerçek yolunu göstermelidir; rsc React Server Components kullanan bir projede, örneğin Next.js App Router'da true olmalıdır; aliases değerleri üçüncü adımdaki takma adla uyumlu olmalıdır. tailwind.config Tailwind v4 için boş bırakılır. Her alanın ayrıntısı components.json ayarları yazısında.

7. Bileşenleri elle eklemek

Belge altıncı adımdan sonra "artık bileşen eklemeye başlayabilirsiniz" der. Bunu CLI ile add komutu üzerinden yapabilir ya da tamamen elle sürdürebilirsiniz. Her bileşen sayfasının kurulum bölümünde "CLI" ve "Manual" adlı iki sekme vardır. Manual sekmesi üç adımlı aynı kalıbı izler: bileşenin bağımlılıklarını kurun, bileşen kodunu projenize kopyalayın, içe aktarma yollarını proje yapınıza göre güncelleyin. Button için bu adımlar şöyledir:

npm install @radix-ui/react-slot

Ardından bileşen sayfasında gösterilen kaynak kodu components/ui/button.tsx dosyasına yapıştırırsınız. Kodun başındaki içe aktarmalar şöyle görünür; @/lib/utils yolu, beşinci adımda oluşturduğunuz dosyayı gösterir:

import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

Farklı bir takma ad ya da klasör yapısı kullanıyorsanız "içe aktarma yollarını güncelleyin" adımı tam olarak bu satırlar içindir: @/lib/utils yolunu kendi yapınıza göre değiştirirsiniz. Depodaki örnek dosyalar @/registry/new-york-v4/ui/button gibi depo içi yollar kullanır; bunları kendi projenizde @/components/ui/button biçimine çevirmeniz gerekir. Bileşeni kullanmak artık her kurulumdakiyle aynıdır:

import { Button } from "@/components/ui/button"

export function KaydetButonu() {
  return <Button variant="outline">Kaydet</Button>
}

Başka bileşene ihtiyaç duyan bileşenler

Bazı bileşenlerin manual sekmesinde üç standart adımın arasına bir adım daha girer. Calendar sayfası buna iyi bir örnektir: önce react-day-picker ve date-fns paketlerini kurarsınız, sonra projenizde Button bileşeninin bulunduğundan emin olursunuz, çünkü Calendar kendi içinde Button'ı kullanır. Ancak bundan sonra Calendar kodunu kopyalayıp içe aktarma yollarını güncellersiniz.

npm install react-day-picker date-fns

CLI ile kurulumda bu tür bileşenler arası bağımlılıklar otomatik çözülür; elle kurulumda ise her sayfadaki adımları sırasıyla izlemeniz gerekir. Benzer biçimde Sidebar ve Chart sayfalarının manual sekmeleri CSS dosyanıza belirli renk değişkenlerini eklemenizi ister. Bu yazıdaki global CSS örneği --sidebar-* ve --chart-1 ile --chart-5 arasındaki değişkenleri zaten içerir; yine de bileşen sayfasındaki listeyle kendi dosyanızı karşılaştırmanızda fayda var. Bu bileşenler Calendar, Sidebar ve Chart yazılarında ayrıntılı anlatılıyor.

Kurulum bittiğinde proje yapısı

Altı hazırlık adımı ve ilk bileşenden sonra, belgedeki örnek yollar ve kök klasörü gösteren @/* takma adıyla projenizde şu dosyalar bulunur:

• tsconfig.json: baseUrl ve paths ile takma ad.
• src/styles/globals.css: Tailwind içe aktarması, tema değişkenleri, @theme inline ve @layer base.
• lib/utils.ts: cn fonksiyonu.
• components.json: CLI için ayarlar, isteğe bağlı.
• components/ui/button.tsx: elle kopyaladığınız ya da add ile eklediğiniz bileşen.

Belgedeki örnekte CSS dosyası src altında, lib ve components ise kökte gösterilir. Kendi projenizde hepsini aynı düzende tutmak, örneğin hepsini src altına almak, takma adları ve components.json değerlerini daha kolay yönetilir kılar. Hangi düzeni seçerseniz seçin, takma ad, aliases değerleri ve tailwind.css yolu birbiriyle tutarlı olmalıdır.

Var olan bir tasarım sistemine eklemek: prefix

Manuel kurulum çoğu zaman zaten kendi stilleri olan bir projede tercih edilir. Böyle bir projede shadcn/ui sınıflarının mevcut sınıflarla çakışmasından endişe ediyorsanız components.json içindeki tailwind.prefix alanına bakın. Aralık 2023 changelog kaydına göre özel bir Tailwind öneki tanımladığınızda CLI, bileşen eklerken yardımcı sınıfların başına bu öneki otomatik koyar; kayıt bunun Docusaurus ya da Nextra gibi mevcut projelere bileşen eklemeyi kolaylaştırdığını ve cn, cva ve CSS değişkenleriyle birlikte çalıştığını belirtir.

{
  "tailwind": {
    "prefix": "tw-"
  }
}

Bu otomatik ekleme CLI'ın işidir. Bileşenleri tamamen elle kopyalıyorsanız önekleri de sınıflara kendiniz eklemeniz gerekir; bu yüzden önek kullanan projelerde bileşenleri add komutuyla eklemek daha az hata riski taşır. Önekin Tailwind tarafındaki tanımı Tailwind'in kendi yapılandırmasına aittir.

Manuel kurulum ile init karşılaştırması

Tablonun gösterdiği gibi iki yol aynı sonuca varır. Manuel kurulumun avantajı her dosyayı bilerek oluşturmanız ve projenize hangi değişikliğin girdiğini tam olarak görmenizdir. Dezavantajı ise zaman ve hata riskidir: uzun CSS dosyasından bir değişkeni eksik kopyalamak ya da bir bileşenin ek bağımlılığını kurmayı unutmak kolaydır.

Sık yapılan hatalar

• CSS dosyasını eksik kopyalamak: @theme inline bloğundaki bir eşleme eksikse ilgili sınıf, örneğin bg-sidebar, Tailwind tarafından üretilmez. Dosyayı belge sayfasından eksiksiz alın.
• tw-animate-css içe aktarmasını unutmak: Paket kurulu olsa da @import "tw-animate-css"; satırı yoksa animasyon sınıfları çalışmaz.
• Eski eklentiyi kullanmak: Eski rehberlerde tailwindcss-animate ve @plugin satırı görebilirsiniz. Belgelere göre bu eklenti kullanımdan kaldırılmıştır; yerine tw-animate-css kullanılır.
• Takma ad ile aliases değerlerini uyumsuz bırakmak: tsconfig'te ~/*, components.json içinde @/components yazarsanız CLI ile eklenen dosyaların içe aktarmaları çözülmez.
• Bileşene özgü bağımlılığı atlamak: Ortak paketler her bileşene yetmez. Manual sekmesindeki ilk adımı, yani bileşenin kendi paketlerini kurmayı atlamayın.
• Depo içi yolları olduğu gibi bırakmak: Örnek dosyalardan kopyalanan @/registry/... yolları sizin projenizde bulunmaz; kendi takma adlarınıza çevirin.

Sık Sorulan Sorular

Manuel kurulumdan sonra CLI'ı kullanabilir miyim?

Evet. components.json dosyasını oluşturduysanız npx shadcn@latest add komutu bu dosyayı okuyarak bileşenleri ayarladığınız klasörlere ekler.

JavaScript projesinde manuel kurulum nasıl olur?

JavaScript belgesine göre components.json içinde tsx değerini false yaparsınız ve takma adları jsconfig.json dosyasındaki paths ile tanımlarsınız. JavaScript sürümü bileşenler CLI üzerinden sağlanır.

CSS dosyası mutlaka src/styles/globals.css mi olmalı?

Hayır. Örnekteki yol yalnızca bir örnektir. Önemli olan, dosyanın uygulamanızda yüklenmesi ve components.json içindeki tailwind.css alanının aynı yolu göstermesidir.

Temel rengi neutral yerine başka bir renk yapmak istersem?

Belgede neutral, stone, zinc, gray ve slate temel renkleri için ayrı değişken setleri bulunur. Manuel kurulumda seçtiğiniz renge ait değerleri CSS dosyasına yazar ve tailwind.baseColor alanını buna göre ayarlarsınız; ayrıntı tema yazısında.

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 · init komutu · components.json · cn fonksiyonu · Tema değişkenleri · CSS değişkenleri · TypeScript paths