shadcn namespace'li registry: @acme/button, özel registry ve kimlik doğrulama

Namespace nedir ve neden merkezi değildir?

Namespace, @ ile başlayan ve kaynağın hangi registry'den geleceğini söyleyen bir öndür. Belge, kaynak türünün yalnızca bileşen olmadığını vurgular: kütüphaneler, yardımcı fonksiyonlar, hook'lar, yapay zekâ istemleri, yapılandırma dosyaları ve temalar da aynı yolla dağıtılabilir. Örneğin @shadcn/button shadcn registry'sinden bir UI bileşenini, @acme/auth-utils şirketinizin özel registry'sinden kimlik doğrulama yardımcılarını gösterebilir.

Sistem bilerek merkezi olmayan biçimde tasarlanmıştır. Açık kaynak namespace'ler için merkezi bir dizin vardır, ama istediğiniz namespace'i kendiniz tanımlayabilirsiniz. Merkezi bir kayıt makamı olmadığı için ad çakışması kaygısı da yoktur; ad yalnızca sizin components.json dosyanızda anlam taşır. Belge bunu registry'leri türe (@components, @hooks), ekibe (@design, @engineering), görünürlüğe (herkese açık ve özel) ya da kararlılığa (@stable, @experimental) göre ayırmak için bir fırsat olarak sunar.

Adlandırma kuralları

Belgeye göre registry adı @ ile başlamalı ve yalnızca harf, rakam, tire ve alt çizgi içermelidir. Geçerli örnekler @v0, @acme-ui ve @my_company olarak verilir. Kaynaklara @namespace/resource-name kalıbıyla başvurulur. Belgenin teknik ayrıntılar bölümündeki ayrıştırıcı düzenli ifadesi, adın bir harf veya rakamla başlayıp bitmesini de şart koşar:

/^(@[a-zA-Z0-9](?:[a-zA-Z0-9-_]*[a-zA-Z0-9])?)\/(.+)$/

CLI 3.6.2 kaynak kodunda bu kurala uymayan adlar için şu hata metni tanımlıdır: Invalid registry namespace: "...". Registry names must start with @ (e.g., @shadcn, @v0).

Temel yapılandırma: URL şablonu

En basit tanım, namespace'i bir URL şablonuna eşleyen bir metindir. {name} yer tutucusu zorunludur ve kurulum sırasında kaynak adıyla değiştirilir: @acme/button isteği https://registry.acme.com/resources/button.json adresine dönüşür.

{
  "registries": {
    "@v0": "https://v0.dev/chat/b/{name}",
    "@acme": "https://registry.acme.com/resources/{name}.json"
  }
}

Tanımdan sonra kurulum, resmi bileşenlerdeki gibidir; birden fazla registry'den aynı komutta öğe alabilirsiniz:

npx shadcn@latest add @acme/button
npx shadcn@latest add @acme/header @lib/auth-utils @ai/chatbot-rules

İsteğe bağlı {style} yer tutucusu projenin components.json dosyasındaki stil değeriyle doldurulur. Stil new-york iken @themes/card isteği https://registry.example.com/new-york/card.json olur. Aynı bileşenin farklı stiller için farklı sürümlerini sunmak istediğinizde işe yarar.

{
  "registries": {
    "@themes": "https://registry.example.com/{style}/{name}.json"
  }
}

Belgeye göre resmi shadcn/ui registry'si için ayrıca bir yapılandırma gerekmez; components.json yazısındaki çoklu registry örneğinde @shadcn adı https://ui.shadcn.com/r/{name}.json adresiyle açıkça da yazılabilir.

Özel registry: başlıklar, parametreler, ortam değişkenleri

Kimlik doğrulama veya ek parametre gerektiren registry'ler için nesne biçimi kullanılır. url zorunlu alandır; headers her isteğe eklenecek HTTP başlıklarını, params URL'ye eklenecek sorgu parametrelerini taşır:

{
  "registries": {
    "@private": {
      "url": "https://api.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}",
        "X-API-Key": "${API_KEY}"
      },
      "params": {
        "version": "latest",
        "format": "json"
      }
    }
  }
}

