التثبيت

1. هيّئ فاصلة مرة واحدة في كل مشروع. يكتب هذا الأمر الملف components.json، الذي يقرؤه كل أمر add:

npx @smicolon/fasla-ui@latest init

هل أعددت مشروعك بالحزمة @smicolon/cli؟ إذا أعددته بالإصدار 0.4 أو أحدث، فتابع العمل بهذا الأمر في المشروع نفسه، ولا تحتاج إلى إعادة تشغيل أي أمر. وإذا أعددته بالإصدار 0.3 أو أقدم، فشغّل الأمر npx @smicolon/fasla-ui@latest init مرة واحدة أولًا. يُصلح هذا الأمر الملف components.json، الذي لا تستطيع أداة الأوامر في shadcn/ui قراءته قبل ذلك، وينقل الملفات التي وضعتها تلك الإصدارات في مجلد خاطئ.

يكتب الأمر init أيضًا الدالة المساعدة cn، ويثبّت الحزمتين اللتين تستوردهما بمدير الحزم (package manager) في مشروعك. إذا فشل التثبيت، يطبع الأمر init الأمر الذي تشغّله، وهو أحد هذه الأوامر:

npm install clsx tailwind-merge

في Tailwind 3، يثبّت الأمر tailwind-merge@^2، لأن الإصدار 3 من tailwind-merge يدعم Tailwind 4 وحده. ويستبدل الأمر init أيضًا أي tailwind-merge إصداره 3، أو قد يصير 3:

npm install clsx tailwind-merge@^2

2. أضف مكوّنًا:

npx @smicolon/fasla-ui@latest add button

أو أضف عدة مكوّنات دفعة واحدة:

npx @smicolon/fasla-ui@latest add card input badge

اعرض كل ما يقدّمه السجل (registry):

npx @smicolon/fasla-ui@latest list

تبدأ من الصفر: استخدم ألوان فاصلة. تحصل على ألوان فاصلة للوضعين الفاتح والداكن، مع نصف قطر الزوايا (radius) والخط Geist، فوق الطبقة الأساسية:

npx shadcn@latest add https://fasla.smicolon.com/r/theme.json https://fasla.smicolon.com/r/font-geist.json

في Next.js 14، أعِدّ المشروع بالأمر npx @smicolon/fasla-ui@latest init، لا بالأمر shadcn init: يكتب إعداد shadcn/ui أنماط Tailwind 4 ويحمّل الخط Geist من next/font، ولا يتوفر أيٌّ منهما في Next.js 14، فيفشل البناء. ثم احذف الرابط font-geist.json من الأمر، لأن قالب Next.js 14 يحمّل الخط Geist أصلًا:

npx shadcn@latest add https://fasla.smicolon.com/r/theme.json

لديك هوية بصرية: احتفظ بألوانك. تحصل على الطبقة الأساسية وحدها: الـ tokens غير الموجودة في shadcn/ui، مثل النجاح، التحذير، المعلومات، ألوان Soft الخفيفة، مع سلّم أحجام النص بارتفاعات أسطر عربية، وقواعد الكتابة العربية، والخط Cairo. لا تغيّر أي لون موجود في مشروعك:

npx shadcn@latest add https://fasla.smicolon.com/r/theme-base.json

1. ثبّت الاعتماديات (dependency):

npm install class-variance-authority clsx tailwind-merge framer-motion

في Tailwind 3، ثبّت tailwind-merge@^2 بدلًا منها. يدعم الإصدار 3 من tailwind-merge إطار Tailwind 4 وحده، ويحذف في Tailwind 3 الأصناف (classes) التي لا يعرفها، مثل outline:

npm install class-variance-authority clsx tailwind-merge@^2 framer-motion

2. أضف الدالة المساعدة cn إلى مشروعك:

// lib/utils.ts
import { type ClassValue, clsx } from "clsx"
import { extendTailwindMerge } from "tailwind-merge"

const twMerge = extendTailwindMerge({
  extend: { classGroups: { "font-size": [{ text: ["xxs", "link", "list-header"] }] } },
})

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

3. انسخ كل مكوّن من ملفه في السجل (registry)، مثل https://fasla.smicolon.com/r/button.json للمكوّن Button. يسرد الملف https://fasla.smicolon.com/r/registry.json المكوّنات كلها.

في كل ملف، يحمل files الشيفرة المصدرية في content، والمسار الذي تحفظها فيه في target. يسرد dependencies الحزم التي تثبّتها، ويسرد registryDependencies مكوّنات فاصلة الأخرى التي يحتاجها المكوّن، فتنسخها بالطريقة نفسها.