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

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.

​
نظرة عامة

بمجرد أن يكون تطبيقك مبنيًا ومختبرًا محليًا، لديك مساران لتوزيعه:
  • نشر أرشيف tar — ارفع تطبيقك مباشرةً إلى خادم Twenty محدد للاستخدام الداخلي أو الخاص.
  • النشر على npm — أدرج تطبيقك في سوق Twenty ليتسنى لأي مساحة عمل اكتشافه وتثبيته.
كلا المسارين يبدآن من نفس خطوة build.

​
بناء تطبيقك

شغّل أمر build لتجميع تطبيقك وإنشاء ملف manifest.json جاهز للتوزيع: 
yarn twenty build
يقوم هذا بتجميع مصادر TypeScript، وتحويل دوال المنطق ومكوّنات الواجهة الأمامية، وكتابة كل شيء إلى .twenty/output/. أضِف --tarball لإنتاج حزمة .tgz أيضًا للتوزيع اليدوي أو لأمر deploy.

​
النشر إلى خادم (tarball)

بالنسبة للتطبيقات التي لا تريد إتاحتها للعامة — مثل الأدوات المملوكة، أو عمليات التكامل الخاصة بالمؤسسات فقط، أو الإصدارات التجريبية — يمكنك نشر tarball مباشرةً إلى خادم Twenty.

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

قبل النشر، تحتاج إلى remote مُعدّ يشير إلى خادم الهدف. تُخزّن remotes عنوان URL للخادم وبيانات اعتماد المصادقة محليًا في ~/.twenty/config.json. أضِف remote: 
yarn twenty remote add --api-url https://your-twenty-server.com --as production

​
النشر

بناء تطبيقك ورفعه إلى الخادم في خطوة واحدة: 
yarn twenty deploy
# To deploy to a specific remote:
# yarn twenty deploy --remote production

​
مشاركة تطبيق منشور

تُعد مشاركة التطبيقات الخاصة (tarball) عبر مساحات العمل ميزة ضمن Enterprise. ستعرض علامة التبويب Distribution مطالبة بالترقية بدلًا من عناصر التحكم في المشاركة حتى تحتوي مساحة العمل لديك على مفتاح Enterprise صالح. اطلع على الإعدادات > لوحة الإدارة > Enterprise لتنشيطه.
تطبيقات tarball لا تُدرَج في السوق العامة، لذا لن تكتشفها مساحات العمل الأخرى على الخادم نفسه عبر الاستعراض. بمجرد أن تصبح مساحة العمل لديك ضمن خطة Enterprise، يمكنك مشاركة تطبيق تم نشره كما يلي:
  1. اذهب إلى الإعدادات > التطبيقات > التسجيلات وافتح تطبيقك
  2. في علامة التبويب التوزيع، انقر نسخ رابط المشاركة
  3. شارك هذا الرابط مع المستخدمين في مساحات عمل أخرى — سيأخذهم مباشرةً إلى صفحة تثبيت التطبيق
يستخدم رابط المشاركة عنوان URL الأساسي للخادم (من دون أي نطاق فرعي لمساحة عمل)، لذا يعمل مع أي مساحة عمل على الخادم.

​
إدارة الإصدارات

عند تحديث تطبيق tarball منشور مسبقًا، يشترط الخادم أن تكون قيمة version في package.json أعلى قطعًا (وفق ترتيب الإصدار الدلالي) من الإصدار المنشور حاليًا. إعادة نشر الإصدار نفسه، أو دفع إصدار أدنى، يُرفَض قبل تخزين ملف tarball — سترى خطأ VERSION_ALREADY_EXISTS من CLI. لطرح تحديث:
  1. قم بزيادة الحقل version في ملف package.json (مثلًا: 1.2.3 → 1.2.4، 1.3.0، أو 2.0.0)
  2. شغّل yarn twenty deploy (أو yarn twenty deploy --remote production)
  3. سترى مساحات العمل التي ثبّتت التطبيق الترقية متاحة في إعداداتها
علامات ما قبل الإصدار تعمل كما هو متوقع: زيادة 1.0.0-rc.1 → 1.0.0-rc.2 مسموح بها، ويُعترَف بالإصدار النهائي مثل 1.0.0 على أنه أعلى من 1.0.0-rc.5. يجب أن يكون الإصدار في package.json بنفسه سلسلة semver صالحة.

