Documentation Index
Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
Use this file to discover all available pages before exploring further.
ما هي التطبيقات؟
تتيح لك التطبيقات توسيع Twenty باستخدام كائنات وحقول مخصّصة ووظائف منطقية ومكوّنات الواجهة الأمامية ومهارات الذكاء الاصطناعي وغير ذلك — جميعها تُدار ككود. بدلًا من تكوين كل شيء عبر واجهة المستخدم، تعرّف نموذج بياناتك ومنطقك في TypeScript وتقوم بنشره إلى مساحة عمل واحدة أو أكثر.
المتطلبات الأساسية
قبل أن تبدأ، تأكّد من تثبيت ما يلي على جهازك:
- Node.js 24+ — نزّل من هنا
- Yarn 4 — يأتي مع Node.js عبر Corepack. قم بتمكينه عبر تشغيل
corepack enable
- Docker — نزّل من هنا. مطلوب لتشغيل مثيل محلي من Twenty. غير مطلوب إذا كان لديك خادم Twenty قيد التشغيل بالفعل.
قم بإنشاء تطبيقك الأول
أنشئ هيكل تطبيقك
افتح الطرفية وشغّل:
npx create-twenty-app@latest my-twenty-app
my-twenty-app يحتوي على كل ما تحتاجه.
إعداد مثيل محلي من Twenty
ستسأل أداة إنشاء الهيكل:
هل ترغب في إعداد مثيل محلي من Twenty؟
- اكتب
yes (موصى به) — سيؤدي ذلك إلى سحب صورة Docker twenty-app-dev وبدء تشغيل خادم Twenty محلي على المنفذ 2020. تأكّد من أن Docker قيد التشغيل قبل المتابعة.
- اكتب
no — اختر هذا إذا كان لديك خادم Twenty يعمل محليًا بالفعل.
سجّل الدخول إلى مساحة العمل الخاصة بك
بعد ذلك، ستُفتح نافذة متصفح تعرض صفحة تسجيل الدخول الخاصة بـ Twenty. سجّل الدخول باستخدام حساب العرض التوضيحي المُجهَّز مسبقًا:
- البريد الإلكتروني:
tim@apple.dev
- كلمة المرور:
tim@apple.dev
قم بتفويض التطبيق
بعد تسجيل الدخول، ستظهر لك شاشة تفويض. يتيح هذا لتطبيقك التفاعل مع مساحة العمل الخاصة بك.
انقر Authorize للمتابعة.
بمجرد منح التفويض، ستؤكّد الطرفية أن كل شيء قد تم إعداده.
ابدأ التطوير
انتقل إلى مجلد تطبيقك الجديد وابدأ خادم التطوير:
cd my-twenty-app
yarn twenty dev
--verbose:
yarn twenty dev --verbose
وضع التطوير متاح فقط على مثيلات Twenty التي تعمل في وضع التطوير (NODE_ENV=development). المثيلات الإنتاجية ترفض طلبات مزامنة وضع التطوير. استخدم yarn twenty deploy للنشر إلى خوادم الإنتاج — اطّلع على نشر التطبيقات للتفاصيل. مزامنة لمرة واحدة باستخدام 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:
انقر على My twenty app لفتح تسجيل التطبيق الخاص به. التسجيل عبارة عن سجل على مستوى الخادم يصف تطبيقك — اسمه، والمعرّف الفريد، وبيانات اعتماد OAuth، والمصدر (محلي، npm، أو tarball). يُخزَّن على الخادم، وليس داخل أي مساحة عمل محددة. عند تثبيت تطبيق في مساحة عمل، ينشئ Twenty تطبيقًا بنطاق مساحة العمل يُشير مرة أخرى إلى هذا التسجيل. يمكن تثبيت تسجيل واحد عبر عدة مساحات عمل على الخادم نفسه.
انقر View installed app لعرض التطبيق المثبّت. تعرض علامة التبويب About الإصدار الحالي وخيارات الإدارة:
انتقل إلى علامة التبويب Content لمشاهدة كل ما يقدمه تطبيقك — الكائنات، والحقول، ودوال المنطق، والوكلاء:
أنت جاهز تمامًا! حرّر أي ملف في src/ وسيتم التقاط التغييرات تلقائيًا.
ما الذي يمكنك بناؤه
تتكون التطبيقات من كيانات — يُعرَّف كل منها كملف TypeScript يحتوي على export default واحد:
| كيان | ماذا يفعل |
|---|
| الكائنات والحقول | عرّف نماذج بيانات مخصّصة (مثل Post Card، Invoice) مع حقول محددة النوع |
| الوظائف المنطقية | دوال TypeScript على جانب الخادم يتم تشغيلها عبر مسارات HTTP، وجداول cron، أو أحداث قاعدة البيانات |
| المكوّنات الأمامية | مكوّنات React تُعرَض داخل واجهة مستخدم Twenty (اللوحة الجانبية، الودجات، قائمة الأوامر) |
| المهارات والوكلاء | قدرات الذكاء الاصطناعي — تعليمات قابلة لإعادة الاستخدام ومساعدون مستقلون ذاتيًا |
| طرق العرض والتنقّل | طرق عرض القوائم مُعدّة مسبقًا وعناصر قائمة الشريط الجانبي لكائناتك |
| تخطيطات الصفحات | صفحات تفاصيل سجلات مخصصة تتضمن علامات تبويب وعناصر واجهة |
هيكل المشروع
تولّد أداة إنشاء الهيكل بنية الملفات التالية:
my-twenty-app/
package.json
yarn.lock
.gitignore
.nvmrc
.yarnrc.yml
.oxlintrc.json
tsconfig.json
tsconfig.spec.json # TypeScript config for tests
vitest.config.ts # Vitest test runner configuration
LLMS.md
README.md
.github/
└── workflows/
└── ci.yml # GitHub Actions CI workflow
public/ # Public assets (images, fonts, etc.)
src/
├── application-config.ts # Required — main application configuration
├── default-role.ts # Default role for logic functions
├── constants/
│ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
└── __tests__/
├── setup-test.ts # Test setup (server health check, config)
└── app-install.integration-test.ts # Integration test
البدء من مثال
للبدء من مثال أكثر اكتمالًا يضم كائنات وحقولًا مخصّصة، ودوال المنطق، ومكوّنات الواجهة الأمامية، وغير ذلك، استخدم الخيار --example:
npx create-twenty-app@latest my-twenty-app --example postcard
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 كاعتمادات:
yarn add twenty-sdk twenty-client-sdk
twenty إلى package.json لديك:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev، وyarn twenty help، وجميع الأوامر الأخرى.
لا تثبّت twenty-sdk عالميًا. استخدمه دائمًا كاعتماد محلي للمشروع بحيث يتمكن كل مشروع من تثبيت إصداره الخاص.
استكشاف الأخطاء وإصلاحها
إذا واجهت مشاكل:
- تأكّد من أن Docker قيد التشغيل قبل تشغيل أداة إنشاء الهيكل مع مثيل محلي.
- تأكّد من أنك تستخدم Node.js 24+ (
node -v للتحقق).
- تأكّد من تمكين Corepack (
corepack enable) حتى يتوفر Yarn 4.
- جرّب حذف
node_modules وتشغيل yarn install مرة أخرى إذا بدت الاعتمادات معطّلة.
ما زلت عالقًا؟ اطلب المساعدة على خادم Twenty على Discord.
