250 lines
13 KiB
Plaintext
250 lines
13 KiB
Plaintext
---
|
|
title: النشر
|
|
description: وزّع تطبيق Twenty الخاص بك على سوق Twenty أو انشره داخليًا.
|
|
---
|
|
|
|
<Warning>
|
|
التطبيقات حاليًا في مرحلة الاختبار الألفا. الميزة تعمل لكنها لا تزال قيد التطور.
|
|
</Warning>
|
|
|
|
## نظرة عامة
|
|
|
|
بمجرد أن يكون تطبيقك [مبنيًا ومختبرًا محليًا](/l/ar/developers/extend/apps/building)، لديك مساران لتوزيعه:
|
|
|
|
* **النشر على npm** — أدرج تطبيقك في سوق Twenty ليتسنى لأي مساحة عمل اكتشافه وتثبيته.
|
|
* **نشر أرشيف tar** — ارفع تطبيقك مباشرةً إلى خادم Twenty محدد للاستخدام الداخلي أو الخاص.
|
|
|
|
كلا المسارين يبدآن من نفس خطوة **build**.
|
|
|
|
## بناء تطبيقك
|
|
|
|
يقوم الأمر `build` بتجميع مصادر TypeScript الخاصة بك، وتحويل دوال المنطق ومكوّنات الواجهة الأمامية، وإنشاء ملف `manifest.json` يصف محتويات تطبيقك:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty build
|
|
```
|
|
|
|
يتم حفظ المخرجات في `.twenty/output/`. يحتوي هذا الدليل على كل ما يلزم للتوزيع: الكود المُجمَّع، والأصول، وملف manifest، ونسخة من `package.json` الخاص بك.
|
|
|
|
لإنشاء حزمة tarball بصيغة `.tgz` أيضًا (تُستخدم داخليًا بواسطة أمر النشر، أو للتوزيع اليدوي):
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty build --tarball
|
|
```
|
|
|
|
## النشر على npm
|
|
|
|
يُتيح النشر على npm إمكانية العثور على تطبيقك في سوق Twenty. يمكن لأي مساحة عمل في Twenty استعراض تطبيقات السوق وتثبيتها وترقيتها مباشرةً من واجهة المستخدم.
|
|
|
|
### المتطلبات
|
|
|
|
* حساب على [npm](https://www.npmjs.com)
|
|
* الكلمة المفتاحية `twenty-app` **يجب** أن تُدرج في مصفوفة `keywords` في `package.json` الخاص بك
|
|
|
|
### إضافة الكلمة المفتاحية المطلوبة
|
|
|
|
يعثر سوق Twenty على التطبيقات من خلال البحث في سجل npm عن الحزم التي تحتوي على الكلمة المفتاحية `twenty-app`. أضِفها إلى `package.json` الخاص بك:
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"name": "twenty-app-postcard-sender",
|
|
"version": "1.0.0",
|
|
"keywords": ["twenty-app"],
|
|
...
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
يبحث السوق عن `keywords:twenty-app` في سجل npm. من دون هذه الكلمة المفتاحية، لن تظهر حزمتك في السوق حتى وإن كانت تحمل بادئة الاسم `twenty-app-`.
|
|
</Note>
|
|
|
|
### الخطوات
|
|
|
|
1. **بناء تطبيقك:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty build
|
|
```
|
|
|
|
2. **النشر على npm:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty publish
|
|
```
|
|
|
|
هذا يُشغِّل `npm publish` من دليل `.twenty/output/`.
|
|
|
|
للنشر تحت dist-tag معيّن (مثلًا: `beta` أو `next`):
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty publish --tag beta
|
|
```
|
|
|
|
### كيف تعمل آلية الاكتشاف في السوق
|
|
|
|
يقوم خادم Twenty بمزامنة كتالوج السوق من سجل npm **كل ساعة**:
|
|
|
|
1. يبحث عن جميع حزم npm التي تحتوي على الكلمة المفتاحية `keywords:twenty-app`
|
|
2. ولكل حزمة، يجلب ملف `manifest.json` من شبكة CDN الخاصة بـ npm
|
|
3. يتم استخراج بيانات التعريف الخاصة بالتطبيق (الاسم، الوصف، المؤلف، الشعار، لقطات الشاشة، الفئة) من ملف manifest وعرضها في السوق
|
|
|
|
بعد النشر، قد يستغرق ظهور تطبيقك في السوق ما يصل إلى ساعة واحدة. لتشغيل المزامنة فورًا بدلًا من انتظار التشغيل التالي كل ساعة:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty catalog-sync
|
|
```
|
|
|
|
لاستهداف remote معيّن:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty catalog-sync -r production
|
|
```
|
|
|
|
تأتي بيانات التعريف المعروضة في السوق من استدعائك لـ `defineApplication()` في الشيفرة المصدرية لتطبيقك — حقول مثل `displayName` و`description` و`author` و`category` و`logoUrl` و`screenshots` و`aboutDescription` و`websiteUrl` و`termsUrl`.
|
|
|
|
### النشر عبر CI
|
|
|
|
يتضمن المشروع المُولَّد سير عمل GitHub Actions يقوم بالنشر عند كل إصدار:
|
|
|
|
```yaml filename=".github/workflows/publish.yml"
|
|
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
|
|
env:
|
|
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
```
|
|
|
|
بالنسبة لأنظمة CI الأخرى (GitLab CI، وCircleCI، إلخ)، تنطبق الأوامر الثلاثة نفسها: `yarn install`، ثم `yarn twenty build`، ثم `npm publish` من `.twenty/output`.
|
|
|
|
<Tip>
|
|
**npm provenance** اختياري ولكنه موصى به. يضيف النشر باستخدام `--provenance` شارة ثقة إلى إدراجك على npm، مما يتيح للمستخدمين التحقق من أن الحزمة تم بناؤها من التزام محدد ضمن خط أنابيب CI عام. راجع [وثائق npm provenance](https://docs.npmjs.com/generating-provenance-statements) للحصول على تعليمات الإعداد.
|
|
</Tip>
|
|
|
|
## النشر إلى خادم (tarball)
|
|
|
|
بالنسبة للتطبيقات التي لا تريد إتاحتها للعامة — مثل الأدوات المملوكة، أو عمليات التكامل الخاصة بالمؤسسات فقط، أو الإصدارات التجريبية — يمكنك نشر tarball مباشرةً إلى خادم Twenty.
|
|
|
|
### المتطلبات الأساسية
|
|
|
|
قبل النشر، تحتاج إلى remote مُعدّ يشير إلى خادم الهدف. تُخزّن remotes عنوان URL للخادم وبيانات اعتماد المصادقة محليًا في `~/.twenty/config.json`.
|
|
|
|
أضِف remote:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty remote add --url https://your-twenty-server.com --as production
|
|
```
|
|
|
|
لخادم تطوير محلي:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty remote add --local --as local
|
|
```
|
|
|
|
يمكنك أيضًا إجراء المصادقة باستخدام مفتاح API للبيئات غير التفاعلية:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
|
|
```
|
|
|
|
إدارة remotes الخاصة بك:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty remote list # List all configured remotes
|
|
yarn twenty remote switch prod # Set the default remote
|
|
yarn twenty remote status # Show active remote and auth status
|
|
yarn twenty remote remove old # Remove a remote
|
|
```
|
|
|
|
### النشر
|
|
|
|
بناء تطبيقك ورفعه إلى الخادم في خطوة واحدة:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty deploy
|
|
```
|
|
|
|
يُنشئ هذا التطبيق باستخدام `--tarball`، ثم يرفع ملف tarball إلى الـ remote الافتراضي عبر رفع متعدد الأجزاء لـ GraphQL.
|
|
|
|
لنشره إلى remote معيّن:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty deploy -r production
|
|
```
|
|
|
|
### مشاركة تطبيق منشور
|
|
|
|
تطبيقات tarball لا تُدرَج في السوق العامة، لذا لن تكتشفها مساحات العمل الأخرى على الخادم نفسه عبر الاستعراض. لمشاركة تطبيق منشور:
|
|
|
|
1. اذهب إلى **الإعدادات > التطبيقات > التسجيلات** وافتح تطبيقك
|
|
2. في علامة التبويب **التوزيع**، انقر **نسخ رابط المشاركة**
|
|
3. شارك هذا الرابط مع المستخدمين في مساحات عمل أخرى — سيأخذهم مباشرةً إلى صفحة تثبيت التطبيق
|
|
|
|
يستخدم رابط المشاركة عنوان URL الأساسي للخادم (من دون أي نطاق فرعي لمساحة عمل)، لذا يعمل مع أي مساحة عمل على الخادم.
|
|
|
|
### إدارة الإصدارات
|
|
|
|
لطرح تحديث:
|
|
|
|
1. ارفع قيمة الحقل `version` في ملف `package.json`
|
|
2. شغّل `yarn twenty deploy` (أو `yarn twenty deploy -r production`)
|
|
3. سترى مساحات العمل التي ثبّتت التطبيق الترقية متاحة في إعداداتها
|
|
|
|
## تثبيت التطبيقات
|
|
|
|
بعد نشر التطبيق (npm) أو نشره إلى الخادم (tarball)، تقوم مساحات العمل بتثبيته عبر واجهة المستخدم:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty install
|
|
```
|
|
|
|
أو من صفحة **الإعدادات > التطبيقات** في واجهة Twenty، حيث يمكن استعراض التطبيقات من السوق ومن النشر عبر tarball وتثبيتها.
|
|
|
|
## فئات توزيع التطبيقات
|
|
|
|
تُنظِّم Twenty التطبيقات في ثلاث فئات استنادًا إلى طريقة توزيعها:
|
|
|
|
| الفئة | كيف يعمل | مرئي في سوق Twenty؟ |
|
|
| ------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------- |
|
|
| **التطوير** | تطبيقات وضع التطوير المحلي التي تعمل عبر `yarn twenty dev`. تُستخدم للبناء والاختبار. | لا |
|
|
| **منشور (npm)** | تطبيقات منشورة على npm تحتوي على الكلمة المفتاحية `twenty-app`. مدرجة في سوق Twenty لتتمكن أي مساحة عمل من تثبيتها. | نعم |
|
|
| **داخلي (tarball)** | تطبيقات منشورة عبر tarball إلى خادم محدد. متاحة فقط لمساحات العمل على ذلك الخادم عبر رابط مشاركة. | لا |
|
|
|
|
<Tip>
|
|
ابدأ في وضع **التطوير** أثناء بناء تطبيقك. عندما يصبح جاهزًا، اختر **منشور** (npm) للتوزيع الواسع أو **داخلي** (tarball) للنشر الخاص.
|
|
</Tip>
|
|
|
|
## مرجع CLI
|
|
|
|
| أمر | الوصف | الأعلام الرئيسية |
|
|
| --------------------------- | ------------------------------------ | ----------------------------------------------------- |
|
|
| `yarn twenty build` | تجميع التطبيق وإنشاء manifest | `--tarball` — يقوم أيضًا بإنشاء حزمة `.tgz` |
|
|
| `yarn twenty publish` | بناء التطبيق ونشره إلى npm | `--tag <tag>` — وسم توزيع npm (مثلًا: `beta`، `next`) |
|
|
| `yarn twenty deploy` | بناء ورفع tarball إلى خادم | `-r, --remote <name>` — الـ remote المستهدف |
|
|
| `yarn twenty catalog-sync` | تشغيل مزامنة كتالوج السوق على الخادم | `-r, --remote <name>` — الـ remote المستهدف |
|
|
| `yarn twenty install` | تثبيت تطبيق منشور على مساحة عمل | `-r, --remote <name>` — الـ remote المستهدف |
|
|
| `yarn twenty dev` | مراقبة ومزامنة التغييرات المحلية | يستخدم الـ remote الافتراضي |
|
|
| `yarn twenty remote add` | إضافة اتصال بخادم | `--url`, `--token`, `--as`, `--local`, `--port` |
|
|
| `yarn twenty remote list` | عرض الـ remotes المُكوَّنة | — |
|
|
| `yarn twenty remote switch` | تعيين الـ remote الافتراضي | — |
|
|
| `yarn twenty remote status` | عرض حالة الاتصال | — |
|
|
| `yarn twenty remote remove` | إزالة remote | — |
|