shadcn/ui Kurulumu: init Komutu, Seçenekleri ve Çatı Seçimi

Önce çatınızı seçin

Kurulum sayfası shadcn/ui'nin tüm React çatılarıyla çalışacak biçimde tasarlandığını söyler ve sizden önce kullandığınız çatıyı seçmenizi ister. Seçtiğiniz sayfa, bağımlılıkları kurmayı ve uygulamanızı yapılandırmayı adım adım anlatır. Sayfalar arasında önemli bir fark vardır: bazı çatılarda init komutu işin büyük kısmını yapar, bazılarında ise proje oluşturma aracı shadcn/ui'yi zaten hazırlar ve doğrudan add ile başlarsınız.

Tablodaki komutlar ilgili belge sayfalarında yazdığı gibidir. Kurulum klasöründe ayrıca Remix ve Gatsby sayfaları da bulunur. Remix sayfası en başta, React Router kullanıyorsanız React Router rehberine bakmanız gerektiğini not eder. Gatsby sayfası ise Tailwind v4 ve React 19 desteğinin eklendiğini belirten bir güncelleme kutusuyla başlar. React Router ve Remix örneklerinde bileşen ~/components/ui/button yolundan içe aktarılır; diğer sayfalarda @/components/ui/button kullanılır. Bu fark, o çatının varsayılan takma adından gelir.

init komutu ne yapar?

CLI belgesine göre init komutu yeni bir proje için yapılandırmayı ve bağımlılıkları başlatır. Somut olarak üç iş yapar: bağımlılıkları kurar, cn yardımcısını ekler ve CSS değişkenlerini yapılandırır. Ağustos 2024 changelog kaydı buna iki ayrıntı ekler: komut çatı algılaması yapar ve tek komutla yepyeni bir Next.js uygulaması da başlatabilir; mevcut bir uygulamaya kurulurken de Tailwind dosyalarınızın üzerine yazmak yerine onları günceller.

npx shadcn@latest init

Komut çalışırken components.json dosyasını yapılandırmak için size birkaç soru sorar. Vite kurulum sayfası bu sorulardan birini şöyle gösterir: Which color would you like to use as base color? › Neutral. Temel renk seçenekleri neutral, gray, zinc, stone ve slate değerleridir. Sorulara verdiğiniz yanıtlar dosyaya kaydedilir ve sonraki her add komutu bu dosyayı okur.

init sonrasında projenizde görmeyi beklemeniz gereken başlıca değişiklikler, belgelerin anlattığı ölçüde şunlardır:

• Proje kökünde components.json dosyası.
• lib/utils.ts içinde cn fonksiyonu (manuel kurulum sayfası bu dosyanın içeriğini gösterir).
• Global CSS dosyanızda tema için CSS değişkenleri. Manuel kurulum sayfası bu değişkenlerin tam listesini :root, .dark ve bunları Tailwind'e bağlayan @theme inline blokları hâlinde gösterir.
• package.json içinde bileşenlerin ortak bağımlılıkları.

Bu değişikliklerin ayrıntılı içeriğini manuel kurulum yazısında, elle yapar gibi tek tek inceliyoruz. CSS değişkenlerinin anlamı için tema ve CSS değişkenleri, cn için cn fonksiyonu yazısına bakın.

init seçenekleri

CLI belgesi init komutunun kullanımını shadcn init [options] [components...] olarak verir. Yani komut, seçeneklerin yanında isteğe bağlı olarak bir ya da daha fazla bileşen de alabilir; bileşen bir ad, URL ya da yerel dosya yolu olabilir. Belgelenen seçenekler şunlardır:

Birkaç seçeneğin pratikteki etkisini açalım. --base-color ile temel rengi komut satırında verirseniz bu soru sorulmaz; değer components.json içindeki tailwind.baseColor alanına yazılır. --no-css-variables ise tema için CSS değişkenleri yerine doğrudan Tailwind renk sınıflarının kullanılmasını sağlar. Her iki ayar da belgeye göre kurulumdan sonra değiştirilemez; değişkenlerle sınıflar arasında geçiş yapmak için bileşenleri silip yeniden kurmanız gerekir. --template seçeneği yeni proje oluşturulurken anlam taşır: next tek bir Next.js uygulaması, next-monorepo ise Turborepo tabanlı bir monorepo kurar (monorepo kurulumu).

