Kendi shadcn registry'nizi kurmak: registry.json, build ve yayın

Registry nedir, neyi dağıtabilirsiniz?

shadcn/ui kendini yalnızca bir bileşen seti olarak değil, bir kod dağıtım sistemi olarak da tanımlar: bileşenleri, bağımlılıklarını ve özelliklerini anlatan düz dosyalı bir şema ve bu şemayı okuyup projelere kuran bir CLI. Registry belgesi, kendi registry'nizle özel bileşenlerinizi, hook'larınızı, sayfalarınızı, yapılandırma dosyalarınızı, kurallarınızı ve başka dosyalarınızı herhangi bir projeye dağıtabileceğinizi söyler. Belgedeki önemli bir not, registry'nin her proje türü ve her framework ile çalıştığı, React ile sınırlı olmadığıdır.

Tek gerçek gereksinim, registry öğelerinizin registry-item şemasına uyan geçerli JSON dosyaları olmasıdır. Nerede ve nasıl barındıracağınız size kalmıştır. Belge, JSON'u HTTP üzerinden sunabildiği sürece Next.js, Vite, Vue, Svelte, PHP ya da başka bir framework kullanabileceğinizi belirtir. Sıfırdan başlıyorsanız resmi registry-template deposu hazır yapılandırılmış bir başlangıç noktasıdır.

Adım 1: registry.json dosyası

registry.json registry'nin giriş noktasıdır. Registry'nin adını, ana sayfasını ve içindeki tüm öğeleri tanımlar ve registry uç noktanızın kökünde bulunmalıdır. Uç nokta, registry'nizin barındırıldığı URL'dir. Proje kökünde registry.json adıyla şu iskeleti oluşturun:

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": []
}

Adım 2: bileşeni yazmak ve tanımlamak

Belgedeki örnek, düz bir HelloWorld bileşenidir. Dosyayı registry/new-york/hello-world/hello-world.tsx yoluna koyun:

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

export function HelloWorld() {
  return <Button>Merhaba Dünya</Button>
}

Örnekteki new-york klasörü zorunlu değildir; belge bunu yalnızca örnek olarak kullanır. Kural, dosyaların registry klasörü altında registry/[STYLE]/[NAME] düzeninde durması ve registry.json içindeki yolların doğru yazılmasıdır:

registry
└── new-york
    └── hello-world
        └── hello-world.tsx

Şimdi bileşeni items dizisine ekleyin. Her öğe için name, type, title, description ve files yazılır. Her dosya için de projenin köküne göre göreli path ve dosyanın type değeri verilir:

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "hello-world",
      "type": "registry:block",
      "title": "Hello World",
      "description": "A simple hello world component.",
      "files": [
        {
          "path": "registry/new-york/hello-world/hello-world.tsx",
          "type": "registry:component"
        }
      ]
    }
  ]
}

Adım 3: build ve sunum

JSON dosyalarını üretmek için shadcn paketini projeye ekleyip package.json içine bir registry:build betiği tanımlarsınız:

{
  "scripts": {
    "registry:build": "shadcn build"
  }
}

npm install shadcn@latest
npm run registry:build

Build komutu varsayılan olarak çıktıları public/r klasörüne yazar; örneğin public/r/hello-world.json. CLI belgesine göre build komutu argüman olarak registry.json yolunu alır (varsayılan ./registry.json) ve -o, --output ile hedef klasör değiştirilebilir (varsayılan ./public/r). -c, --cwd çalışma klasörünü belirler:

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

Registry Next.js üzerindeyse geliştirme sunucusunu başlatmanız yeterlidir; dosyalar http://localhost:3000/r/[NAME].json adresinden sunulur. Başka bir projeden bu adresi vererek kurulumu deneyebilirsiniz:

npm run dev
npx shadcn@latest add http://localhost:3000/r/hello-world.json

Registry'yi başka geliştiricilere açmak için projeyi herkese açık bir URL'ye yayımlarsınız. Next.js uygulamasını kendi sunucunuzda yayınlamak için Next.js VPS yayınlama rehberine bakabilirsiniz.

registry-item.json alanları

Build sonucunda her öğe için üretilen JSON, registry-item şemasına uyar. Aynı alanları registry.json içindeki öğe tanımlarında da kullanırsınız. Belgede anlatılan alanlar şunlardır:

type alanının alabildiği değerler belgede şöyle listelenir. Bu ayrım önemlidir, çünkü CLI dosyayı projenin hangi klasörüne koyacağına türüne ve components.json takma adlarına bakarak karar verir:

files, target ve bağımlılıklar

files içindeki her dosyada path, type ve isteğe bağlı target bulunur. path build betiğinin dosyayı okuyup dönüştürmesi için registry içindeki yoldur. target dosyanın kullanıcının projesinde nereye yazılacağını belirtir ve registry:page ile registry:file türleri için zorunludur. Diğer türlerde CLI hedefi components.json dosyasından okur. ~ işareti projenin kökünü gösterir; örneğin ~/foo.config.js.