${VAR_NAME} biçimindeki değerler ortamdan, yani process.env üzerinden genişletilir. Bu genişletme URL'de, başlıklarda ve parametrelerde çalışır. Değerleri proje kökündeki .env.local dosyasına yazarsınız:

REGISTRY_TOKEN=your_secret_token_here
API_KEY=your_api_key_here

Belge ortam değişkenleri için üç güvence sayar: CLI değerlerini hiçbir zaman günlüğe yazmaz veya göstermez, değişkenler yalnızca gerektiğinde genişletilir ve saklanmaz, her registry kendi kimlik doğrulama bağlamını ayrı tutar. Sürümleme için de aynı mekanizma kullanılır: params içine "version": "v2" yazarsanız @versioned/button isteği https://registry.example.com/button?version=v2 olur. Belge varsayılan değer için ${VAR:-default} sözdizimini de önerir.

Kimlik doğrulama yöntemleri

Belgelerde dört temel yöntem gösterilir ve bunlar birlikte de kullanılabilir:

Sorgu parametresiyle kimlik doğrulamada istek https://registry.company.com/button.json?token=your_token biçimine dönüşür. Belge bu yöntemi daha basit kurulumlar için önerir; v0'ın Open in v0 özelliğinin desteklediği tek yöntem de budur.

{
  "registries": {
    "@internal": {
      "url": "https://registry.company.com/{name}.json",
      "params": {
        "token": "${ACCESS_TOKEN}"
      }
    }
  }
}

Kimlik doğrulama belgesi aynı projede herkese açık, iç ve lisanslı registry'leri bir arada kullanan şu örneği verir. Her namespace kendi başlığını taşır; böylece erişim düzeyine göre ayrım yapılır:

{
  "registries": {
    "@public": "https://public.company.com/{name}.json",
    "@internal": {
      "url": "https://internal.company.com/{name}.json",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    },
    "@premium": {
      "url": "https://premium.company.com/{name}.json",
      "headers": {
        "X-License-Key": "${LICENSE_KEY}"
      }
    }
  }
}

Sunucu tarafında token denetimi

CLI'nin gönderdiği başlığı denetlemek registry sunucusunun işidir. Belgedeki Next.js route handler örneği önce Authorization başlığından, yoksa token sorgu parametresinden token okur; geçersizse 401, token bu bileşene erişemiyorsa 403 döner. Aşağıdaki sürüm belgedeki iki örneğin birleştirilmiş halidir; isValidToken, hasAccessToComponent ve getComponent sizin yazacağınız fonksiyonlardır:

import { NextRequest, NextResponse } from "next/server"

export async function GET(
  request: NextRequest,
  { params }: { params: { name: string } }
) {
  const authHeader = request.headers.get("authorization")
  const token = authHeader?.replace("Bearer ", "")
  const queryToken = request.nextUrl.searchParams.get("token")

  if (!isValidToken(token || queryToken)) {
    return NextResponse.json(
      {
        error: "Unauthorized",
        message: "Authentication required. Set REGISTRY_TOKEN in your .env.local file",
      },
      { status: 401 }
    )
  }

  if (!hasAccessToComponent(token, params.name)) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 })
  }

  const component = await getComponent(params.name)
  return NextResponse.json(component)
}

Belgeye göre yanıt gövdesindeki message alanı CLI tarafından kullanıcıya gösterilir. Bu sayede "aboneliğiniz bitti" ya da "token süresi doldu" gibi duruma özel yönlendirmeler yapabilirsiniz. CLI'nin ayrıca ele aldığı durum kodları 401 (token geçersiz veya eksik), 403 (token bu kaynağa yetkili değil) ve 429'dur (istek sınırı aşıldı). Kurulumu yerelde denemek için belge iki komut önerir:

curl -H "Authorization: Bearer your_token" \
  https://registry.company.com/button.json

REGISTRY_TOKEN=your_token npx shadcn@latest add @private/button

Belgedeki güvenlik önerileri de kısaca şöyledir: token'ları sürüm kontrolüne koymayın, yalnızca HTTPS kullanın, istek sınırlama ekleyin, token'ları düzenli olarak yenileyin ve erişimleri günlüğe kaydedin. Sunucuyu kendi VPS'inizde çalıştırıyorsanız Next.js VPS yayınlama rehberi temel kurulum için yol gösterir.