npx shadcn@latest init --base-color zinc
npx shadcn@latest init -t next --src-dir
npx shadcn@latest init -c ./apps/web

-y seçeneğinin varsayılan değerinin true olması, onay sorusunun init için zaten atlandığı anlamına gelir; add komutunda ise aynı seçeneğin varsayılanı false'tur. --no-base-style seçeneği belgede yalnızca "temel shadcn stilini kurma" diye tanımlanır ve belgede başka bir açıklaması yoktur. Standart bir kurulumda temel stil zaten istenen şey olduğu için bu seçeneğe ihtiyaç duymazsınız.

İlk satır temel renk sorusunu atlayarak zinc seçer. İkinci satır yeni proje oluşturulacaksa Next.js şablonunu ve src klasörünü kullanır. Üçüncü satır komutu başka bir klasörde, örneğin bir monorepo içindeki uygulamada çalıştırır.

init ile bileşen ya da şablon kurmak

init komutuna bileşen argümanı verilebilmesi, kurulum ile ilk bileşenleri tek adımda birleştirmenizi sağlar. Ağustos 2024 changelog kaydı bunun için şu örneği verir:

npx shadcn init sidebar-01 login-01

Buradaki sidebar-01 ve login-01 birer bloktur; hazır blokları Blocks yazısında anlatıyoruz. Temmuz 2025 kaydı ise yerel dosya desteğini getirir: bir registry öğesini tanımlayan yerel JSON dosyasından proje başlatabilirsiniz. Bu, bir şirket şablonunu ağa koymadan önce yerelde denemek için kullanışlıdır.

npx shadcn init ./template.json

Yerel ya da uzak registry öğelerinin nasıl hazırlandığı kendi registry'nizi oluşturma yazısının konusudur.

add ile ilk bileşen

init tamamlandıktan sonra bileşen eklemek için add komutunu kullanırsınız. Belgelerdeki örneklerin neredeyse tamamı Button ile başlar; Laravel sayfası ise Switch bileşenini örnek alır ve dosyanın resources/js/components/ui/switch.tsx konumuna eklendiğini belirtir. Bu da bileşenlerin nereye yazılacağının sabit olmadığını, components.json içindeki takma adlara göre belirlendiğini gösterir.

npx shadcn@latest add button
npx shadcn@latest add button card dialog
npx shadcn@latest add --all

İkinci satır birden fazla bileşeni aynı anda ekler; üçüncü satır, TanStack Start sayfasında da gösterildiği gibi mevcut tüm bileşenleri ekler. add komutunun --overwrite, --path gibi diğer seçenekleri CLI komutları yazısında anlatılıyor. Eklenen bileşeni kullanmak için Vite sayfasındaki src/App.tsx örneğine benzer bir içe aktarma yeterlidir:

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

function App() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center">
      <Button>Başla</Button>
    </div>
  )
}

export default App

Tailwind v4, React 19 ve mevcut projeler

Tailwind v4 sayfasına göre CLI artık projeleri Tailwind v4 ile başlatabilir ve tüm bileşenler Tailwind v4 ile React 19 için güncellenmiştir. Sayfa bu değişikliğin geriye dönük uyumlu olduğunu özellikle vurgular: Tailwind v3 ve React 18 kullanan mevcut uygulamalarınız çalışmaya devam eder, yükseltme yapana kadar eklediğiniz yeni bileşenler de v3 ve React 18 biçiminde gelir. Tailwind v4 ve React 19 ile yalnızca yeni projeler başlar.

Bu ayrımın init açısından anlamı şudur: Tailwind v4 kullanan bir projede components.json içindeki tailwind.config alanı boş bırakılır, çünkü v4'te ayrı bir tailwind.config.js dosyası yoktur. Tailwind v3 kullanan eski bir projede ise bu alan yapılandırma dosyanızın yolunu gösterir. Mevcut bir projeyi v4'e taşıma adımları Tailwind v4 geçişi yazısında; Tailwind'in kendi yenilikleri ise Tailwind CSS v4 yenilikleri yazısında anlatılır.