​
CI/CD المؤتمتة (مهام سير عمل مُولَّدة بالقوالب)

التطبيقات المُولَّدة باستخدام create-twenty-app تأتي افتراضيًا مع مهمَّتي سير عمل من GitHub Actions ضمن .github/workflows/. هي جاهزة للتشغيل بمجرد دفع المستودع إلى GitHub — لا حاجة لأي إعداد إضافي لـ CI، وCD يتطلّب سرًّا واحدًا فقط.

​
CI — ci.yml

يشغّل اختبارات التكامل عند كل دفع إلى main وعند كل طلب سحب. ماذا يفعل:
  1. يجلب مصدر تطبيقك.
  2. ينشئ مثيلاً اختبارياً معزولاً من Twenty باستخدام الإجراء المركّب twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main (المكافئ في CI للأمر yarn twenty server start --test).
  3. يُفعِّل Corepack، ويُعدّ Node.js من ملف .nvmrc لديك، ويثبّت التبعيات بواسطة yarn install --immutable.
  4. يشغّل yarn test، ويمرّر TWENTY_API_URL وTWENTY_API_KEY من المثيل الذي تم إنشاؤه بحيث تتمكّن اختباراتك من التواصل مع خادم حقيقي.
خيارات التكوين:
  • TWENTY_VERSION (متغيّر بيئة، القيمة الافتراضية latest) — ثبّت نسخة خادم Twenty المستخدمة في CI عبر تعديل هذا في ci.yml.
  • يتم تجميع التشغيل المتزامن حسب github.ref ويلغي التشغيلات قيد التقدّم عند أي دفع جديد.
لا تتطلّب أي أسرار — مثيل الاختبار مؤقّت ويستمر فقط طوال مدّة المهمّة.

​
CD — cd.yml

ينشر تطبيقك إلى خادم Twenty مُهيّأ عند كل دفع إلى main، وبشكل اختياري من طلب سحب عند تطبيق الوسم deploy. ماذا يفعل:
  1. يجلب رأس طلب السحب (للطلبات الموسومة) أو الالتزام المدفوع.
  2. يشغّل twentyhq/twenty/.github/actions/deploy-twenty-app@main — وهو المكافئ في CI للأمر yarn twenty deploy.
  3. يشغّل twentyhq/twenty/.github/actions/install-twenty-app@main بحيث تُثبَّت النسخة المُنشَرة حديثًا في مساحة العمل المستهدفة.
التكوين المطلوب:
الإعدادحيثالغرض
TWENTY_DEPLOY_URLenv في cd.yml (القيمة الافتراضية http://localhost:3000)خادم Twenty الذي سيتم النشر إليه. غيّر هذا إلى عنوان URL لخادمك الحقيقي قبل أول استخدام.
TWENTY_DEPLOY_API_KEYفي مستودع GitHub Settings → Secrets and variables → Actionsمفتاح API يمتلك إذن النشر على الخادم المستهدف.
القيمة الافتراضية لـ TWENTY_DEPLOY_URL وهي http://localhost:3000 مجرد عنصر نائب — لن تصل إلى أي شيء من مُشغِّل مستضاف لدى GitHub. حدّثها إلى عنوان URL العام لخادمك (أو استخدم مُشغِّلًا مستضافًا ذاتيًا مع وصول شبكي) قبل تمكين CD.
تشغيل نشر معاينة من طلب سحب: أضِف الوسم deploy إلى طلب سحب. الشرط if: في cd.yml سيشغّل المهمّة لذلك الطلب مستخدمًا التزام رأس الطلب، مما يتيح لك التحقّق من التغيير على الخادم المستهدف قبل الدمج.

​
تثبيت الإجراءات القابلة لإعادة الاستخدام

يشير كلا سيرَي العمل إلى إجراءات قابلة لإعادة الاستخدام عند @main، لذا تُلتقط تحديثات الإجراءات في مستودع twentyhq/twenty تلقائيًا. إذا كنت تريد بناءات حتمية، فاستبدِل @main بقيمة SHA لالتزام أو بوسم إصدار في كل سطر uses:.

​
النشر على npm

يُتيح النشر على npm إمكانية العثور على تطبيقك في سوق Twenty. يمكن لأي مساحة عمل في Twenty استعراض تطبيقات السوق وتثبيتها وترقيتها مباشرةً من واجهة المستخدم.

​
المتطلبات

  • حساب على npm
  • الكلمة المفتاحية twenty-app في مصفوفة keywords في package.json (أضفها يدويًا — فهي غير مضمنة افتراضيًا في قالب create-twenty-app)
{
  "name": "twenty-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["twenty-app"]
}

​
بيانات التعريف لسوق التطبيقات

يدعم إعداد defineApplication() حقولًا اختيارية تتحكم في كيفية ظهور تطبيقك في السوق. استخدم logoUrl وscreenshots للإشارة إلى الصور من مجلد public/:
src/application-config.ts
export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});
اطّلع على أكورديون defineApplication في صفحة بناء التطبيقات للاطلاع على القائمة الكاملة لحقول السوق (author وcategory وaboutDescription وwebsiteUrl وtermsUrl وغيرها).

