ما هي التطبيقات؟
تتيح لك التطبيقات توسيع Twenty باستخدام كائنات وحقول مخصّصة ووظائف منطقية ومكوّنات الواجهة الأمامية ومهارات الذكاء الاصطناعي وغير ذلك — جميعها تُدار ككود. بدلًا من تكوين كل شيء عبر واجهة المستخدم، تعرّف نموذج بياناتك ومنطقك في TypeScript وتقوم بنشره إلى مساحة عمل واحدة أو أكثر.المتطلبات الأساسية
قبل أن تبدأ، تأكّد من تثبيت ما يلي على جهازك:- Node.js 24+ — نزّل من هنا
- Yarn 4 — يأتي مع Node.js عبر Corepack. قم بتمكينه عبر تشغيل
corepack enable - Docker — نزّل من هنا. مطلوب لتشغيل مثيل محلي من Twenty. غير مطلوب إذا كان لديك خادم Twenty قيد التشغيل بالفعل.
قم بإنشاء تطبيقك الأول
أنشئ هيكل تطبيقك
افتح الطرفية وشغّل:my-twenty-app يحتوي على كل ما تحتاجه.
إعداد مثيل محلي من Twenty
ستسأل أداة إنشاء الهيكل:هل ترغب في إعداد مثيل محلي من Twenty؟
- اكتب
yes(موصى به) — سيؤدي ذلك إلى سحب صورة Dockertwenty-app-devوبدء تشغيل خادم Twenty محلي على المنفذ2020. تأكّد من أن Docker قيد التشغيل قبل المتابعة. - اكتب
no— اختر هذا إذا كان لديك خادم Twenty يعمل محليًا بالفعل.

سجّل الدخول إلى مساحة العمل الخاصة بك
بعد ذلك، ستُفتح نافذة متصفح تعرض صفحة تسجيل الدخول الخاصة بـ Twenty. سجّل الدخول باستخدام حساب العرض التوضيحي المُجهَّز مسبقًا:- البريد الإلكتروني:
tim@apple.dev - كلمة المرور:
tim@apple.dev

قم بتفويض التطبيق
بعد تسجيل الدخول، ستظهر لك شاشة تفويض. يتيح هذا لتطبيقك التفاعل مع مساحة العمل الخاصة بك. انقر Authorize للمتابعة.

ابدأ التطوير
انتقل إلى مجلد تطبيقك الجديد وابدأ خادم التطوير:--verbose:

مزامنة لمرة واحدة باستخدام yarn twenty dev --once
إذا كنت لا تريد تشغيل مراقب في الخلفية (مثلًا في خط أنابيب CI، أو خطاف Git، أو سير عمل مُؤتمت عبر سكربت)، فمرِّر الخيار --once. يُشغِّل خط الأنابيب نفسه مثل yarn twenty dev — إنشاء بيان البناء، تجميع الملفات، الرفع، المزامنة، إعادة توليد عميل API مضبوط الأنواع — ولكنه ينهي التنفيذ فور اكتمال المزامنة:
| أمر | السلوك | متى يُستخدم |
|---|---|---|
yarn twenty dev | يراقب ملفات المصدر ويعيد المزامنة عند كل تغيير. يستمر بالتشغيل حتى توقفه. | تطوير محلي تفاعلي — تريد لوحة حالة مباشرة وحلقة تغذية راجعة فورية. |
yarn twenty dev --once | يجري عملية بناء واحدة + مزامنة واحدة، ثم ينهي التنفيذ برمز 0 عند النجاح أو 1 عند الفشل. | البرامج النصية، وCI، وخطافات ما قبل الالتزام، ووكلاء الذكاء الاصطناعي، وأي سير عمل غير تفاعلي. |
اعرض تطبيقك في Twenty
افتح http://localhost:2020/settings/applications#developer في متصفحك. انتقل إلى Settings > Apps واختر علامة التبويب Developer. يُفترض أن ترى تطبيقك مُدرجًا تحت Your Apps:



