الانتقال إلى المحتوى الرئيسي

​
المتطلبات الأساسية

  • Node.js 24+ — تنزيل
  • Yarn 4 — يأتي مع Node.js عبر Corepack. قم بتمكينه: corepack enable
  • Docker — تنزيل. مطلوب لتشغيل خادم Twenty محليًا. تخطَّ ذلك إذا كان لديك Twenty يعمل في مكان آخر.
يتكوّن إنشاء تطبيق Twenty من ثلاث مراحل. تقوم أداة توليد الهيكل بدمجها في أمر واحد لمسار الاستخدام المثالي، لكن كل مرحلة تمثّل مفهومًا منفصلًا — وعند حدوث فشل، فإن معرفة المرحلة التي أنت فيها تُخبرك بما ينبغي إصلاحه.
المرحلةماذا تفعلالأداةالنتيجة
1. تهيئة الهيكلتوليد الشفرة المصدرية للتطبيقnpx create-twenty-appمشروع TypeScript على القرص
2. تشغيل خادمبدء تشغيل خادم Twenty للمزامنة معهDocker + yarn twenty serverمثيل Twenty قيد التشغيل
3. مزامنةقم بمزامنة شفرتك مباشرةً مع الخادمyarn twenty devتظهر تغييراتك في واجهة المستخدم

​
المرحلة 1 — تهيئة هيكل مشروعك

أنشئ تطبيقًا جديدًا من القالب: 
npx create-twenty-app@latest my-twenty-app
ستتم مطالبتك باسم ووصف — اضغط Enter للقيم الافتراضية. يُنشئ هذا مشروع TypeScript في my-twenty-app/ يتضمن ملف بداية application-config.ts، ودورًا افتراضيًا، وسير عمل CI، واختبار تكامل. بعد هذه المرحلة: سيكون لديك الشفرة المصدرية لتطبيق على جهازك. ليس قيد التشغيل بعد — وهذه هي المرحلة 2.

​
المرحلة 2 — تشغيل خادم Twenty محلي

يحتاج تطبيقك إلى خادم Twenty للمزامنة معه. الخادم هو مثيل Twenty كامل — واجهة مستخدم، واجهة برمجة تطبيقات GraphQL، PostgreSQL — يعمل محليًا داخل Docker. ترفع شفرتك المحلية تعريفاتها إلى ذلك الخادم، مما يجعلها تظهر في واجهة المستخدم. تقترح أداة توليد الهيكل تشغيل خادم لك:
هل ترغب في إعداد مثيل محلي من Twenty؟
  • نعم (موصى به) — ستسحب صورة Docker twentycrm/twenty-app-dev وتبدأ تشغيلها على المنفذ 2020. تأكّد أولًا من أن Docker قيد التشغيل.
  • لا — اختر هذا إذا كان لديك بالفعل خادم Twenty تريد الاتصال به. يمكنك ربطه لاحقًا باستخدام yarn twenty remote:add.
هل يجب بدء المثيل المحلي؟
بمجرد أن يصبح الخادم جاهزًا، سيفتح المتصفح لإجراء تسجيل الدخول. استخدم حساب العرض التوضيحي المُجهَّز مسبقًا:
  • البريد الإلكتروني: tim@apple.dev
  • كلمة المرور: tim@apple.dev
شاشة تسجيل الدخول إلى Twenty
انقر Authorize في الشاشة التالية — يمنح هذا واجهة سطر الأوامر CLI حق الوصول إلى مساحة العمل الخاصة بك.
شاشة تفويض واجهة الأوامر (CLI) الخاصة بـ Twenty
ستؤكّد الطرفية أن كل شيء قد تم إعداده.
تم إنشاء هيكل التطبيق بنجاح
بعد هذه المرحلة: لديك خادم Twenty قيد التشغيل على http://localhost:2020، مع تفويض CLI لديك للمزامنة معه.
إذا لم يكن Docker مثبتًا أو قيد التشغيل، فستخبرك أداة توليد الهيكل بأمر البدء المناسب لنظام التشغيل لديك. عند تشغيل Docker، يمكنك المتابعة باستخدام yarn twenty docker:start — لا حاجة لإعادة إنشاء الهيكل.

​
المرحلة 3 — مزامنة تغييراتك

