github-actions[bot]
6af7e32c54
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
250 lines
11 KiB
Plaintext
250 lines
11 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/`. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
|
|
|
|
To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty build --tarball
|
|
```
|
|
|
|
## النشر على npm
|
|
|
|
يُتيح النشر على npm إمكانية العثور على تطبيقك في سوق Twenty. يمكن لأي مساحة عمل في Twenty استعراض تطبيقات السوق وتثبيتها وترقيتها مباشرةً من واجهة المستخدم.
|
|
|
|
### المتطلبات
|
|
|
|
* حساب على [npm](https://www.npmjs.com)
|
|
* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
|
|
|
|
### Adding the required keyword
|
|
|
|
The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"name": "twenty-app-postcard-sender",
|
|
"version": "1.0.0",
|
|
"keywords": ["twenty-app"],
|
|
...
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
|
|
</Note>
|
|
|
|
### الخطوات
|
|
|
|
1. **Build your app:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty build
|
|
```
|
|
|
|
2. **Publish to npm:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty publish
|
|
```
|
|
|
|
This runs `npm publish` from the `.twenty/output/` directory.
|
|
|
|
To publish under a specific dist-tag (e.g., `beta` or `next`):
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty publish --tag beta
|
|
```
|
|
|
|
### How marketplace discovery works
|
|
|
|
The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
|
|
|
|
1. It searches for all npm packages with the `keywords:twenty-app` keyword
|
|
2. For each package, it fetches the `manifest.json` from the npm CDN
|
|
3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
|
|
|
|
After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty catalog-sync
|
|
```
|
|
|
|
To target a specific remote:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty catalog-sync -r production
|
|
```
|
|
|
|
The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `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 }}
|
|
```
|
|
|
|
For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
|
|
|
|
<Tip>
|
|
**npm provenance** اختياري ولكنه موصى به. يضيف النشر باستخدام `--provenance` شارة ثقة إلى إدراجك على npm، مما يتيح للمستخدمين التحقق من أن الحزمة تم بناؤها من التزام محدد ضمن خط أنابيب CI عام. راجع [وثائق npm provenance](https://docs.npmjs.com/generating-provenance-statements) للحصول على تعليمات الإعداد.
|
|
</Tip>
|
|
|
|
## Deploying to a server (tarball)
|
|
|
|
For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
|
|
|
|
### المتطلبات الأساسية
|
|
|
|
Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
|
|
|
|
Add a remote:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty remote add --url https://your-twenty-server.com --as production
|
|
```
|
|
|
|
For a local development server:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty remote add --local --as local
|
|
```
|
|
|
|
You can also authenticate with an API key for non-interactive environments:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
|
|
```
|
|
|
|
Manage your 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
|
|
```
|
|
|
|
### Deploying
|
|
|
|
Build and upload your app to the server in one step:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty deploy
|
|
```
|
|
|
|
This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
|
|
|
|
To deploy to a specific remote:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty deploy -r production
|
|
```
|
|
|
|
### Sharing a deployed app
|
|
|
|
Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
|
|
|
|
1. Go to **Settings > Applications > Registrations** and open your app
|
|
2. In the **Distribution** tab, click **Copy share link**
|
|
3. Share this link with users on other workspaces — it takes them directly to the app's install page
|
|
|
|
The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
|
|
|
|
### إدارة الإصدارات
|
|
|
|
لطرح تحديث:
|
|
|
|
1. ارفع قيمة الحقل `version` في ملف `package.json`
|
|
2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
|
|
3. Workspaces that have the app installed will see the upgrade available in their settings
|
|
|
|
## Installing apps
|
|
|
|
Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty install
|
|
```
|
|
|
|
Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
|
|
|
|
## App distribution categories
|
|
|
|
تُنظِّم Twenty التطبيقات في ثلاث فئات استنادًا إلى طريقة توزيعها:
|
|
|
|
| الفئة | كيف يعمل | مرئي في سوق Twenty؟ |
|
|
| ---------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
|
|
| **التطوير** | تطبيقات وضع التطوير المحلي التي تعمل عبر `yarn twenty dev`. تُستخدم للبناء والاختبار. | لا |
|
|
| **Published (npm)** | Apps published to npm with the `twenty-app` keyword. مدرجة في سوق Twenty لتتمكن أي مساحة عمل من تثبيتها. | نعم |
|
|
| **Internal (tarball)** | تطبيقات منشورة عبر tarball إلى خادم محدد. Available only to workspaces on that server via a share link. | لا |
|
|
|
|
<Tip>
|
|
ابدأ في وضع **التطوير** أثناء بناء تطبيقك. عندما يصبح جاهزًا، اختر **منشور** (npm) للتوزيع الواسع أو **داخلي** (tarball) للنشر الخاص.
|
|
</Tip>
|
|
|
|
## CLI reference
|
|
|
|
| أمر | الوصف | Key flags |
|
|
| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
|
|
| `yarn twenty build` | Compile app and generate manifest | `--tarball` — also create a `.tgz` package |
|
|
| `yarn twenty publish` | Build and publish to npm | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
|
|
| `yarn twenty deploy` | Build and upload tarball to a server | `-r, --remote <name>` — target remote |
|
|
| `yarn twenty catalog-sync` | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote |
|
|
| `yarn twenty install` | Install a deployed app on a workspace | `-r, --remote <name>` — target remote |
|
|
| `yarn twenty dev` | Watch and sync local changes | Uses default remote |
|
|
| `yarn twenty remote add` | Add a server connection | `--url`, `--token`, `--as`, `--local`, `--port` |
|
|
| `yarn twenty remote list` | List configured remotes | — |
|
|
| `yarn twenty remote switch` | Set default remote | — |
|
|
| `yarn twenty remote status` | Show connection status | — |
|
|
| `yarn twenty remote remove` | Remove a remote | — |
|