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

يعني إيه Registry أصلًا؟

code distribution · registry.json · registry item · shadcn add
🎯 الهدف: تفهم الـ registry بيوزّع إيه، ومكوّن من إيه، وإزاي الـ CLI بيوصل لأي item.

الفكرة

الـ shadcn CLI مش بس بيجيب components بتاعة shadcn. تقدر تخليه يجيب كودك إنت من registry إنت عامله.

  • الـ registry ده نظام لتوزيع الكود: components وhooks وصفحات وconfig وrules وأي ملفات تانية.
  • الكود بيتكتب جوه مشروع المستخدم كملفات عادية، مش بيتسطب في node_modules.
  • المستخدم يقدر يعدّل الملفات بعد كده براحته، لأنها بقت بتاعته.
npm بيديك صندوق مقفول، والـ registry بيديك الكود نفسه.

مش لـ React بس

  • الـ registry شغال مع أي نوع مشروع وأي framework.
  • السيرفر بتاع الـ registry نفسه ممكن يبقى Next أو Vite أو Vue أو Svelte أو PHP أو أي حاجة، المهم إنه يقدّم JSON على HTTP.
  • أو ممكن ميبقاش فيه سيرفر خالص: GitHub repo فيه registry.json في الـ root.

تقدر توزّع إيه؟

النوعأمثلة ملفات
UIcomponents/ui/date-picker.tsx
Helperslib/format-money.ts، hooks/use-copy.ts
Design systemstyles/theme.css، tokens، components كاملة
Feature كاملةصفحات auth + lib/auth.ts + الفورم
Rules للـ AI agentsAGENTS.md، .cursor/rules/*، .claude/commands/*
Conventions.editorconfig، biome.json، docs
Testingvitest.config.ts، test/setup.ts
CI.github/workflows/ci.yml
Templatesissue templates، PR template
Codemodscodemods/*، scripts/migrate.ts
MCP config.mcp.json، .cursor/mcp.json

الـ registry مكوّن من إيه؟

registry.json — الفهرس

ملف واحد في الـ root فيه اسم الـ registry والـ homepage وقائمة كل الـ items. ده اللي list وsearch بيقروه.

item.json — الوصفة

ملف لكل item، فيه الملفات بمحتواها، والـ packages المطلوبة، والـ CSS variables. ده اللي view وadd بيقروه.

الـ CLI بيوصل للـ item إزاي؟

في 5 أشكال للعنوان، وهتشوفهم في كل المذكرة:

terminal
npx shadcn@latest add button                            # اسم بس = item من shadcn نفسهnpx shadcn@latest add @nile/money-input                 # namespace متعرّف في components.jsonnpx shadcn@latest add nile-team/ui/money-input          # GitHub: owner/repo/itemnpx shadcn@latest add https://nile.dev/r/money-input.json  # URL مباشرnpx shadcn@latest add ./registry/money-input.json       # ملف local
  • الاسم لوحده زي button معناه دايمًا الـ item الرسمي بتاع shadcn، حتى لو إنت جوه registry تاني.
  • @nile/... محتاج تعريف للـ namespace في components.json، أو يكون الـ namespace متسجل في الـ Registry Directory.
  • owner/repo/item بيقرا من GitHub على طول، من غير سيرفر ومن غير config.

3 طرق تقدّم بيها الـ registry

  1. ملفات JSON static: تعمل shadcn build وترفع الناتج على أي hosting.
  2. Route handlers: السيرفر يبني الـ JSON وقت الطلب من registry.json الأصلي.
  3. GitHub repo: تحط registry.json في الـ root وخلاص.

وفي البداية خالص، shadcn عامل registry template جاهز تبدأ منه.

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

🧠 اختبر نفسك
١) إيه الفرق الأساسي بين registry item وnpm package؟
الـ item بيتكتب كملفات جوه مشروعك وتقدر تعدّلها، والـ package بيفضل في node_modules.
٢) shadcn add button جوه مشروع متعرّف فيه @nile. هيجيب button منين؟
من shadcn الرسمي. الاسم لوحده مش بيتربط بأي registry تاني.
٣) أنهي ملف بيقراه list وأنهي بيقراه add؟
list وsearch بيقروا registry.json، وview وadd بيقروا ملف الـ item.