هذه هي الحلقة الداخلية التي ستقضي معظم وقتك فيها. 
cd my-twenty-app
yarn twenty dev
يراقب هذا المجلد src/، ويُعيد البناء عند كل تغيير، ويزامن الناتج إلى الخادم. حرّر ملفًا، واحفظه، وخلال بضع ثوانٍ سينعكس التغيير على الخادم. سترى لوحة حالة مباشرة في الطرفية. للحصول على مخرجات أكثر تفصيلاً (سجلات البناء، طلبات المزامنة، تتبعات الأخطاء)، أضِف --verbose.
مخرجات الطرفية في وضع التطوير
افتح http://localhost:2020/settings/applications#developer. يفترض أن ترى تطبيقك ضمن Your Apps.
قائمة "Your Apps" تعرض "My twenty app"
انقر My twenty app لعرض تسجيل التطبيق — وهو سجل على مستوى الخادم يصف تطبيقك (الاسم، المعرّف، بيانات اعتماد OAuth، المصدر). يمكن تثبيت تسجيل واحد عبر عدة مساحات عمل على الخادم نفسه.
تفاصيل تسجيل التطبيق
انقر View installed app لعرض التثبيت في مساحة العمل. تعرض علامة التبويب About الإصدار وخيارات الإدارة.
التطبيق المثبت
بعد هذه المرحلة: لديك دورة تطوير حيّة. حرّر أي ملف في src/ وسيظهر في واجهة المستخدم.

​
مزامنة لمرة واحدة لـ CI والبرامج النصية

مرّر --once لتشغيل عملية بناء واحدة + مزامنة واحدة ثم الخروج — نفس خط الأنابيب، من دون مراقِب: 
yarn twenty dev --once
أمرالسلوكمتى يُستخدم
yarn twenty devيراقب ويعيد المزامنة عند كل تغيير. يستمر في العمل حتى توقفه.تطوير محلي تفاعلي.
yarn twenty dev --onceبناء واحد + مزامنة واحدة، يخرج برمز 0 عند النجاح، و1 عند الفشل.CI، وخطافات ما قبل الالتزام، ووكلاء الذكاء الاصطناعي، وسير عمل مكتوب بنصوص.
yarn twenty dev --once --dry-runيبني تغييرات البيانات الوصفية ويطبعها من دون تطبيقها.فحص ما الذي سيُغيِّره التزامن قبل تطبيقه.
كلا الوضعين يحتاجان إلى جهة بعيدة موثَّقة. راجع قسم المزامنة والاستعادة للحصول على المزيد من المعلومات حول --dry-run.

​
خيارات وضع التطوير

خيارالوصف
--onceقم بالإنشاء والمزامنة مرة واحدة، ثم اخرج.
--dry-runباستخدام --once، يمكنك معاينة تغييرات البيانات الوصفية دون تطبيقها. لا يكتب أي شيء.
--debounceMs \<ms>اضبط مهلة إزالة الارتداد لتغييرات الملفات بالميلي ثانية (القيمة الافتراضية: 2000).
--verbose / --debugإظهار سجلات إنشاء تفصيلية، وطلبات المزامنة، وتتبع الأخطاء.

​
ما الذي يمكنك بناؤه

تتكون التطبيقات من كيانات — يُعرَّف كل منها كملف TypeScript يحتوي على export default واحد:
كيانماذا يفعل
الكائنات والحقولنماذج بيانات مخصّصة (بطاقة بريدية، فاتورة، إلخ) بحقول ذات أنواع محددة
الوظائف المنطقيةTypeScript على جانب الخادم يتم تشغيله عبر مسارات HTTP، أو جداول cron، أو أحداث قاعدة البيانات
المكوّنات الأماميةمكوّنات React تُعرَض داخل واجهة مستخدم Twenty (اللوحة الجانبية، الودجات، قائمة الأوامر)
المهارات والوكلاءقدرات الذكاء الاصطناعي — تعليمات قابلة لإعادة الاستخدام ومساعدون مستقلون ذاتيًا
طرق العرض والتنقّلطرق عرض قوائم مُعدّة مسبقًا وعناصر قائمة الشريط الجانبي
تخطيطات الصفحاتصفحات تفاصيل سجلات مخصصة تتضمن علامات تبويب وعناصر واجهة
مرجع كامل: المفاهيم.

​
الخطوات التالية

التهيئة

هوية التطبيق، الدور الافتراضي، وخطّافات التثبيت، والأصول العامة.

بيانات

الكائنات، الحقول، والعلاقات ثنائية الاتجاه.

المنطق

الوظائف المنطقية، المهارات، الوكلاء، واتصالات OAuth.

التخطيط

العروض، التنقل، تخطيطات الصفحات، ومكوّنات الواجهة الأمامية.

العمليات

سطر الأوامر (CLI)، الاختبار، الوجهات البعيدة، التكامل المستمر (CI)، ونشر تطبيقك.