{
  "files": [
    {
      "path": "registry/new-york/hello-world/page.tsx",
      "type": "registry:page",
      "target": "app/hello/page.tsx"
    },
    {
      "path": "registry/new-york/hello-world/hello-world.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/new-york/hello-world/use-hello-world.ts",
      "type": "registry:hook"
    },
    {
      "path": "registry/new-york/hello-world/.env",
      "type": "registry:file",
      "target": "~/.env"
    }
  ]
}

Bağımlılıklar iki ayrı alanda tutulur. dependencies npm paketleri içindir ve sürüm sabitlemek için zod@^3.20.0 gibi name@version biçimi kullanılır. registryDependencies ise başka registry öğeleri içindir ve üç biçim alır: shadcn/ui öğeleri için düz ad (button), namespace'li öğeler için @acme/input-form, özel registry öğeleri için tam URL. CLI uzaktaki registry bağımlılıklarını otomatik çözer.

{
  "dependencies": ["zod@^3.20.0", "motion"],
  "registryDependencies": [
    "button",
    "@acme/input-form",
    "https://example.com/r/editor.json"
  ]
}

CSS değişkenleri, CSS kuralları ve ortam değişkenleri

Bir öğe, kurulduğu projenin CSS dosyasını da güncelleyebilir. cssVars alanında theme, light ve dark anahtarları bulunur. Registry SSS'ine göre yeni bir renk eklemek için onu hem light hem dark altına yazarsınız; CLI CSS dosyasını güncelledikten sonra renk utility sınıfı olarak kullanılabilir. Bir Tailwind tema değişkenini eklemek ya da ezmek için cssVars.theme kullanılır. css alanı ise @layer base, @layer components, @utility, @keyframes ve @plugin gibi kurallar ekler. Örneklere göre @import satırları dosyanın en üstüne, eklentiler importlardan sonra ve diğer içerikten önce yerleşir; npm'den gelen bir eklentiyi dependencies listesine de eklemeniz gerekir.

envVars alanındaki değişkenler .env.local veya .env dosyasına eklenir ve var olan değişkenlerin üzerine yazılmaz. Belge bunu yalnızca geliştirme veya örnek değerler için kullanmanızı, üretim değerleri için kesinlikle kullanmamanızı vurgular. docs alanı ise kurulum sırasında kullanıcıya bir mesaj göstermenizi sağlar. Hepsini bir arada gösteren örnek:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "brand-card",
  "type": "registry:component",
  "cssVars": {
    "theme": {
      "font-heading": "Poppins, sans-serif"
    },
    "light": {
      "brand": "oklch(0.99 0.00 0)"
    },
    "dark": {
      "brand": "oklch(0.14 0.00 286)"
    }
  },
  "css": {
    "@utility content-auto": {
      "content-visibility": "auto"
    }
  },
  "envVars": {
    "NEXT_PUBLIC_APP_URL": "http://localhost:4000"
  },
  "docs": "Bu bileşen NEXT_PUBLIC_APP_URL değişkenini kullanır."
}

Proje temasındaki değişkenlerin ne anlama geldiğini tema ve CSS değişkenleri yazısında bulabilirsiniz.

Stil, tema ve evrensel öğeler

Registry yalnızca bileşen dağıtmaz. registry:style türündeki bir öğe npx shadcn init sırasında uygulanan özel bir stil tanımlar. Belgedeki örnek, shadcn/ui'yi genişleten bir stildir: @tabler/icons-react paketini kurar, login-01 bloğunu ve calendar bileşenini ekler, uzak bir registry'den editor öğesini alır, font-sans değişkenini ayarlar ve açık ile koyu modda bir brand rengi tanımlar:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "example-style",
  "type": "registry:style",
  "dependencies": ["@tabler/icons-react"],
  "registryDependencies": [
    "login-01",
    "calendar",
    "https://example.com/r/editor.json"
  ],
  "cssVars": {
    "theme": {
      "font-sans": "Inter, sans-serif"
    },
    "light": {
      "brand": "20 14.3% 4.1%"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}

Stil "extends": "none" taşıyorsa shadcn/ui'yi genişletmez, sıfırdan bir stil kurar. registry:theme türü ise yalnızca renk değişkenlerinden oluşan temalar içindir. Belgedeki ayrı bir örnek, login-01 bloğunu kurup button, input ve label temel parçalarını uzak registry'deki sürümlerle değiştiren bir bloktur; bu, registry bağımlılıklarının sırayla çözülmesinden yararlanır.

Sürüm 2.9.0'dan beri evrensel öğeler de yazılabilir. Bunlar framework algılaması veya components.json olmadan kurulabilir. Koşul, öğedeki tüm dosyaların açık bir target taşımasıdır. Belgedeki örnek, bir projeye Cursor kuralları dosyası kuran öğedir:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "python-rules",
  "type": "registry:item",
  "files": [
    {
      "path": "/path/to/your/registry/default/custom-python.mdc",
      "type": "registry:file",
      "target": "~/.cursor/rules/custom-python.mdc",
      "content": "..."
    }
  ]
}

