shadcn CLI komutları: add, view, search, list, build ve migrate

CLI nasıl çalıştırılır?

Belgeler komutları her zaman npx shadcn@latest biçiminde yazar. Paket adı shadcn, sondaki @latest ise npx'in her seferinde en güncel yayımlanmış sürümü kullanmasını ister. Bu sayede CLI'yi projenize kalıcı bağımlılık olarak eklemeniz gerekmez. pnpm, yarn ya da bun kullanıyorsanız aynı komutun kendi paket yöneticinizdeki karşılığını çalıştırırsınız; örneğin depodaki monorepo şablonunun README dosyası pnpm dlx shadcn@latest biçimini kullanır. Node.js ve npm kurulu değilse önce Node.js kurulum rehberine bakın.

CLI'nin bileşeni nereye yazacağını, hangi stil ve renk ayarıyla üreteceğini bilmesi için projenin kökünde bir components.json dosyası olmalıdır. Bu dosyayı init oluşturur; alanların tek tek anlamı components.json ayarları yazısında. add, view, search ve migrate bu dosyadaki takma adları (aliases) ve registry tanımlarını okur. build ise farklıdır: o, bileşen tüketen değil registry yayımlayan tarafın komutudur ve registry.json dosyasını okur.

add: bileşen eklemek

add komutu, adını verdiğiniz bileşenin kaynak kodunu components.json içindeki aliases.ui yoluna yazar ve gerekiyorsa npm bağımlılıklarını kurar. Bir bileşen başka bileşenlere ihtiyaç duyuyorsa (registry dilinde registryDependencies) onları da ekler. Argüman olarak bileşen adı, bir URL ya da yerel bir dosya yolu verebilirsiniz. Tek komutta birden çok bileşen de yazılabilir.

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

Ağustos 2024 tarihli CLI yeniden yazımından beri uzak bir registry öğesini doğrudan URL ile kurabilirsiniz. Temmuz 2025 notu ise yerel JSON dosyalarından kurulumu ekledi; bu, bir registry öğesini yayımlamadan önce kendi makinenizde denemenin en kısa yoludur. CLI 3.0 (Ağustos 2025) ile gelen ad alanlı registry'lerde ise @registry/ad biçimi kullanılır. Changelog'daki örnekler şöyle:

npx shadcn add https://acme.com/registry/navbar.json
npx shadcn add ./block.json
npx shadcn add @acme/button @internal/auth-system

Ad alanlı biçimin çalışması için @acme gibi bir adın components.json içindeki registries alanında tanımlı olması gerekir. Bu kurulum ve kimlik doğrulama ayrıntıları namespace ve özel registry yazısında anlatılıyor.

add seçenekleri

Bileşen adı vermeden yalnızca npx shadcn@latest add yazarsanız CLI size bir seçim listesi açar. 3.6.2 kaynağında bu listenin sorusu "Which components would you like to add?" metnidir; listede yalnızca registry:ui türündeki öğeler bulunur ve hiçbir şey seçmeden onaylarsanız "No components selected. Exiting." uyarısıyla çıkılır. --all seçeneği ise registry dizinindeki tüm öğeleri seçer; kaynak koda göre kullanımdan kaldırılmış bileşenler bu listeden çıkarılır.

Kullanımdan kaldırılmış bir bileşeni adıyla istemek de mümkün değildir. Eski toast bileşeni Tailwind v4 güncellemesiyle birlikte sonner lehine kullanımdan kaldırıldı. 3.6.2 kaynağında add toast denediğinizde CLI "The toast component is deprecated. Use the sonner component instead." uyarısını yazar ve işlem yapmadan çıkar. Bildirim için doğru yol Sonner bileşeni.

-c (--cwd) özellikle monorepo yapılarında işe yarar: depodaki monorepo şablonunun README dosyası, kökten çalışırken bileşeni web uygulaması adına eklemek için -c apps/web kullanır. Ayrıntılar için shadcn monorepo kurulumu yazısına bakın.

view: kurmadan önce incelemek

view komutu bir registry öğesini projenize yazmadan gösterir. Changelog'daki tanıma göre amaç, kurmadan önce kodu ve tüm bağımlılıkları görmektir. Aynı anda birden çok öğe verebilir, ad alanlı registry'lerden de öğe isteyebilirsiniz. 3.6.2 kaynağında komut sonucu biçimlendirilmiş JSON olarak terminale yazdırır; yani öğenin türünü, dosyalarını ve bağımlılık listesini doğrudan okuyabilirsiniz.

npx shadcn@latest view button card dialog
npx shadcn@latest view @acme/auth @v0/dashboard