Bağımlılıklar farklı registry'lerden nasıl çözülür?

Bir öğenin registryDependencies listesinde farklı namespace'lerden öğeler bulunabilir; CLI her birini kendi kaynağından getirir. Belge npx shadcn@latest add @namespace/resource çalıştığında olanları sırayla anlatır: registry bağlamı temizlenir, ana kaynak getirilir, bağımlılıklar özyinelemeli olarak çözülür, kurulum sırası için topolojik sıralama yapılır, dosyalar hedef yola göre tekilleştirilir (aynı hedefte en son gelen kazanır) ve tailwind, cssVars, css, envVars yapılandırmaları derin birleştirilir. Döngüsel bağımlılıklar algılanıp engellenir.

"Son gelen kazanır" kuralı üçüncü taraf bir bileşeni özelleştirmenin resmi yoludur. Belgedeki örnekte satıcının @vendor/button öğesini bağımlılık olarak alan ve yalnızca bir CSS değişkenini değiştiren bir öğe yazılır. npx shadcn@latest add @my-company/custom-button çalıştığında önce orijinal buton kurulur, sonra sizin değerleriniz uygulanır:

{
  "name": "custom-button",
  "type": "registry:ui",
  "registryDependencies": ["@vendor/button"],
  "cssVars": {
    "light": {
      "--button-bg": "purple"
    }
  }
}

Aynı mantıkla npx shadcn@latest add @acme/auth @custom/login-form komutunda, iki kaynak da aynı login-form.ts hedefine yazıyorsa sonradan çözülen @custom/login-form dosyası geçerli olur.

Kurmadan önce incelemek ve aramak

Üçüncü taraf bir registry'ye güvenmeden önce içeriğine bakmak iyi bir alışkanlıktır. view komutu öğenin üst verisini, bağımlılıklarını, kurulacak dosyaların içeriğini, CSS değişkenlerini ve gereken ortam değişkenlerini konsola yazar. search bir veya daha fazla registry'de arama yapar; -q, --query, -l, --limit (varsayılan 100) ve -o, --offset (varsayılan 0) seçeneklerini alır. list ise search komutunun takma adıdır:

npx shadcn@latest view @acme/button
npx shadcn@latest search @acme --query "auth"
npx shadcn@latest search @v0 --limit 10 --offset 20
npx shadcn@latest list @acme

Komutların tamamı CLI komutları yazısında anlatılıyor.

Açık kaynak registry dizini

Eylül 2025'te açık kaynak registry'lerin bir dizini (registry index) yayımlandı. Belgeye göre shadcn add veya shadcn search çalıştırdığınızda CLI aradığınız registry'yi bu dizinde de kontrol eder ve bulursa components.json dosyanıza kendisi ekler. Değişiklik günlüğündeki örnek şudur:

npx shadcn add @ai-elements/prompt-input

Tam liste https://ui.shadcn.com/r/registries.json adresindedir. Kasım 2025'te ise bu registry'leri tarayabileceğiniz Registry Directory sayfası açıldı; sayfa bu registry'lerin CLI'ye gömülü olduğunu ve ek yapılandırma gerektirmediğini söyler. Kendi registry'nizi dizine eklemek için GitHub'daki registry directory issue şablonunu doldurursunuz. Belgedeki koşullar: registry açık kaynak ve herkese açık olmalı, registry şemasına uyan geçerli bir JSON olmalı, iç içe öğe içermeyen düz bir yapıda olmalı (/registry.json ve /component-name.json dosyaları kökte), files dizisinde content özelliği bulunmamalıdır.

Güvenlik modeli

Belge, registry kaynaklarının kod değil veri olarak ele alındığını vurgular: kaynaklar geçerli JSON olmalı, registry öğesi şemasına uymalı, dosyalar yalnızca yapılandırılmış yollara yazılabilir ve CLI registry kaynaklarındaki hiçbir kodu çalıştırmaz. Güven modeli de açıktır: kurduğunuz şeye siz güvenirsiniz, registry'ler components.json içinde açıkça tanımlanmalıdır ve CLI kendiliğinden registry eklemez. Burada bir ayrıntıya dikkat edin: açık kaynak dizininde bulunan bir namespace'i add ile kullandığınızda CLI onu dosyanıza ekler; yani dizindeki registry'ler için bu adımı sizin yerinize yapar.