Temmuz 2025'ten beri CLI yerel JSON dosyalarını da kabul eder. Böylece bir öğeyi yayımlamadan önce yerelde deneyebilirsiniz:

npx shadcn init ./template.json
npx shadcn add ./block.json

Yayımlamadan önce kontrol

Bir öğeyi duyurmadan önce kullanıcı gözüyle denemek, sonradan gelen hata bildirimlerini azaltır. CLI belgesine göre view komutu yalnızca adları değil URL'leri de kabul eder; böylece build sonrasında üretilen JSON'un içeriğini, yani dosyaları ve bağımlılıkları, kurulum yapmadan görebilirsiniz:

npx shadcn@latest view http://localhost:3000/r/hello-world.json

Ardından boş bir test projesinde add komutunu aynı URL ile çalıştırıp şunlara bakın: dosyalar beklediğiniz klasörlere yazıldı mı, içe aktarmalar test projesinin takma adlarına çözüldü mü, dependencies içindeki paketler kuruldu mu, cssVars değerleri CSS dosyasına eklendi mi. Registry belgesi build betiğinin dosyaları ayrıştırıp dönüştürdüğünü söyler; bu yüzden kaynak dosyada çalışan bir yolun kullanıcı projesinde de çalıştığını görmek için tek güvenilir yol gerçek bir kurulumdur.

Sık yapılan hatalar

• Sayfa veya genel dosyada target unutmak: registry:page ve registry:file için target zorunludur; diğer türlerin hedefi components.json takma adlarından gelir.
• İçe aktarmalarda yanlış yol: Belgeye göre registry içindeki dosyalarda içe aktarmalar her zaman @/registry yolunu kullanmalıdır, örneğin import { HelloWorld } from "@/registry/new-york/hello-world/hello-world".
• Bağımlılıkları eksik listelemek: Kullandığınız her shadcn bileşenini registryDependencies, her npm paketini dependencies içine yazmazsanız öğe başka projede eksik kurulur.
• Tanımı değiştirip build almamak: registry.json değiştikten sonra public/r dosyaları yeniden üretilmelidir.
• Tailwind v4 projesinde tailwind alanı kullanmak: Bu alan kullanımdan kalktı; cssVars.theme kullanın.
• envVars ile gizli değer dağıtmak: Bu alana yalnızca örnek ve geliştirme değerleri yazılmalıdır.
• Geçersiz JSON yayımlamak: CLI 3.6.2 kaynak kodunda şemaya uymayan bir öğe için Failed to parse registry item: ... hatası ve öğenin geçerli bir JSON nesnesi döndürmesi gerektiğini söyleyen bir öneri tanımlıdır.

Registry SSS'indeki karmaşık bileşen örneğinde yardımcı dosyanın türü registry:utils olarak yazılmıştır; oysa şema belgesindeki tür listesinde bu değer yoktur ve yardımcı dosyalar için registry:lib verilir. Kendi öğelerinizde listedeki türleri kullanmanız daha güvenlidir.

Sık Sorulan Sorular

Registry için Next.js zorunlu mu?

Hayır. JSON dosyalarını HTTP üzerinden sunabilen her ortam yeterlidir. Belgedeki sunum adımı Next.js örneğiyle anlatılır, ancak public/r içindeki dosyaları herhangi bir statik sunucudan yayımlayabilirsiniz.

Kullanıcı bileşenimi kurduktan sonra güncellemeleri nasıl alır?

Kod kullanıcının projesine kopyalandığı için otomatik güncelleme yoktur. Kullanıcı aynı öğeyi yeniden ekler; add komutunun --overwrite seçeneği mevcut dosyaların üzerine yazar. Bu yüzden önemli değişiklikleri sürüm notu olarak duyurmanız iyi olur.

Registry'mi özel yapabilir miyim?

Evet. Kimlik doğrulama başlıkları, API anahtarları ve namespace yapılandırması namespace ve özel registry yazısında anlatılıyor.

Hazır registry'leri nasıl bulurum?

CLI'ye gömülü açık kaynak registry dizini vardır; npx shadcn@latest search ve list komutlarıyla tarayabilirsiniz. Komutların ayrıntısı CLI komutları 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 · Namespace ve özel registry · shadcn/ui Blocks · shadcn MCP sunucusu · components.json ayarları