الانتقال إلى المحتوى الرئيسي
التطبيقات حاليًا في مرحلة الألفا. الميزة تعمل لكنها لا تزال قيد التطور.

​
نظرة عامة

بمجرد أن يكون تطبيقك مبنيًا ومختبرًا محليًا، لديك مساران لتوزيعه:
  • نشر أرشيف 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 صالحة.

​
النشر على 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.