Hata mesajları

CLI 3.0 ile hata mesajları da yenilendi. Tanımlanmamış bir namespace kullandığınızda belgeye göre şu mesajı görürsünüz:

Unknown registry "@non-existent". Make sure it is defined in components.json as follows:
{
  "registries": {
    "@non-existent": "[URL_TO_REGISTRY]"
  }
}

Gereken bir ortam değişkeni tanımlı değilse:

Registry "@private" requires the following environment variables:

  • REGISTRY_TOKEN

Set the required environment variables to your .env or .env.local file.

Öğe bulunamadığında (404) The item at https://registry.company.com/button.json was not found. It may not exist at the registry. mesajı çıkar; belge bunun genellikle yanlış yazılmış ad, registry'de olmayan kaynak veya hatalı URL kalıbı anlamına geldiğini söyler. 401 ve 403 için belgede yetki ve izin sorunlarını anlatan mesajlar gösterilir. Bu hataların toplu çözüm tablosu sık hatalar yazısında.

Uçtan uca örnek: şirket içi registry bağlamak

Parçaları bir araya getirelim. Ekibinizin https://internal.company.com/{name}.json adresinde token isteyen bir registry'si olduğunu düşünün. Önce components.json içine @internal namespace'ini nesne biçiminde ekler ve Authorization başlığına Bearer ${INTERNAL_TOKEN} yazarsınız. İkinci adımda gerçek token'ı .env.local dosyasına INTERNAL_TOKEN=... olarak koyarsınız. Üçüncü adımda npx shadcn@latest view @internal/auth-form ile öğenin dosyalarını ve bağımlılıklarını incelersiniz; token yanlışsa sorun bu aşamada 401 olarak ortaya çıkar, henüz projenize hiçbir şey yazılmamıştır. Son adımda npx shadcn@latest add @internal/auth-form çalıştırırsınız. Öğe @shadcn/button gibi başka namespace'lerden bağımlılıklar istiyorsa CLI onları kendi adreslerinden ve kendi kimlik doğrulama bağlamlarıyla getirir.

Sık yapılan hatalar

• URL'de {name} unutmak: Yer tutucu zorunludur; yoksa her ad aynı adrese gider.
• Token'ı components.json içine düz yazmak: Değeri ${REGISTRY_TOKEN} olarak yazın, gerçek değeri .env.local dosyasında tutun ve bu dosyayı sürüm kontrolüne eklemeyin.
• Ortam değişkenini tanımlamadan kurulum yapmak: CLI eksik değişkeni adıyla bildirir; değişkeni .env veya .env.local dosyasına ekleyin.
• Aynı adlı kaynakları karıştırmak: Farklı registry'lerde aynı ad olabilir; belge belirsizliği önlemek için tam nitelikli @namespace/resource adlarını kullanmanızı önerir.
• Open in v0 ile namespace kullanmayı denemek: Bu özellik namespace'li registry'leri ve başlık tabanlı kimlik doğrulamayı desteklemez.

Sık Sorulan Sorular

Namespace adımı başkası da kullanabilir mi?

Evet, sistem merkezi değildir. @acme adı yalnızca kendi components.json dosyanızdaki eşlemeyle anlam kazanır. Açık kaynak dizinine eklenmek için yaptığınız başvuru ise belgeye göre ekip tarafından doğrulanıp incelenir.

Özel registry MCP sunucusuyla çalışır mı?

Evet. MCP sunucusu aynı registries alanını okur ve ortam değişkenlerini .env.local dosyasından alır. Ayrıntılar shadcn MCP sunucusu yazısında.

Bir registry'yi farklı ortamlarda farklı sürüme nasıl sabitlerim?

params içinde "version": "${REGISTRY_VERSION}" kullanın ve değişkeni her ortamda farklı ayarlayın. Belge sürüm sabitlemeyi yeniden üretilebilir kurulumlar için önerir.

Registry sunucum hangi formatta yanıt vermeli?

Registry öğesi şemasına uyan JSON. Şemanın alanları registry kurma yazısında tablo halinde anlatılıyor.

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 · Kendi registry'nizi kurun · shadcn MCP sunucusu · components.json ayarları · Sık hatalar