Cheat Sheet: shadcn Registry · مذكرات سعيد

الـ registry إيه؟نظام توزيع كود بيكتب ملفات في مشروع المستخدم، مش npm package

لـ React بس؟لأ، أي framework وأي ملفات، طالما JSON على HTTP أو GitHub repo

الفهرسregistry.json في الـ root: name وhomepage وitems وinclude

ملف الـ itemفيه الملفات بالـ content، وview/add بيقروه

list وsearchعلى الفهرس، URL أو @ns، مش ملف local

includeمسار صريح لـ registry.json، من غير اختصار فولدر

path مع includeنسبي للـ registry.json اللي معرّف الـ item

أسماء الـ itemsunique في الـ registry كله بعد التجميع

registryDependenciesbutton أو @ns/x أو owner/repo/x#ref أو URL أو ./x.json

اسم لوحده زي buttonدايمًا item من shadcn الرسمي

npm packagesdependencies وdevDependencies، والـ version بـ @

target إجباريمع registry:page وregistry:file

~/root مشروع المستخدم

مسارات المستخدم@ui/ و@components/ و@lib/ و@hooks/، و@utils/ مش مدعوم

envVarsبتتكتب في .env.local من غير overwrite، وقيم dev بس

لون جديدcssVars.light وdark، فتقدر تستخدم bg-brand

متغير TailwindcssVars.theme، وtailwind.config deprecated

ترتيب الـ CSS@import ثم @plugin ثم الباقي، والـ plugin يتحط في dependencies

animation@keyframes في css + --animate-* في cssVars.theme

خطregistry:font + font، وselector بيقصّر الـ class على selectors

design systemregistry:base + config، وextends: none للصفر

طلّع JSONshadcn build، والناتج في public/r، وتغيّره بـ -o

من غير buildloadRegistry وloadRegistryItem في route handlers

URL واحد لكلهAccept application/vnd.shadcn.v1+json + Vary

universal itemكل ملف ليه target، ويتسطب من غير components.json

GitHub registryregistry.json في الـ root، وadd owner/repo/item

ثبّت إصدار#v1.0.0 أو SHA كامل، والـ ref مش بيتورّث

GitHub privategh auth login أو GH_TOKEN (Contents: Read-only)

validateshadcn registry validate owner/repo#ref

namespaceshadcn registry add @ns=https://x/r/{name}.json

الـ URL template{name} إجباري، و{style} اختياري، و${VAR} من env

authheaders أو params في components.json، والقيمة في .env.local

ملفين بنفس الـ targetالأخير في الحل بيكسب، فتعمل override بيه

versioningparams: { version } و${VAR:-default}

401 / 403 / 429token غلط / مفيش صلاحية / rate limit

رسالة للمستخدمmessage في body الـ error

قبل التثبيتview، وadd --dry-run و--diff و--view

registry فيها آلاف itemsdynamic search: q وtype وlimit وoffset + pagination

DirectoryPR على directory.json: open source وflat ومن غير content

HealthObserving / Healthy / Degraded / Unavailable، وسكور 45+25+20+10

الترتيب0.8 × health + 20 × حجم، والحجم بيقف عند 500

MCPفهرس اسمه registry في الـ root + shadcn mcp init --client

Open in v0v0.dev/chat/api/open?url=، من غير cssVars/css/envVars/namespaces

APIshadcn/registry وshadcn/schema وshadcn/preset بس

سيرفر شغال على طولuseCache: false

خلّصت المذكرة لما

🧠 اختبر نفسك

١) عايز توزّع AGENTS.md لكل مشاريع الفريق من غير سيرفر. أسهل طريقة؟

GitHub repo فيه registry.json، وitem نوعه registry:file وtarget بتاعه ~/AGENTS.md، وبعدها add owner/repo/item.

٢) عايز تغيّر لون button من vendor. تعمل إيه؟

item بتاعك فيه registryDependencies للـ vendor button وcssVars جديدة.

٣) registry private للشركة على سيرفر خاص. GitHub address ولا namespace؟

namespace بـ headers للـ auth والـ token في .env.local.