shadcn/ui components.json Ayarları: Tüm Alanlar ve Örnekler

Dosya ne zaman gerekir?

Belge bu konuda açıktır: components.json isteğe bağlıdır ve yalnızca CLI ile bileşen ekliyorsanız gereklidir. Bileşen sayfalarındaki "Manual" sekmesinden kodu kopyalayıp yapıştırıyorsanız bu dosyaya ihtiyacınız yoktur. CLI ise her add komutunda bu dosyayı okuyarak bileşenin hangi klasöre yazılacağını, içe aktarma yollarının nasıl düzenleneceğini ve renklerin hangi yöntemle uygulanacağını belirler. Dosyayı oluşturmanın önerilen yolu init komutudur:

npx shadcn@latest init

Dosyayı elle de yazabilirsiniz; manuel kurulum sayfası eksiksiz bir örnek verir (manuel kurulum). Aşağıdaki tam örnek, bu yazıda anlatılan alanların hepsini bir arada gösterir:

{
  "$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"
}

$schema

$schema alanı dosyanın JSON şemasını gösterir. Belge şemayı https://ui.shadcn.com/schema.json adresinde yayımlar. Bu alan CLI'ın davranışını değiştirmez; ancak şemayı tanıyan editörler size alan adlarında otomatik tamamlama ve yanlış değerlerde uyarı gösterebilir. Elle yazdığınız dosyalarda bu satırı eklemeniz yazım hatalarını erken yakalamanıza yardım eder.

style

style, bileşenlerinizin stilini belirler ve belgeye göre kurulumdan sonra değiştirilemez. Belge ayrıca default stilinin kullanımdan kaldırıldığını ve bunun yerine new-york stilinin kullanılması gerektiğini söyler. Haziran 2023 changelog kaydı stil kavramını bileşenlerin görsel temeli, yani şekiller, ikonlar, animasyonlar ve tipografi olarak tanımlar; her stil kendi bileşen, animasyon ve ikon setiyle gelir.

Değiştirilememesinin pratik nedeni, stilin CLI'ın hangi bileşen kaynağını çekeceğini belirlemesidir: projenizdeki bileşenler bir stile göre üretilmiştir, alanı sonradan değiştirmek mevcut dosyaları dönüştürmez. Aralık 2025'te duyurulan npx shadcn create ile gelen yeni görsel stiller (Vega, Nova, Maia, Lyra, Mira) ayrı bir akıştır; ayrıntısı yenilikler yazısında.

tailwind alanları

tailwind nesnesi, Tailwind CSS'in projenizde nasıl kurulduğunu CLI'ya anlatır. Beş alt alanı vardır.

tailwind.config

tailwind.config.js ya da tailwind.config.ts dosyanızın yoludur. Belge özellikle vurgular: Tailwind CSS v4 için bu alanı boş bırakın. v4'te yapılandırma CSS dosyasının içinde yapıldığı için ayrı bir dosya yolu gerekmez. Bu alan yalnızca Tailwind v3 kullanan eski projelerde dolu olur.

tailwind.css

Projenize Tailwind CSS'i içe aktaran CSS dosyasının yoludur, örneğin styles/global.css, app/globals.css ya da src/index.css. CLI tema değişkenlerini ve bileşenlerin ihtiyaç duyduğu CSS eklemelerini bu dosyaya yazar. Bu yüzden değer, uygulamanızın gerçekten yüklediği dosyayı göstermelidir.

tailwind.baseColor

Bileşenler için varsayılan renk paletini üretmekte kullanılır ve kurulumdan sonra değiştirilemez. Geçerli değerler gray, neutral, slate, stone ve zinc'tir. Haziran 2023 kaydına göre cssVariables açıksa temel renkler global CSS dosyanıza CSS değişkeni olarak yazılır; kapalıysa Tailwind renk sınıfları doğrudan bileşenlerin içine yerleştirilir. Renk değerlerinin tamamı tema ve CSS değişkenleri yazısında.

tailwind.cssVariables

Tema için CSS değişkenleri mi yoksa Tailwind yardımcı sınıfları mı kullanılacağını seçer. true değerinde bileşenler bg-background ve text-foreground gibi değişkenlere bağlı sınıflar kullanır; false değerinde ise bg-zinc-950 ve dark:bg-white gibi doğrudan renk sınıfları kullanılır. Tema belgesi CSS değişkenlerini önerilen yöntem olarak tanımlar.

<div className="bg-background text-foreground" />
<div className="bg-zinc-950 dark:bg-white" />