Belgedeki seçenek listesi kısadır: yalnızca -c, --cwd ve yardım seçeneği vardır. Argüman olarak öğe adları ya da URL'ler verilir. Üçüncü taraf bir registry'den kod alacaksanız önce view ile bakmak iyi bir alışkanlıktır, çünkü add komutu kodu doğrudan projenize yazar ve npm paketleri kurar.

search ve list: registry içinde aramak

search bir ya da daha fazla registry'de öğe arar. Registry adları @ ile başlamak zorundadır; URL de verebilirsiniz. -q ile bir sorgu metni geçersiniz, -l registry başına gösterilecek en fazla öğe sayısını (varsayılan 100), -o ise atlanacak öğe sayısını (varsayılan 0) belirler. Bu iki seçenekle uzun listelerde sayfa sayfa ilerleyebilirsiniz.

npx shadcn@latest search @shadcn -q "button"
npx shadcn@latest search @shadcn @v0 @acme
npx shadcn@latest list @acme

list komutu belgede ayrı bir başlık olarak geçse de aynı sayfa onun search için bir takma ad olduğunu söyler; 3.6.2 kaynağında da search komutu list takma adıyla tanımlıdır. Pratikte sorgu vermeden list @acme yazmak, o registry'deki öğeleri listelemek anlamına gelir. Sonuç da view gibi JSON olarak yazdırılır. Changelog örneği, bir topluluk registry'sinde koyu temalı öğeleri bulmak için npx shadcn search @tweakcn -q "dark" komutunu gösterir.

Kasım 2025 notu Registry Directory'yi duyurur: göz atıp kod çekebileceğiniz registry'lerin listesidir ve CLI'ye yerleşiktir, ek yapılandırma istemez. Hangi registry adlarının bu şekilde hazır geldiğini namespace yazısında ele alıyoruz.

Özel registry ve ortam değişkenleri

Kimlik doğrulama isteyen bir registry, components.json içinde ${REGISTRY_TOKEN} gibi ortam değişkenlerine başvurur. Değişken tanımlı değilse CLI 3.0 ile gelen hata mesajı hangi değişkenin eksik olduğunu adıyla söyler ve onu .env ya da .env.local dosyasına yazmanızı ister. Bu nedenle add, view veya search komutlarını özel bir registry ile kullanmadan önce gerekli değişkenlerin bu dosyalardan birinde bulunduğundan emin olun. Registry yazarları da yanıtlarına kendi hata mesajlarını koyabilir; örneğin süresi dolmuş bir API anahtarında CLI, registry'nin döndürdüğü açıklamayı olduğu gibi gösterir.

build: kendi registry dosyalarınızı üretmek

build komutu, kendi bileşenlerinizi başkalarına dağıtmak istediğinizde kullanılır. Varsayılan olarak ./registry.json dosyasını okur ve her öğe için bir JSON dosyasını ./public/r klasörüne yazar. Bu klasör bir web sunucusundan yayınlandığında, başka projeler o JSON'ları add ile URL üzerinden kurabilir. Çıktı klasörünü --output (kısa biçimi -o) ile değiştirirsiniz.

npx shadcn@latest build
npx shadcn@latest build --output ./public/registry

Argüman olarak farklı bir registry.json yolu da verebilirsiniz. registry.json ve registry-item.json şemalarının içeriği, öğe türleri ve yayına alma adımları kendi registry'nizi oluşturma yazısının konusu.

migrate: içe aktarmaları toplu güncellemek

Haziran 2025 notu, tek tek @radix-ui/react-* paketleri yerine birleşik radix-ui paketine geçmek için bir komut ekledi. Komut ui klasörünüzdeki bileşenlerin içe aktarmalarını değiştirir ve radix-ui paketini bağımlılık olarak kurar.

npx shadcn@latest migrate radix

Changelog'daki örnekte components/ui/alert-dialog.tsx dosyasının içe aktarması şöyle değişir:

// Önce
import * as AlertDialogPrimitive from "@radix-ui/react-dialog"

// Sonra
import { AlertDialog as AlertDialogPrimitive } from "radix-ui"

İki önemli not var. Birincisi, komuttan sonra bileşenlerinizi ve projeyi test etmeniz istenir. İkincisi, geçişten sonra eklediğiniz yeni bileşenlerin içe aktarmaları otomatik güncellenmez; onlar için komutu yeniden çalıştırmanız gerekir. Komut components.json dosyasını arar; 3.6.2 kaynağında dosya bulunamazsa "No `components.json` file found. Ensure you are at the root of your project." hatası verilir. Kasım 2024 notu ayrıca ikonları CLI ile isteğe bağlı olarak Lucide'a taşıyabileceğinizi söyler; kaynakta bu geçişin adı icons olarak geçer.