src/ وسيتم التقاط التغييرات تلقائيًا.
ما الذي يمكنك بناؤه
تتكون التطبيقات من كيانات — يُعرَّف كل منها كملف TypeScript يحتوي علىexport default واحد:
| كيان | ماذا يفعل |
|---|---|
| الكائنات والحقول | عرّف نماذج بيانات مخصّصة (مثل Post Card، Invoice) مع حقول محددة النوع |
| الوظائف المنطقية | دوال TypeScript على جانب الخادم يتم تشغيلها عبر مسارات HTTP، وجداول cron، أو أحداث قاعدة البيانات |
| المكوّنات الأمامية | مكوّنات React تُعرَض داخل واجهة مستخدم Twenty (اللوحة الجانبية، الودجات، قائمة الأوامر) |
| المهارات والوكلاء | قدرات الذكاء الاصطناعي — تعليمات قابلة لإعادة الاستخدام ومساعدون مستقلون ذاتيًا |
| طرق العرض والتنقّل | طرق عرض القوائم مُعدّة مسبقًا وعناصر قائمة الشريط الجانبي لكائناتك |
| تخطيطات الصفحات | صفحات تفاصيل سجلات مخصصة تتضمن علامات تبويب وعناصر واجهة |
هيكل المشروع
تولّد أداة إنشاء الهيكل بنية الملفات التالية:البدء من مثال
للبدء من مثال أكثر اكتمالًا يضم كائنات وحقولًا مخصّصة، ودوال المنطق، ومكوّنات الواجهة الأمامية، وغير ذلك، استخدم الخيار--example:
yarn twenty add (انظر بناء التطبيقات).
الملفات الرئيسية
| ملف / مجلد | الغرض |
|---|---|
package.json | يصرّح باسم تطبيقك وإصداره واعتماداته. يتضمن نصًا برمجيًا باسم twenty بحيث يمكنك تشغيل yarn twenty help للاطلاع على جميع الأوامر. |
src/application-config.ts | مطلوب. ملف الإعداد الرئيسي لتطبيقك. |
src/default-role.ts | الدور الافتراضي الذي يتحكم بما يمكن لدوال المنطق الوصول إليه. |
src/constants/universal-identifiers.ts | معرّفات UUID وبيانات التعريف للتطبيق، والمولَّدة تلقائيًا (اسم العرض، الوصف). |
src/__tests__/ | اختبارات تكامل (إعداد + اختبار مثال). |
public/ | أصول ثابتة (صور، خطوط) تُقدَّم مع تطبيقك. |
خادم التطوير المحلي
لقد قامت أداة إنشاء الهيكل بالفعل بتشغيل خادم Twenty محليًا لك. لإدارته لاحقًا، استخدمyarn twenty server:
| أمر | الوصف |
|---|---|
yarn twenty server start | بدء الخادم المحلي (يسحب الصورة إذا لزم الأمر) |
yarn twenty server start --port 3030 | ابدأ على منفذ مخصّص |
yarn twenty server start --test | ابدأ مثيل اختبار منفصل على المنفذ 2021 |
yarn twenty server stop | إيقاف الخادم (مع الحفاظ على البيانات) |
yarn twenty server status | عرض حالة الخادم، وعنوان URL، وبيانات الاعتماد |
yarn twenty server logs | بث سجلات الخادم |
yarn twenty server logs --lines 100 | عرض آخر 100 سطر من السجلات |
yarn twenty server reset | حذف جميع البيانات والبدء من جديد |
twenty-app-dev-data لـ PostgreSQL، وtwenty-app-dev-storage للملفات). استخدم reset لمسح كل شيء والبدء من جديد.
تشغيل مثيل الاختبار
مرر--test إلى أي أمر server لإدارة مثيل ثانٍ معزول تمامًا — مفيد لتشغيل اختبارات التكامل أو للتجربة من دون لمس بيانات التطوير الرئيسية لديك.
| أمر | الوصف |
|---|---|
yarn twenty server start --test | بدء مثيل الاختبار (المنفذ الافتراضي 2021) |
yarn twenty server stop --test | إيقاف مثيل الاختبار |
yarn twenty server status --test | عرض حالة مثيل الاختبار، وعنوان URL، وبيانات الاعتماد |
yarn twenty server logs --test | بث سجلات مثيل الاختبار |
yarn twenty server reset --test | محو بيانات الاختبار والبدء من جديد |
twenty-app-dev-test) مع وحدات تخزين مخصصة (twenty-app-dev-test-data, twenty-app-dev-test-storage) وتهيئة مستقلة، بحيث يمكنه العمل بالتوازي مع مثيلك الرئيسي من دون تعارضات. اجمع --test مع --port لتجاوز القيمة الافتراضية 2021.
يتطلّب الخادم أن يكون Docker قيد التشغيل. إذا ظهرت لك رسالة خطأ “Docker not running”، فتأكّد من تشغيل Docker Desktop (أو خادوم Docker).
إعداد يدوي (بدون المهيئ)
إذا كنت تفضّل إعداد الأمور بنفسك بدلًا من استخدامcreate-twenty-app، فيمكنك ذلك بخطوتين.
1. أضِف twenty-sdk وtwenty-client-sdk كاعتمادات:
twenty إلى package.json لديك:
yarn twenty dev، وyarn twenty help، وجميع الأوامر الأخرى.
لا تثبّت
twenty-sdk عالميًا. استخدمه دائمًا كاعتماد محلي للمشروع بحيث يتمكن كل مشروع من تثبيت إصداره الخاص.استكشاف الأخطاء وإصلاحها
إذا واجهت مشاكل:- تأكّد من أن Docker قيد التشغيل قبل تشغيل أداة إنشاء الهيكل مع مثيل محلي.
- تأكّد من أنك تستخدم Node.js 24+ (
node -vللتحقق). - تأكّد من تمكين Corepack (
corepack enable) حتى يتوفر Yarn 4. - جرّب حذف
node_modulesوتشغيلyarn installمرة أخرى إذا بدت الاعتمادات معطّلة.