İlk satır cssVariables: true, ikinci satır cssVariables: false durumunda bileşenlerde göreceğiniz sınıf türünü örnekler. Bu alan da kurulumdan sonra değiştirilemez; belgeye göre iki yöntem arasında geçmek için bileşenlerinizi silip yeniden kurmanız gerekir.

tailwind.prefix

Tailwind yardımcı sınıfları için kullanılacak önektir; bileşenler bu önekle eklenir. Örneğin "prefix": "tw-" ayarıyla eklenen bir bileşenin sınıfları tw- ile başlar. Bu, kendi Tailwind sınıflarınızla çakışmayı önlemek istediğiniz mevcut projelerde işe yarar. Önek kullanmıyorsanız alanı boş dize olarak bırakırsınız.

rsc

React Server Components desteğinin açık olup olmadığını belirtir. true olduğunda CLI, istemci bileşenlerine "use client" yönergesini otomatik ekler. Next.js App Router gibi Server Components kullanan projelerde true, Vite gibi kullanmayan projelerde false değeri uygundur. Bu alanın bileşen dosyalarına etkisi Next.js kurulumu yazısında örnekleriyle anlatılıyor.

tsx ve JavaScript projeleri

tsx, bileşenlerin TypeScript mi JavaScript mi olacağını seçer. false yapıldığında bileşenler .jsx uzantılı JavaScript dosyaları olarak eklenir. JavaScript belgesi, projenin ve bileşenlerin TypeScript ile yazıldığını ve TypeScript kullanmanızın önerildiğini, ancak CLI üzerinden bir JavaScript sürümünün de sunulduğunu belirtir. Belgedeki örnek dosya şöyledir:

