الإضافة عبر الطرفية

التهيئة مرة واحدة

يتعرّف init على إطار العمل ومدير الحزم، ثم ينسخ الشيفرة المشتركة ويعدّل ملف CSS.

$ npx topclassui init

Detected Next.js 16.4.2, App Router, TypeScript 5.9.3, Tailwind 4.3.3
Detected npm (default)
CSS entry  app/globals.css
Folder     topclassui
svg → topclassui/components/svg/ (button imports it)
button → topclassui/components/button/ (toast imports it)
toast → topclassui/components/toast/ (base imports it)
base → topclassui/
Added to app/globals.css:
  @import "../topclassui/tokens.css";
  @import "../topclassui/styles.css";
Wrote 106 files and topclassui.json

ثم يثبّت @base-ui/react وclass-variance-authority وclsx وtailwind-merge وzod، ويطبع أسطر المزوّد التي تضعها في التخطيط؛ ولا يعدّل التخطيط بنفسه أبدًا. وإذا كان التخطيط يركّب المزوّد من الحزمة توقّف init، لأن النسخ تقرأ المزوّد المنسوخ؛ والخيار --force يمضي على أي حال.

أضف مكوّنًا

ينسخ add المكوّن وكل ما يستورده. اذكر مكوّنًا واحدًا أو أكثر، أو مرّر --all.

$ npx topclassui add select

select → topclassui/components/select/

# الأمر نفسه مع كل مدير حزم
$ pnpm dlx topclassui add select
$ yarn dlx topclassui add select
$ bunx topclassui add select

يطبع list كل المكوّنات وما يوجد منها في مشروعك؛ و--json يطبع القائمة نفسها بصيغة JSON.

ما يصل إلى مشروعك

مجلد واحد لكل ما نضيفه. شيفرتك تبقى كما هي.

• your-app/
• app/
• globals.cssيضيف إليه init سطرَي استيراد
• topclassui/كل ما نضيفه، في مجلد واحد
• components/
• button/يجلبه init، فالإشعار يستورده
• index.tsxالمكوّن، يُعرض على الخادم
• variants.tsمظهره
• classes.tsثوابت أصنافه
• constants.tsقيمه الافتراضية
• types.tsخصائصه
• schema.tsقواعد الخصائص
• boundaries.tsالحدود التي يفرضها
• skeleton.tsxحالة التحميل
• dummy/أمثلة عاملة، مثال في كل ملف
• select/npx topclassui add select
• client.tsxالجزء التفاعلي وحده
• hook.tsالحالة والتأثيرات والمعالجات
• lib.tsدوال خالصة، بلا React
• shared/cn وclasses وcontracts وlabels وprovider وtheme
• icons/ملف لكل أيقونة تستخدمها نسخة
• tokens.cssكل متغيّرات --tc-*
• styles.cssربط @theme والمتغيّرات الشرطية
• topclassui.jsonإعداداتك

استورد من المجلد لا من الحزمة: import { Button } from '@/topclassui/components/button'. النسخ تستورد بعضها بمسارات نسبية.

ملف الإعدادات

يكتبه init ويقرؤه add وdiff. الحقل lock يسجّل كل ملف منسوخ مع إصداره وبصمته، فاتركه للطرفية.

{
  "version": 1,
  "framework": "next-app",
  "css": "app/globals.css",
  "dir": "topclassui",
  "imports": "relative",
  "packageManager": "npm",
  "lock": {
    "registry": "0.1.0-beta.3",
    "files": {
      "components/button/index.tsx": { "from": "button", "version": "0.1.0-beta.3", "sha256": "…" }
    }
  }
}

عندما تعدّل ملفًا منسوخًا

لا يكتب add فوق تعديلاتك أبدًا. يعرض diff ما تغيّر؛ و--overwrite يستبدل الملف ويطبع الفرق أولًا.

$ npx topclassui diff select

select: 1 of 20 files differ
  components/select/classes.ts: modified locally

$ npx topclassui add select --overwrite

يخرج diff بالرمز 1 إذا وُجد أي اختلاف. وبعد تحديث الحزمة، يكتب add --update الإصدار الجديد من كل ملف لم تلمسه.

التشغيل بلا أسئلة

npx topclassui init --yes                # يقبل كل القيم الافتراضية
npx topclassui add button --yes
npx topclassui add button --dry-run      # يطبع ما سيكتبه ولا يكتب شيئًا

كل أمر يقبل أيضًا --cwd <dir> لمشروع خارج المجلد الحالي.

ما لا يفعله أبدًا