المتطلبات الأساسية
- Node.js 24.5+ — تنزيل
- Yarn 4 — يأتي مع Node.js عبر Corepack. قم بتمكينه:
corepack enable - Docker — تنزيل. مطلوب لتشغيل خادم Twenty محليًا. تخطَّ ذلك إذا كان لديك Twenty يعمل في مكان آخر.
المرحلة 1 — تهيئة هيكل مشروعك
أنشئ تطبيقًا جديدًا من القالب:--display-name و--description لتخصيص البيانات الوصفية المُولَّدة (يمكنك أيضًا تعديلها لاحقًا في src/constants/universal-identifiers.ts). يُنشئ هذا مشروع TypeScript في my-twenty-app/ يتضمّن ملف بداية application-config.ts، ودورًا افتراضيًا، وسير عمل CI/CD، واختبار تكامل.
بعد هذه المرحلة: سيكون لديك الشفرة المصدرية لتطبيق على جهازك. ليس قيد التشغيل بعد — وهذه هي المرحلة 2.
المرحلة 2 — تشغيل خادم Twenty محلي
يحتاج تطبيقك إلى خادم Twenty للمزامنة معه. الخادم هو مثيل Twenty كامل — واجهة مستخدم، واجهة برمجة تطبيقات GraphQL، PostgreSQL — يعمل محليًا داخل Docker. ترفع شفرتك المحلية تعريفاتها إلى ذلك الخادم، مما يجعلها تظهر في واجهة المستخدم. يقوم مُنشئ الهياكل بتشغيل مثيل لك: مع تشغيل Docker، يسحب صورةtwentycrm/twenty-app-dev، ويبدأها على المنفذ 2020، ويُجري مصادقة أداة CLI على مساحة العمل التجريبية المهيأة مسبقًا (tim@apple.dev) — دون الحاجة إلى تسجيل الدخول.
للاتصال بخادم Twenty موجود بدلاً من ذلك، مرِّر الخيار --url \<your-server-url>. تُجري الخوادم البعيدة المصادقة باستخدام OAuth: يفتح المتصفح حتى تتمكن من تسجيل الدخول والنقر على Authorize، مما يمنح أداة CLI حق الوصول إلى مساحة عملك. (يمكنك أيضًا اختيار استخدام OAuth محليًا باستخدام --authentication-method oauth — سجِّل الدخول باستخدام tim@apple.dev / tim@apple.dev.)
إذا لم يكن Docker مثبتًا أو قيد التشغيل، فستخبرك أداة توليد الهيكل بأمر البدء المناسب لنظام التشغيل لديك. عند تشغيل Docker، يمكنك المتابعة باستخدام
yarn twenty docker:start — لا حاجة لإعادة إنشاء الهيكل.المرحلة 3 — مزامنة تغييراتك
هذه هي الحلقة الداخلية التي ستقضي معظم وقتك فيها.src/، ويُعيد البناء عند كل تغيير، ويزامن الناتج إلى الخادم. حرّر ملفًا، واحفظه، وخلال بضع ثوانٍ سينعكس التغيير على الخادم. سترى لوحة حالة مباشرة في الطرفية.
للحصول على مخرجات أكثر تفصيلاً (سجلات البناء، طلبات المزامنة، تتبعات الأخطاء)، أضِف --verbose.
src/ وسيظهر في واجهة المستخدم.
مزامنة لمرة واحدة لـ CI والبرامج النصية
استخدمplan وapply لتشغيل نفس خط الأنابيب مرة واحدة، بدون أداة مراقبة (watcher):
جميع الأوضاع تحتاج إلى جهة بعيدة موثَّقة. راجع قسم المزامنة والاستعادة للحصول على مزيد من المعلومات حول
plan.
الأوامر
yarn twenty dev --once وyarn twenty dev --once --dry-run هي أسماء بديلة مهملة للأمرين yarn twenty apply وyarn twenty plan.خيارات وضع التطوير
ما الذي يمكنك بناؤه
تتكون التطبيقات من كيانات — يُعرَّف كل منها كملف TypeScript يحتوي علىexport default واحد:
مرجع كامل: المفاهيم.
الخطوات التالية
التهيئة
هوية التطبيق، الدور الافتراضي، وخطّافات التثبيت، والأصول العامة.
بيانات
الكائنات، الحقول، والعلاقات ثنائية الاتجاه.
المنطق
الوظائف المنطقية، المهارات، الوكلاء، واتصالات OAuth.
التخطيط
العروض، التنقل، تخطيطات الصفحات، ومكوّنات الواجهة الأمامية.
العمليات
سطر الأوامر (CLI)، الاختبار، الوجهات البعيدة، التكامل المستمر (CI)، ونشر تطبيقك.