​
النشر

yarn twenty publish
للنشر تحت dist-tag معيّن (مثلًا: beta أو next): 
yarn twenty publish --tag beta

​
كيف تعمل آلية الاكتشاف في السوق

يقوم خادم Twenty بمزامنة كتالوج السوق من سجل npm كل ساعة. يمكنك تشغيل المزامنة فورًا بدلًا من الانتظار: 
yarn twenty catalog-sync
# To target a specific remote:
# yarn twenty catalog-sync --remote production
تأتي بيانات التعريف المعروضة في السوق من إعداد defineApplication() — حقول مثل displayName وdescription وauthor وcategory وlogoUrl وscreenshots وaboutDescription وwebsiteUrl وtermsUrl.
إذا لم يحدد تطبيقك aboutDescription في defineApplication()، فسيستخدم السوق تلقائيًا ملف README.md الخاص بحزمتك من npm كمحتوى لصفحة حول. هذا يعني أنه يمكنك الاحتفاظ بملف README واحد لكل من npm وسوق Twenty. إذا كنت تريد وصفًا مختلفًا في السوق، فقم بتعيين aboutDescription بشكل صريح.

​
النشر عبر CI

استخدم سير عمل GitHub Actions هذا للنشر تلقائيًا مع كل إصدار (يستخدم OIDC): 
name: Publish
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          registry-url: https://registry.npmjs.org
      - run: yarn install --immutable
      - run: npx twenty build
      - run: npm publish --provenance --access public
        working-directory: .twenty/output
بالنسبة لأنظمة CI الأخرى (GitLab CI، وCircleCI، إلخ)، تنطبق الأوامر الثلاثة نفسها: yarn install، ثم yarn twenty build، ثم npm publish من .twenty/output.
npm provenance اختياري ولكنه موصى به. يضيف النشر باستخدام --provenance شارة ثقة إلى إدراجك على npm، مما يتيح للمستخدمين التحقق من أن الحزمة تم بناؤها من التزام محدد ضمن خط أنابيب CI عام. راجع وثائق npm provenance للحصول على تعليمات الإعداد.

​
تثبيت التطبيقات

بعد نشر التطبيق (npm) أو نشره (tarball)، يمكن لمساحات العمل تثبيته عبر واجهة المستخدم. اذهب إلى صفحة الإعدادات > التطبيقات في Twenty، حيث يمكن استعراض تطبيقات السوق والتطبيقات المنشورة عبر tarball وتثبيتها. يمكنك أيضًا تثبيت التطبيقات من سطر الأوامر: 
yarn twenty install
يفرض الخادم اعتماد إصدارات semver عند التثبيت، بما يعكس القواعد المطبّقة عند النشر:
  • تثبيت الإصدار نفسه المثبّت بالفعل في مساحة عملك يُرفَض بخطأ APP_ALREADY_INSTALLED.
  • تثبيت إصدار أدنى من الإصدار المثبّت حاليًا يُرفَض بخطأ CANNOT_DOWNGRADE_APPLICATION.
لتثبيت إصدار أحدث، انشره (deploy) أو انشره إلى السجل (publish) أولًا، ثم أعد تشغيل yarn twenty install.