{
  "style": "new-york",
  "rsc": false,
  "tsx": false,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

JavaScript projesinde takma adlar tsconfig.json yerine jsconfig.json içinde tanımlanır:

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

aliases

aliases nesnesi, CLI'ın oluşturduğu dosyaları nereye koyacağını ve içlerindeki içe aktarmaları nasıl yazacağını belirler. Belgeye göre CLI bu değerleri tsconfig.json ya da jsconfig.json dosyanızdaki paths ayarıyla birlikte kullanır; bu yüzden takma adların önce o dosyada tanımlanmış olması gerekir. src klasörü kullanıyorsanız, belgedeki önemli notun dediği gibi, bu klasörün paths altında yer aldığından emin olun.

aliases.ui özellikle önemlidir: CLI ui bileşenlerini hangi klasöre yazacağına bu değerle karar verir. Belgedeki "@/app/ui" örneği, bileşenleri varsayılan components/ui yerine başka bir klasörde tutmak istediğinizde kullanılır. Bu değeri değiştirdiğinizde bileşenleri içe aktarırken de aynı yolu kullanırsınız, örneğin import { Button } from "@/app/ui/button".

Monorepo projelerinde aynı alanlar workspace paketlerini gösterir. Monorepo belgesindeki uygulama dosyasında ui değeri @workspace/ui/components, utils değeri @workspace/ui/lib/utils olarak yazılır ve her workspace'in kendi components.json dosyası bulunur. Ayrıntı monorepo kurulumu yazısında.

iconLibrary

components.json belge sayfasında ayrı bir başlığı olmasa da manuel kurulum, tema, JavaScript ve monorepo sayfalarındaki örneklerin hepsinde "iconLibrary": "lucide" satırı bulunur. Changelog'daki Kasım 2024 kaydına göre new-york stili varsayılan ikon seti olarak Lucide kullanır ve yeni projeler Lucide ile başlar. Bu alanı belgelerdeki örneklerde olduğu gibi lucide bırakmanız yeterlidir.

registries

registries alanı, projeniz için birden fazla kaynak registry tanımlamanızı sağlar. Böylece bileşenleri, kütüphaneleri ve yardımcıları özel registry'ler dahil farklı kaynaklardan kurabilirsiniz. En basit biçimde her registry'ye bir ad ve {name} yer tutuculu bir URL şablonu verilir; kurulum sırasında {name} kaynağın adıyla değiştirilir.

{
  "registries": {
    "@acme": "https://registry.acme.com/{name}.json",
    "@private": {
      "url": "https://api.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

İkinci tanımdaki ${REGISTRY_TOKEN} biçimindeki ortam değişkenleri belgeye göre ortamınızdan otomatik olarak genişletilir; böylece gizli anahtarları dosyaya yazmanız gerekmez. Tanımlanan registry'den kurulum npx shadcn@latest add @acme/header gibi namespace sözdizimiyle yapılır. Kimlik doğrulama yöntemleri ve gelişmiş seçenekler namespace ve özel registry yazısının konusudur.

Dosyayı CLI ne zaman okur ve yazar?

Dosyanın yaşam döngüsünü bilmek, elle yaptığınız değişikliklerin ne zaman etkili olacağını anlamanızı sağlar. İlk yazım init sırasında olur: komut sorulara verdiğiniz yanıtları ve seçenekleri bu dosyaya kaydeder. Sonraki her add komutu dosyayı okuyarak bileşeni yerleştirir; -c seçeneğiyle başka bir çalışma klasörü verdiğinizde komut o klasörde çalışır. CLI bazı durumlarda dosyayı kendisi de günceller. Eylül 2025 changelog kaydına göre açık kaynak registry dizinindeki öğeleri components.json dosyasını önceden yapılandırmadan arayabilir, görüntüleyebilir ve ekleyebilirsiniz; kullanılan registry'ler sizin için components.json dosyasına otomatik eklenir.

Sürüm geçişlerinde dosya geriye dönük uyumlu kalmıştır. Ağustos 2025'teki shadcn CLI 3.0 duyurusu, kullanıcılar için kırıcı bir değişiklik olmadığını, mevcut components.json dosyalarının ve kurulu bileşenlerin aynen çalışmaya devam ettiğini belirtir. Bu yüzden eski bir projede dosyayı yeniden oluşturmanız gerekmez; yalnızca yeni alanlara ihtiyaç duyduğunuzda, örneğin registries, onları eklersiniz.

Tüm alanlar tek tabloda

"Belgede kısıt yok" yazan alanlar için belge değiştirilemez demez; ancak bir değeri değiştirdiğinizde bunun yalnızca bundan sonra eklenen bileşenleri etkileyeceğini unutmayın. Örneğin aliases.ui değerini değiştirmek mevcut dosyaları taşımaz.

CLI'ın kaynak kodundaki şema da belgeyle uyumludur: style, tailwind.css, tailwind.baseColor, aliases.components ve aliases.utils zorunlu alanlardır; rsc verilmezse false, tsx ve tailwind.cssVariables verilmezse true kabul edilir.

Sık yapılan hatalar

• tailwind.css alanında yanlış dosya: Değer uygulamanın yüklemediği bir dosyayı gösterirse CLI tema değişkenlerini oraya yazar ve bileşenler renksiz görünür.
• Tailwind v4 projesinde tailwind.config doldurmak: Belge v4 için alanın boş bırakılmasını ister.
• paths tanımlamadan aliases değiştirmek: Takma adların tsconfig veya jsconfig içinde tanımlı olması gerekir; aksi hâlde eklenen dosyaların içe aktarmaları çözülmez.
• Değiştirilemez alanları elle düzenlemek: style, baseColor ya da cssVariables değerini dosyada değiştirmek mevcut bileşenleri dönüştürmez; sonradan eklenen bileşenler eskilerden farklı yapıda gelebilir.
• Gizli anahtarı dosyaya yazmak: Özel registry tokenlerini ${VAR} sözdizimiyle ortam değişkeninden alın; components.json çoğu zaman sürüm kontrolüne eklenir.
• Monorepo'da tek dosya kullanmak: Monorepo belgesi her workspace'te bir components.json bulunmasını ve style, iconLibrary, baseColor değerlerinin iki dosyada aynı olmasını ister.

Sık Sorulan Sorular

components.json olmadan shadcn/ui kullanabilir miyim?

Evet. Belgeye göre dosya yalnızca CLI için gereklidir; bileşenleri Manual sekmesinden kopyalıyorsanız ihtiyacınız yoktur.

Temel rengi yanlış seçtim, ne yapmalıyım?

tailwind.baseColor belgeye göre kurulumdan sonra değiştirilemez. CSS değişkenleri kullanıyorsanız renkler global CSS dosyanızdaki değişkenlerde durduğu için o değişkenlerin değerlerini tema belgesindeki başka bir temel rengin değerleriyle değiştirebilirsiniz; bu yöntem tema yazısında anlatılıyor.

Bileşenleri components/ui dışında bir klasöre koyabilir miyim?

Evet. aliases.ui değerini, örneğin belgedeki gibi @/app/ui olarak ayarlarsanız CLI ui bileşenlerini o klasöre yazar.

Eski bir projede aliases alanında yalnızca components ve utils var, sorun olur mu?

Ağustos 2024 changelog kaydı, mevcut projeleri yeni CLI'a uyarlamak için components.json dosyasına components, utils, ui, lib ve hooks takma adlarının eklenmesini önerir. Eksik alanları belgedeki varsayılan değerlerle tamamlayabilirsiniz.

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 · Manuel kurulum · Tema değişkenleri · Namespace ve özel registry · Monorepo · TypeScript paths