diff komutu ne oldu?

Eski blog yazılarında ve bazı kopya kağıtlarında npx shadcn@latest diff komutunu görebilirsiniz. Changelog'un Haziran 2023 bölümü bu komutu deneysel olarak tanıtmıştı. Ancak depo kopyası 19 Aralık 2025 tarihli güncel cli.mdx sayfası diff komutunu belgelemiyor. Bu nedenle onu güncel ve desteklenen bir iş akışı gibi kullanmayın. Yerel değişikliklerinizi korumanın belgelenmiş yolu git ile kaydedip add --overwrite sonrası farkları kendi araçlarınızla incelemektir.

Uygulamalı akış: bir bileşeni bulup güvenle eklemek

Diyelim ki projenize ad alanlı bir registry'den kimlik doğrulama bloğu ekleyeceksiniz ve aynı zamanda shadcn/ui'nin kendi düğmesini güncellemek istiyorsunuz. Belgelerdeki komutları birleştiren güvenli bir sıra şöyle olabilir:

git add .
git commit -m "bilesenleri guncellemeden once"

npx shadcn@latest search @acme -q "auth"
npx shadcn@latest view @acme/auth
npx shadcn@latest add @acme/auth
npx shadcn@latest add button --overwrite

İlk iki satır, üzerine yazma işleminden önce geri dönüş noktası oluşturur. search öğe adını bulmanızı, view kodu ve bağımlılıkları görmenizi sağlar. add öğeyi ve ihtiyaç duyduğu bileşenleri kurar. Son satır yerel button.tsx dosyanızın üzerine yazacağı için ondan önce yaptığınız commit önemlidir; ardından git farkına bakıp kendi düzenlemelerinizi geri taşırsınız. Burada @acme belgelerin örnek adıdır; kendi projenizde gerçekten tanımlı bir registry adı kullanmalısınız.

Sık yapılan hatalar

• components.json olmadan add çalıştırmak: CLI bileşeni nereye yazacağını bilemez. Önce init çalıştırın ya da dosyayı manuel kurulum adımlarıyla oluşturun.
• Kök dizin yerine alt klasörde komut vermek: Monorepo dışında da CLI geçerli dizine bakar. Farklı bir klasör için -c seçeneğini kullanın.
• Registry adını @ olmadan yazmak: search ve list için registry adlarının @ ile başlaması gerekir.
• Tanımsız ad alanı kullanmak: components.json içinde tanımlı olmayan bir @acme için CLI "Unknown registry" hatası verir; hata metinleri sık hatalar yazısında.
• Commit etmeden --overwrite: Bileşenlerdeki kendi değişiklikleriniz kaybolur.
• migrate radix sonrasını unutmak: Yeni eklenen bileşenler için komutu tekrar çalıştırmak gerekir.
• diff komutuna güvenmek: Güncel belgede yer almaz.

Sık Sorulan Sorular

shadcn CLI'yi global olarak kurmam gerekir mi?

Hayır. Belgelerdeki tüm komutlar npx shadcn@latest ile çalışır; npx paketi geçici olarak indirip çalıştırır. pnpm, yarn veya bun kullanıyorsanız kendi paket yöneticinizin eşdeğer komutunu kullanabilirsiniz.

add komutu var olan bir dosyanın üzerine yazar mı?

Varsayılan olarak --overwrite kapalıdır (false). Üzerine yazmayı açıkça istemeniz gerekir. Değişiklik yaptığınız bileşenler için önce commit almanız belgelerde özellikle önerilir.

view ile search arasındaki fark nedir?

search (ve takma adı list) registry içinde hangi öğelerin bulunduğunu bulmanıza yarar. view ise adını bildiğiniz öğenin içeriğini, yani dosyalarını ve bağımlılıklarını kurmadan göstermek içindir.

build komutunu her projede çalıştırmam gerekir mi?

Hayır. build yalnızca kendi registry'nizi yayımlıyorsanız gerekir. Bileşen tüketen bir uygulama için init ve add yeterlidir.

Aralık 2025'te duyurulan create komutu nedir?

Changelog'a göre npx shadcn create, bileşen kütüphanesini, stili ve temayı seçerek kendi shadcn/ui sürümünüzü oluşturmanızı sağlar. Ayrıntılar yenilikler ve sürüm geçmişi 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 · kendi registry'niz · namespace ve özel registry · shadcn MCP sunucusu