مذكرات سعيد
اتقرأ🔖
البداية · فصل ٣

registry-item.json — كل حقل في الوصفة

type · dependencies · registryDependencies · files · target · envVars · docs · meta
🎯 الهدف: تعرف كل حقل في الـ item، وخصوصًا الأنواع والـ dependencies ومكان كتابة الملفات بـ target.

شكل الـ item كامل

public/r/checkout-card.json
{  "$schema": "https://ui.shadcn.com/schema/registry-item.json",  "name": "checkout-card",  "type": "registry:block",  "title": "Checkout Card",  "description": "كارت دفع بالجنيه فيه money-input وزرار.",  "author": "Saeed <saeed@nile.dev>",  "registryDependencies": ["button", "@nile/money-input"],  "dependencies": ["zod@^3.23.0", "motion"],  "devDependencies": ["@types/mdx"],  "files": [    { "path": "registry/default/checkout-card/checkout-card.tsx", "type": "registry:component" },    { "path": "registry/default/checkout-card/use-checkout.ts", "type": "registry:hook" }  ],  "cssVars": {    "light": { "brand": "oklch(0.55 0.17 160)" },    "dark": { "brand": "oklch(0.7 0.15 160)" }  },  "docs": "محتاج NILE_PAY_KEY في .env.local عشان الدفع يشتغل.",  "categories": ["checkout", "forms"],  "meta": { "version": "1.2.0" }}

الحقول الأساسية

  • $schema: رابط registry-item.json schema.
  • name: الاسم اللي الـ item بيتعرف بيه، ولازم يكون unique جوه الـ registry بتاعك.
  • title: عنوان قصير يتقري.
  • description: شرح أطول من الـ title. مهم جدًا للـ AI والـ MCP.
  • author: صاحب الـ item، ممكن يختلف عن صاحب الـ registry.

type — نوع الـ item

النوع بيحدد الـ item ده إيه، وبيحدد كمان الملف هيتكتب فين في المشروع.

النوعتستخدمه لـ
registry:uicomponent UI أو primitive في ملف واحد
registry:componentcomponent بسيط
registry:blockحاجة أكبر من كذا ملف، زي فورم login كامل
registry:hookReact hook
registry:libutils ودوال مساعدة
registry:pageصفحة أو route
registry:fileأي ملف تاني، زي config
registry:stylestyle كامل زي new-york
registry:themetheme ألوان
registry:fontخط
registry:basedesign system كامل بإعداده
registry:itemitem عام (universal) مش مربوط بنوع

الـ dependencies — 3 أنواع

dependencies

npm packages بتتسطب مع الـ item. الـ version بـ @، زي zod@^3.23.0.

devDependencies

npm packages للـ development بس، زي tw-animate-css أو @types/mdx.

registryDependencies — items تانية لازم تتسطب قبله

كل عنصر فيها عنوان item، وليه 5 أشكال:

registry-item.json
{  "registryDependencies": [    "button",    "@nile/money-input",    "nile-team/ui/otp-input#v1.2.0",    "https://nile.dev/r/editor.json",    "./editor.json"  ]}
  • button: اسم لوحده = item من shadcn الرسمي.
  • @nile/money-input: item من namespace.
  • nile-team/ui/otp-input: item من GitHub repo، والأحسن تثبّته بـ tag أو commit SHA كامل في الـ registries المنشورة.
  • URL: رابط ملف item مباشر.
  • ./editor.json: ملف item على الـ disk.

files — الملفات

كل ملف ليه path وtype، وtarget اختياري:

  • path: مكان الملف في الـ registry. الـ build بيقراه ويحوّله ويحط محتواه في content.
  • type: نوع الملف، بنفس قائمة الأنواع اللي فوق.
  • target: مكان الملف في مشروع المستخدم.

إمتى target إجباري؟

  • إجباري مع registry:page وregistry:file.
  • في الباقي: الـ CLI بيقرا components.json بتاع المستخدم ويحدد المكان لوحده حسب الـ type.
  • ~: معناها root المشروع، زي ~/nile.config.ts.
registry-item.json
{  "files": [    { "path": "registry/default/checkout/page.tsx", "type": "registry:page", "target": "app/checkout/page.tsx" },    { "path": "registry/default/checkout/nile.config.ts", "type": "registry:file", "target": "~/nile.config.ts" },    { "path": "registry/default/checkout/.env.example", "type": "registry:file", "target": "~/.env.example" }  ]}

الـ placeholders في target

بدل ما تكتب components/ui بإيدك وتلاقي المستخدم شغال بـ src أو monorepo، استخدم placeholder بيتحل من aliases في components.json بتاعه:

الـ placeholderبيتحل لـ
@components/aliases.components
@ui/aliases.ui
@lib/aliases.lib
@hooks/aliases.hooks
  • بيشتغل مع أي import prefix: سواء المشروع بيستخدم @/ أو # أو package imports أو workspace exports.
  • أي حاجة بعده بتتساب زي ما هي: @ui/payments/money-input.tsx بيتكتب جوه فولدر الـ ui عند المستخدم في payments/money-input.tsx.
  • في أول الـ target بس: components/@ui/x.tsx بيتعامل كمسار عادي.
  • placeholder مش معروف زي @foo/bar.ts بيتكتب foo/bar.ts عادي.
  • @utils/ مش مدعوم، لأن utils بيشاور على ملف مش فولدر.
  • الـ target أقوى من الـ type: ملف type بتاعه registry:ui وtarget بتاعه @lib/format-money.ts هيتكتب في lib.
  • في الـ dependencies كمان: الـ items اللي في registryDependencies تقدر تستخدم نفس الـ placeholders.

envVars

registry-item.json
{  "envVars": {    "NEXT_PUBLIC_APP_URL": "http://localhost:3000",    "NILE_PAY_KEY": ""  }}
  • مكان الكتابة: بتتكتب في .env.local أو .env.
  • مش بتمسح حاجة: أي متغير موجود قبل كده مش بيتكتب فوقه.
  • قيم dev بس: استخدمها لقيم development أو أمثلة، وأوعى تحط فيها قيم production، لأن الـ JSON ده بيوصل لأي حد.

حقول تانية

  • docs: رسالة بتظهر للمستخدم في الـ terminal بعد الـ install، زي “هات الـ key من الموقع الفلاني”.
  • categories: tags لتنظيم الـ items، زي ["sidebar", "dashboard"].
  • meta: أي key/value إنت عايزه، لأدواتك أو scripts بتاعتك.
  • cssVars وcss وfont وtailwind وextends وconfig: ليهم الفصل الجاي كله.

خلّصت الفصل لما

🧠 اختبر نفسك
١) item فيه ملف registry:file من غير target. إيه المشكلة؟
target إجباري للـ registry:file والـ registry:page.
٢) target بتاعه @utils/cn.ts. هيشتغل؟
لأ. @utils/ مش مدعوم لأن utils بيشاور على ملف، فمش هيتحل لفولدر الـ utils عند المستخدم. استخدم @lib/cn.ts.
٣) envVars فيها DATABASE_URL والمستخدم عنده DATABASE_URL في .env.local. هيحصل إيه؟
مش هيتغير. الـ CLI مش بيكتب فوق متغير موجود.
٤) ملف type بتاعه registry:ui وtarget بتاعه @lib/x.ts. هيتكتب فين؟
في فولدر lib، لأن الـ target هو اللي بيحدد المكان.