Kurulumdan sonra kısa kontrol listesi

init ve ilk add komutundan sonra her şeyin yerinde olduğunu anlamak için şu noktaları kontrol edebilirsiniz. Bu liste belgelerdeki adımların tersinden okunmuş hâlidir; bir sorun yaşarsanız hangi adımın eksik kaldığını bulmanıza yardım eder.

• Proje kökünde components.json var mı ve tailwind.css alanı gerçekten global CSS dosyanızı gösteriyor mu?
• aliases.ui değerinin gösterdiği klasörde, örneğin components/ui altında, eklediğiniz bileşenin dosyası duruyor mu?
• lib/utils.ts dosyası ve içindeki cn fonksiyonu var mı?
• Tarayıcıda bileşen stilsiz görünüyorsa global CSS dosyanız uygulamanıza yükleniyor mu ve Tailwind içe aktarılıyor mu?
• Editörünüz @/components/ui/button yolunu bulamıyorsa tsconfig dosyalarınızdaki paths ayarı doğru klasörü gösteriyor mu?

Bu kontrollerden geçemeyen durumların belgelerde geçen çözümlerini sık hatalar ve çözümleri yazısında topluyoruz.

Sık yapılan hatalar

• init'i yanlış klasörde çalıştırmak: Komut geçerli klasörü proje kabul eder. Monorepo ya da alt klasörlerde ya ilgili klasöre geçin ya da -c seçeneğiyle yolu verin.
• Vite veya Astro'da hazırlık adımlarını atlamak: Bu çatılarda Tailwind kurulumu ve tsconfig.json içindeki paths ayarı init'ten önce yapılmalıdır; aksi hâlde takma adlar çözülmez.
• Temel renk ve CSS değişkeni seçimini rastgele yapmak: tailwind.baseColor ve tailwind.cssVariables sonradan değiştirilemez. Emin değilseniz belgenin önerdiği CSS değişkeni yolunu seçin.
• npm ile React 19 uyarısını görmezden gelmek: npm, React 19'u peer dependency olarak listelemeyen paketlerde kurulumu durdurabilir. CLI bu durumda --force ya da --legacy-peer-deps seçimini sorar; ayrıntı React 19 peer dependency yazısında.
• Eski diff komutunu aramak: 2023 changelog kaydında deneysel bir diff komutu anılır, ancak güncel CLI belgesi bu komutu listelemez. Güncel komutlar için CLI sayfasına bakın.

Sık Sorulan Sorular

init komutunu iki kez çalıştırırsam ne olur?

Belge yalnızca --force seçeneğinin var olan yapılandırmanın üzerine zorla yazdığını belirtir; varsayılan değeri false'tur. Mevcut bir components.json dosyanız varsa bilinçsizce --force kullanmayın ve önce dosyanızı yedekleyin.

Hangi paket yöneticisini kullanmalıyım?

Belgeler komutları pnpm, npm, yarn ve bun sekmeleriyle gösterir. React 19 sayfasına göre peer dependency sorunu yalnızca npm'de hata olarak görünür; pnpm ve bun yalnızca sessiz bir uyarı verir.

components.json olmadan bileşen kullanabilir miyim?

Evet. Belgeye göre bu dosya yalnızca CLI ile bileşen eklerken gereklidir. Bileşen sayfalarındaki "Manual" sekmesinden kodu kopyalıyorsanız dosyaya ihtiyacınız yoktur.

npx shadcn create ile init arasındaki fark nedir?

Changelog'a göre Aralık 2025'te duyurulan create, bileşen kütüphanesi, ikonlar, temel renk, tema ve yazı tipini seçerek kendi shadcn/ui sürümünüzü oluşturmanıza yöneliktir. Ayrıntısı yenilikler yazısındadır; bu yazı belgelenmiş init akışını anlatır.

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 · Vite kurulumu · Next.js kurulumu · Manuel kurulum · components.json · CLI komutları · Node.js kurulumu