i18n - docs translations (#19228)
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
6eb4c4ca4b
commit
5de5ed2cb4
@@ -4,142 +4,142 @@ description: أنشئ أول تطبيق Twenty خلال دقائق.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha. The feature works but is still evolving.
|
||||
التطبيقات حاليًا في مرحلة الألفا. الميزة تعمل لكنها لا تزال قيد التطور.
|
||||
</Warning>
|
||||
|
||||
تتيح لك التطبيقات توسيع Twenty باستخدام كائنات وحقول ووظائف منطقية ومهارات ذكاء اصطناعي ومكونات واجهة مستخدم مخصصة — جميعها تُدار ككود.
|
||||
|
||||
## المتطلبات الأساسية
|
||||
|
||||
Before you begin, make sure the following is installed on your machine:
|
||||
قبل أن تبدأ، تأكّد من تثبيت ما يلي على جهازك:
|
||||
|
||||
* **Node.js 24+** — [Download here](https://nodejs.org/)
|
||||
* **Yarn 4** — Comes with Node.js via Corepack. Enable it by running `corepack enable`
|
||||
* **Docker** — [Download here](https://www.docker.com/products/docker-desktop/). Required to run a local Twenty instance. Not needed if you already have a Twenty server running.
|
||||
* **Node.js 24+** — [نزّل من هنا](https://nodejs.org/)
|
||||
* **Yarn 4** — يأتي مع Node.js عبر Corepack. قم بتمكينه عبر تشغيل `corepack enable`
|
||||
* **Docker** — [نزّل من هنا](https://www.docker.com/products/docker-desktop/). مطلوب لتشغيل مثيل محلي من Twenty. غير مطلوب إذا كان لديك خادم Twenty قيد التشغيل بالفعل.
|
||||
|
||||
## Step 1: Scaffold your app
|
||||
## الخطوة 1: إنشاء هيكل تطبيقك
|
||||
|
||||
Open a terminal and run:
|
||||
افتح الطرفية وشغّل:
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
```
|
||||
|
||||
You will be prompted to enter a name and a description for your app. Press **Enter** to accept the defaults.
|
||||
سيُطلب منك إدخال اسم ووصف لتطبيقك. اضغط **Enter** لقبول الإعدادات الافتراضية.
|
||||
|
||||
This creates a new folder called `my-twenty-app` with everything you need.
|
||||
سيؤدي ذلك إلى إنشاء مجلد جديد باسم `my-twenty-app` يحتوي على كل ما تحتاجه.
|
||||
|
||||
<Note>
|
||||
The scaffolder supports these flags:
|
||||
أداة إنشاء الهيكل تدعم الأعلام التالية:
|
||||
|
||||
* `--minimal` — scaffold only the essential files, no examples (default)
|
||||
* `--exhaustive` — scaffold all example entities
|
||||
* `--name <name>` — set the app name (skips the prompt)
|
||||
* `--display-name <displayName>` — set the display name (skips the prompt)
|
||||
* `--description <description>` — set the description (skips the prompt)
|
||||
* `--skip-local-instance` — skip the local server setup prompt
|
||||
* `--minimal` — إنشاء الهيكل للملفات الأساسية فقط، بدون أمثلة (افتراضي)
|
||||
* `--exhaustive` — إنشاء الهيكل لجميع كيانات الأمثلة
|
||||
* `--name <name>` — تعيين اسم التطبيق (يتخطى المطالبة)
|
||||
* `--display-name <displayName>` — تعيين اسم العرض (يتخطى المطالبة)
|
||||
* `--description <description>` — تعيين الوصف (يتخطى المطالبة)
|
||||
* `--skip-local-instance` — تخطي مطالبة إعداد الخادم المحلي
|
||||
</Note>
|
||||
|
||||
## Step 2: Set up a local Twenty instance
|
||||
## الخطوة 2: إعداد مثيل محلي من Twenty
|
||||
|
||||
The scaffolder will ask:
|
||||
ستسأل أداة إنشاء الهيكل:
|
||||
|
||||
> **Would you like to set up a local Twenty instance?**
|
||||
> **هل ترغب في إعداد مثيل محلي من Twenty؟**
|
||||
|
||||
* **Type `yes`** (recommended) — This pulls the `twenty-app-dev` Docker image and starts a local Twenty server on port `2020`. Make sure Docker is running before you continue.
|
||||
* **Type `no`** — Choose this if you already have a Twenty server running locally.
|
||||
* **اكتب `yes`** (موصى به) — سيؤدي ذلك إلى سحب صورة Docker `twenty-app-dev` وبدء تشغيل خادم Twenty محلي على المنفذ `2020`. تأكّد من أن Docker قيد التشغيل قبل المتابعة.
|
||||
* **اكتب `no`** — اختر هذا إذا كان لديك خادم Twenty يعمل محليًا بالفعل.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Should start local instance?" />
|
||||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="هل يجب بدء المثيل المحلي؟" />
|
||||
</div>
|
||||
|
||||
## Step 3: Sign in to your workspace
|
||||
## الخطوة 3: سجّل الدخول إلى مساحة العمل الخاصة بك
|
||||
|
||||
Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
|
||||
بعد ذلك، ستُفتح نافذة متصفح تعرض صفحة تسجيل الدخول الخاصة بـ Twenty. سجّل الدخول باستخدام حساب العرض التوضيحي المُجهَّز مسبقًا:
|
||||
|
||||
* **Email:** `tim@apple.dev`
|
||||
* **Password:** `tim@apple.dev`
|
||||
* **البريد الإلكتروني:** `tim@apple.dev`
|
||||
* **كلمة المرور:** `tim@apple.dev`
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />
|
||||
<img src="/images/docs/developers/extends/apps/login.png" alt="شاشة تسجيل الدخول إلى Twenty" />
|
||||
</div>
|
||||
|
||||
## Step 4: Authorize the app
|
||||
## الخطوة 4: تفويض التطبيق
|
||||
|
||||
After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
|
||||
بعد تسجيل الدخول، ستظهر لك شاشة تفويض. يتيح هذا لتطبيقك التفاعل مع مساحة العمل الخاصة بك.
|
||||
|
||||
Click **Authorize** to continue.
|
||||
انقر **Authorize** للمتابعة.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI authorization screen" />
|
||||
<img src="/images/docs/developers/extends/apps/authorize.png" alt="شاشة تفويض واجهة الأوامر (CLI) الخاصة بـ Twenty" />
|
||||
</div>
|
||||
|
||||
Once authorized, your terminal will confirm that everything is set up.
|
||||
بمجرد منح التفويض، ستؤكّد الطرفية أن كل شيء قد تم إعداده.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />
|
||||
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="تم إنشاء هيكل التطبيق بنجاح" />
|
||||
</div>
|
||||
|
||||
## Step 5: Start developing
|
||||
## الخطوة 5: ابدأ التطوير
|
||||
|
||||
Go into your new app folder and start the development server:
|
||||
انتقل إلى مجلد تطبيقك الجديد وابدأ خادم التطوير:
|
||||
|
||||
```bash filename="Terminal"
|
||||
cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
This watches your source files, rebuilds on every change, and syncs your app to the local Twenty server automatically. You should see a live status panel in your terminal.
|
||||
يقوم هذا بمراقبة ملفات المصدر لديك، وإعادة البناء عند كل تغيير، ومزامنة تطبيقك تلقائيًا مع خادم Twenty المحلي. يفترض أن ترى لوحة حالة مباشرة في الطرفية.
|
||||
|
||||
For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
|
||||
للحصول على مخرجات أكثر تفصيلاً (سجلات البناء، طلبات المزامنة، تتبعات الأخطاء)، استخدم العلم `--verbose`:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev --verbose
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Dev mode is only available on Twenty instances running in development (`NODE_ENV=development`). Production instances reject dev sync requests. Use `yarn twenty deploy` to deploy to production servers — see [Publishing Apps](/l/ar/developers/extend/apps/publishing) for details.
|
||||
وضع التطوير متاح فقط على مثيلات Twenty التي تعمل في وضع التطوير (`NODE_ENV=development`). المثيلات الإنتاجية ترفض طلبات مزامنة وضع التطوير. استخدم `yarn twenty deploy` للنشر إلى خوادم الإنتاج — اطّلع على [نشر التطبيقات](/l/ar/developers/extend/apps/publishing) للتفاصيل.
|
||||
</Warning>
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Dev mode terminal output" />
|
||||
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="مخرجات الطرفية في وضع التطوير" />
|
||||
</div>
|
||||
|
||||
## Step 6: See your app in Twenty
|
||||
## الخطوة 6: اعرض تطبيقك في Twenty
|
||||
|
||||
Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) in your browser. Navigate to **Settings > Apps** and select the **Developer** tab. You should see your app listed under **Your Apps**:
|
||||
افتح [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) في متصفحك. انتقل إلى **Settings > Apps** واختر علامة التبويب **Developer**. يُفترض أن ترى تطبيقك مُدرجًا تحت **Your Apps**:
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps list showing My twenty app" />
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="قائمة "Your Apps" تعرض "My twenty app"" />
|
||||
</div>
|
||||
|
||||
Click on **My twenty app** to open its **application registration**. A registration is a server-level record that describes your app — its name, unique identifier, OAuth credentials, and source (local, npm, or tarball). It lives on the server, not inside any specific workspace. When you install an app into a workspace, Twenty creates a workspace-scoped **application** that points back to this registration. One registration can be installed across multiple workspaces on the same server.
|
||||
انقر على **My twenty app** لفتح **تسجيل التطبيق** الخاص به. التسجيل عبارة عن سجل على مستوى الخادم يصف تطبيقك — اسمه، والمعرّف الفريد، وبيانات اعتماد OAuth، والمصدر (محلي، npm، أو tarball). يُخزَّن على الخادم، وليس داخل أي مساحة عمل محددة. عند تثبيت تطبيق في مساحة عمل، ينشئ Twenty **تطبيقًا** بنطاق مساحة العمل يُشير مرة أخرى إلى هذا التسجيل. يمكن تثبيت تسجيل واحد عبر عدة مساحات عمل على الخادم نفسه.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Application registration details" />
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="تفاصيل تسجيل التطبيق" />
|
||||
</div>
|
||||
|
||||
Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
|
||||
انقر **View installed app** لعرض التطبيق المثبّت. تعرض علامة التبويب **About** الإصدار الحالي وخيارات الإدارة:
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installed app — About tab" />
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="التطبيق المثبّت — علامة تبويب About" />
|
||||
</div>
|
||||
|
||||
Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
|
||||
انتقل إلى علامة التبويب **Content** لمشاهدة كل ما يقدمه تطبيقك — الكائنات، والحقول، ودوال المنطق، والوكلاء:
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Installed app — Content tab" />
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="التطبيق المثبّت — علامة تبويب Content" />
|
||||
</div>
|
||||
|
||||
You are all set! Edit any file in `src/` and the changes will be picked up automatically.
|
||||
أنت جاهز تمامًا! حرّر أي ملف في `src/` وسيتم التقاط التغييرات تلقائيًا.
|
||||
|
||||
Head over to [Building Apps](/l/ar/developers/extend/apps/building) for a detailed guide on creating objects, logic functions, front components, skills, and more.
|
||||
انتقل إلى [بناء التطبيقات](/l/ar/developers/extend/apps/building) للحصول على دليل مفصّل حول إنشاء الكائنات، ودوال المنطق، ومكونات الواجهة الأمامية، والمهارات، والمزيد.
|
||||
|
||||
---
|
||||
|
||||
## Project structure
|
||||
## هيكل المشروع
|
||||
|
||||
The scaffolder generates the following file structure (shown with `--exhaustive` mode, which includes examples for every entity type):
|
||||
تولّد أداة إنشاء الهيكل بنية الملفات التالية (مُبيّنة بوضع `--exhaustive` الذي يتضمن أمثلة لكل نوع من الكيانات):
|
||||
|
||||
```text filename="my-twenty-app/"
|
||||
my-twenty-app/
|
||||
@@ -190,30 +190,30 @@ my-twenty-app/
|
||||
└── example-agent.ts # Example AI agent definition
|
||||
```
|
||||
|
||||
By default (`--minimal`), only the core files are created: `application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts`, and `logic-functions/post-install.ts`. Use `--exhaustive` to include all the example files shown above.
|
||||
افتراضيًا (`--minimal`)، تُنشأ الملفات الأساسية فقط: `application-config.ts`، `roles/default-role.ts`، `logic-functions/pre-install.ts`، و`logic-functions/post-install.ts`. استخدم `--exhaustive` لتضمين جميع ملفات الأمثلة الموضّحة أعلاه.
|
||||
|
||||
### Key files
|
||||
### الملفات الرئيسية
|
||||
|
||||
| File / Folder | الغرض |
|
||||
| ملف / مجلد | الغرض |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `package.json` | Declares your app name, version, and dependencies. Includes a `twenty` script so you can run `yarn twenty help` to see all commands. |
|
||||
| `src/application-config.ts` | **Required.** The main configuration file for your app. |
|
||||
| `src/roles/` | Defines roles that control what your logic functions can access. |
|
||||
| `src/logic-functions/` | Server-side functions triggered by routes, cron schedules, or database events. |
|
||||
| `src/front-components/` | React components that render inside Twenty's UI. |
|
||||
| `src/objects/` | Custom object definitions to extend your data model. |
|
||||
| `src/fields/` | Custom fields added to existing objects. |
|
||||
| `src/views/` | Saved view configurations. |
|
||||
| `src/navigation-menu-items/` | Custom links in the sidebar navigation. |
|
||||
| `package.json` | يصرّح باسم تطبيقك وإصداره واعتماداته. يتضمن نصًا برمجيًا باسم `twenty` بحيث يمكنك تشغيل `yarn twenty help` للاطلاع على جميع الأوامر. |
|
||||
| `src/application-config.ts` | **مطلوب.** ملف الإعداد الرئيسي لتطبيقك. |
|
||||
| `src/roles/` | يعرِّف الأدوار التي تتحكم بما يمكن لدوال المنطق الوصول إليه. |
|
||||
| `src/logic-functions/` | دوال على جانب الخادم يتم تشغيلها عبر المسارات، وجداول cron، أو أحداث قاعدة البيانات. |
|
||||
| `src/front-components/` | مكونات React تُعرَض داخل واجهة مستخدم Twenty. |
|
||||
| `src/objects/` | تعريفات كائنات مخصّصة لتوسيع نموذج البيانات لديك. |
|
||||
| `src/fields/` | حقول مخصّصة تُضاف إلى الكائنات الموجودة. |
|
||||
| `src/views/` | تكوينات العروض المحفوظة. |
|
||||
| `src/navigation-menu-items/` | روابط مخصّصة في شريط التنقل الجانبي. |
|
||||
| `src/skills/` | مهارات توسّع قدرات وكلاء الذكاء الاصطناعي في Twenty. |
|
||||
| `src/agents/` | AI agents with custom prompts. |
|
||||
| `src/page-layouts/` | Custom page layouts for record views. |
|
||||
| `src/__tests__/` | Integration tests (setup + example test). |
|
||||
| `public/` | Static assets (images, fonts) served with your app. |
|
||||
| `src/agents/` | وكلاء ذكاء اصطناعي مع موجهات مخصّصة. |
|
||||
| `src/page-layouts/` | تخطيطات صفحات مخصّصة لعرض السجلات. |
|
||||
| `src/__tests__/` | اختبارات تكامل (إعداد + اختبار مثال). |
|
||||
| `public/` | أصول ثابتة (صور، خطوط) تُقدَّم مع تطبيقك. |
|
||||
|
||||
## Managing remotes
|
||||
## إدارة الريموتات
|
||||
|
||||
A **remote** is a Twenty server that your app connects to. During setup, the scaffolder creates one for you automatically. You can add more remotes or switch between them at any time.
|
||||
**الريموت** هو خادم Twenty يتصل به تطبيقك. أثناء الإعداد، تُنشئ أداة إنشاء الهيكل واحدًا لك تلقائيًا. يمكنك إضافة ريموتات أخرى أو التبديل بينها في أي وقت.
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Add a new remote (opens a browser for OAuth login)
|
||||
@@ -232,11 +232,11 @@ yarn twenty remote list
|
||||
yarn twenty remote switch <name>
|
||||
```
|
||||
|
||||
Your credentials are stored in `~/.twenty/config.json`.
|
||||
تُخزَّن بيانات اعتمادك في `~/.twenty/config.json`.
|
||||
|
||||
## Local development server (`yarn twenty server`)
|
||||
## خادم التطوير المحلي (`yarn twenty server`)
|
||||
|
||||
The CLI can manage a local Twenty server running in Docker. This is the same server started automatically when you scaffold an app with `create-twenty-app`, but you can also manage it manually.
|
||||
يمكن لأداة سطر الأوامر (CLI) إدارة خادم Twenty محلي يعمل داخل Docker. هذا هو الخادم نفسه الذي يبدأ تلقائيًا عند إنشاء هيكل تطبيق باستخدام `create-twenty-app`، لكن يمكنك أيضًا إدارته يدويًا.
|
||||
|
||||
### بدء الخادم
|
||||
|
||||
@@ -244,85 +244,85 @@ The CLI can manage a local Twenty server running in Docker. This is the same ser
|
||||
yarn twenty server start
|
||||
```
|
||||
|
||||
This pulls the `twentycrm/twenty-app-dev:latest` Docker image (if not already present), creates a container named `twenty-app-dev`, and starts it on port **2020**. The CLI waits until the server passes its health check before returning.
|
||||
سيؤدي ذلك إلى سحب صورة Docker `twentycrm/twenty-app-dev:latest` (إن لم تكن موجودة بالفعل)، وإنشاء حاوية باسم `twenty-app-dev`، وبدء تشغيلها على المنفذ **2020**. تنتظر أداة CLI حتى يجتاز الخادم فحص السلامة قبل الإنهاء.
|
||||
|
||||
Two Docker volumes are created to persist data between restarts:
|
||||
يتم إنشاء حجمين في Docker للاحتفاظ بالبيانات بين عمليات إعادة التشغيل:
|
||||
|
||||
* `twenty-app-dev-data` — PostgreSQL database
|
||||
* `twenty-app-dev-storage` — file storage
|
||||
* `twenty-app-dev-data` — قاعدة بيانات PostgreSQL
|
||||
* `twenty-app-dev-storage` — تخزين ملفات
|
||||
|
||||
If port 2020 is already in use, you can start on a different port:
|
||||
إذا كان المنفذ 2020 مستخدمًا بالفعل، يمكنك البدء على منفذ مختلف:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server start --port 3030
|
||||
```
|
||||
|
||||
The CLI automatically configures the container's internal `NODE_PORT` and `SERVER_URL` to match the chosen port, so logic functions, OAuth, and all other internal networking work correctly.
|
||||
تقوم أداة CLI تلقائيًا بتهيئة قيم `NODE_PORT` و`SERVER_URL` الداخلية في الحاوية لتطابق المنفذ المختار، بحيث تعمل دوال المنطق وOAuth وكل الشبكات الداخلية الأخرى بشكل صحيح.
|
||||
|
||||
Once started, the server is automatically registered as the `local` remote in your CLI config.
|
||||
بمجرد البدء، يُسجَّل الخادم تلقائيًا كـ `local` remote في إعدادات CLI لديك.
|
||||
|
||||
### Checking server status
|
||||
### التحقق من حالة الخادم
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server status
|
||||
```
|
||||
|
||||
Displays whether the server is running, its URL, and the default login credentials (`tim@apple.dev` / `tim@apple.dev`).
|
||||
يعرض ما إذا كان الخادم قيد التشغيل، وعنوان URL الخاص به، وبيانات اعتماد تسجيل الدخول الافتراضية (`tim@apple.dev` / `tim@apple.dev`).
|
||||
|
||||
### Viewing server logs
|
||||
### عرض سجلات الخادم
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server logs
|
||||
```
|
||||
|
||||
Streams the container logs. Use `--lines` to control how many recent lines to show:
|
||||
يبث سجلات الحاوية. استخدم `--lines` للتحكّم بعدد الأسطر الحديثة المراد عرضها:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server logs --lines 100
|
||||
```
|
||||
|
||||
### Stopping the server
|
||||
### إيقاف الخادم
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server stop
|
||||
```
|
||||
|
||||
Stops the container. Your data is preserved in the Docker volumes — the next `start` picks up where you left off.
|
||||
يوقف الحاوية. تُحفَظ بياناتك في أحجام Docker — وستُستأنف الحالة مع عملية `start` التالية من حيث توقفت.
|
||||
|
||||
### Resetting the server
|
||||
### إعادة تعيين الخادم
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server reset
|
||||
```
|
||||
|
||||
Removes the container **and** deletes both Docker volumes, wiping all data. The next `start` creates a fresh instance.
|
||||
يزيل الحاوية **و** يحذف كلا حجمي Docker، ممّا يمحو جميع البيانات. ستنشئ عملية `start` التالية مثيلًا جديدًا من البداية.
|
||||
|
||||
<Note>
|
||||
The server requires **Docker** to be running. If you see a "Docker not running" error, make sure Docker Desktop (or the Docker daemon) is started.
|
||||
يتطلّب الخادم أن يكون **Docker** قيد التشغيل. إذا ظهرت لك رسالة خطأ "Docker not running"، فتأكّد من تشغيل Docker Desktop (أو خادوم Docker).
|
||||
</Note>
|
||||
|
||||
### Command reference
|
||||
### مرجع الأوامر
|
||||
|
||||
| أمر | الوصف |
|
||||
| -------------------------------------- | ---------------------------------------------- |
|
||||
| `yarn twenty server start` | Start the local server (pulls image if needed) |
|
||||
| `yarn twenty server start --port 3030` | Start on a custom port |
|
||||
| `yarn twenty server stop` | Stop the server (preserves data) |
|
||||
| `yarn twenty server status` | Show server status, URL, and credentials |
|
||||
| `yarn twenty server logs` | Stream server logs |
|
||||
| `yarn twenty server logs --lines 100` | Show the last 100 log lines |
|
||||
| `yarn twenty server reset` | Delete all data and start fresh |
|
||||
| أمر | الوصف |
|
||||
| -------------------------------------- | --------------------------------------------- |
|
||||
| `yarn twenty server start` | بدء الخادم المحلي (يسحب الصورة إذا لزم الأمر) |
|
||||
| `yarn twenty server start --port 3030` | ابدأ على منفذ مخصّص |
|
||||
| `yarn twenty server stop` | إيقاف الخادم (مع الحفاظ على البيانات) |
|
||||
| `yarn twenty server status` | عرض حالة الخادم، وعنوان URL، وبيانات الاعتماد |
|
||||
| `yarn twenty server logs` | بث سجلات الخادم |
|
||||
| `yarn twenty server logs --lines 100` | عرض آخر 100 سطر من السجلات |
|
||||
| `yarn twenty server reset` | حذف جميع البيانات والبدء من جديد |
|
||||
|
||||
## CI with GitHub Actions
|
||||
## التكامل المستمر (CI) باستخدام GitHub Actions
|
||||
|
||||
The scaffolder generates a ready-to-use GitHub Actions workflow at `.github/workflows/ci.yml`. It runs your integration tests automatically on every push to `main` and on pull requests.
|
||||
تولّد أداة إنشاء الهيكل سير عمل GitHub Actions جاهزًا للاستخدام في `.github/workflows/ci.yml`. يشغّل اختبارات التكامل لديك تلقائيًا عند كل دفع إلى `main` وعلى طلبات السحب.
|
||||
|
||||
The workflow:
|
||||
سير العمل:
|
||||
|
||||
1. Checks out your code
|
||||
2. Spins up a temporary Twenty server using the `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` action
|
||||
3. Installs dependencies with `yarn install --immutable`
|
||||
4. Runs `yarn test` with `TWENTY_API_URL` and `TWENTY_API_KEY` injected from the action outputs
|
||||
1. يجلب الشيفرة الخاصة بك
|
||||
2. يشغّل خادم Twenty مؤقتًا باستخدام الإجراء `twentyhq/twenty/.github/actions/spawn-twenty-docker-image`
|
||||
3. يثبّت الاعتمادات باستخدام `yarn install --immutable`
|
||||
4. يشغّل `yarn test` مع حقن `TWENTY_API_URL` و`TWENTY_API_KEY` من مخرجات الإجراء
|
||||
|
||||
```yaml .github/workflows/ci.yml
|
||||
name: CI
|
||||
@@ -369,21 +369,21 @@ jobs:
|
||||
TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
|
||||
```
|
||||
|
||||
You don't need to configure any secrets — the `spawn-twenty-docker-image` action starts an ephemeral Twenty server directly in the runner and outputs the connection details. The `GITHUB_TOKEN` secret is provided automatically by GitHub.
|
||||
لا تحتاج إلى تهيئة أي أسرار — إذ يبدأ إجراء `spawn-twenty-docker-image` خادم Twenty عابرًا مباشرة في المشغّل ويُخرِج تفاصيل الاتصال. يتم توفير السر `GITHUB_TOKEN` تلقائيًا من قِبل GitHub.
|
||||
|
||||
To pin a specific Twenty version instead of `latest`, change the `TWENTY_VERSION` environment variable at the top of the workflow.
|
||||
لتثبيت إصدار محدّد من Twenty بدلًا من `latest`، غيّر متغير البيئة `TWENTY_VERSION` في أعلى سير العمل.
|
||||
|
||||
## إعداد يدوي (بدون المهيئ)
|
||||
|
||||
If you prefer to set things up yourself instead of using `create-twenty-app`, you can do it in two steps.
|
||||
إذا كنت تفضّل إعداد الأمور بنفسك بدلًا من استخدام `create-twenty-app`، فيمكنك ذلك بخطوتين.
|
||||
|
||||
**1. Add `twenty-sdk` and `twenty-client-sdk` as dependencies:**
|
||||
**1. أضِف `twenty-sdk` و`twenty-client-sdk` كاعتمادات:**
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn add twenty-sdk twenty-client-sdk
|
||||
```
|
||||
|
||||
**2. Add a `twenty` script to your `package.json`:**
|
||||
**2. أضِف نصًا برمجيًا باسم `twenty` إلى `package.json` لديك:**
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -393,19 +393,19 @@ yarn add twenty-sdk twenty-client-sdk
|
||||
}
|
||||
```
|
||||
|
||||
You can now run `yarn twenty dev`, `yarn twenty help`, and all other commands.
|
||||
يمكنك الآن تشغيل `yarn twenty dev`، و`yarn twenty help`، وجميع الأوامر الأخرى.
|
||||
|
||||
<Note>
|
||||
Do not install `twenty-sdk` globally. Always use it as a local project dependency so that each project can pin its own version.
|
||||
لا تثبّت `twenty-sdk` عالميًا. استخدمه دائمًا كاعتماد محلي للمشروع بحيث يتمكن كل مشروع من تثبيت إصداره الخاص.
|
||||
</Note>
|
||||
|
||||
## استكشاف الأخطاء وإصلاحها
|
||||
|
||||
If you run into issues:
|
||||
إذا واجهت مشاكل:
|
||||
|
||||
* Make sure **Docker is running** before starting the scaffolder with a local instance.
|
||||
* Make sure you are using **Node.js 24+** (`node -v` to check).
|
||||
* Make sure **Corepack is enabled** (`corepack enable`) so Yarn 4 is available.
|
||||
* Try deleting `node_modules` and running `yarn install` again if dependencies seem broken.
|
||||
* تأكّد من أن **Docker قيد التشغيل** قبل تشغيل أداة إنشاء الهيكل مع مثيل محلي.
|
||||
* تأكّد من أنك تستخدم **Node.js 24+** (`node -v` للتحقق).
|
||||
* تأكّد من **تمكين Corepack** (`corepack enable`) حتى يتوفر Yarn 4.
|
||||
* جرّب حذف `node_modules` وتشغيل `yarn install` مرة أخرى إذا بدت الاعتمادات معطّلة.
|
||||
|
||||
Still stuck? Ask for help on the [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).
|
||||
ما زلت عالقًا؟ اطلب المساعدة على [خادم Twenty على Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).
|
||||
|
||||
@@ -18,13 +18,13 @@ description: وزّع تطبيق Twenty الخاص بك على سوق Twenty أ
|
||||
|
||||
## بناء تطبيقك
|
||||
|
||||
Run the build command to compile your app and generate a distribution-ready `manifest.json`:
|
||||
شغّل أمر build لتجميع تطبيقك وإنشاء ملف `manifest.json` جاهز للتوزيع:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty build
|
||||
```
|
||||
|
||||
This compiles TypeScript sources, transpiles logic functions and front components, and writes everything to `.twenty/output/`. Add `--tarball` to also produce a `.tgz` package for manual distribution or the deploy command.
|
||||
يقوم هذا بتجميع مصادر TypeScript، وتحويل دوال المنطق ومكوّنات الواجهة الأمامية، وكتابة كل شيء إلى `.twenty/output/`. أضِف `--tarball` لإنتاج حزمة `.tgz` أيضًا للتوزيع اليدوي أو لأمر deploy.
|
||||
|
||||
## النشر إلى خادم (tarball)
|
||||
|
||||
@@ -61,7 +61,7 @@ yarn twenty deploy
|
||||
يستخدم رابط المشاركة عنوان URL الأساسي للخادم (من دون أي نطاق فرعي لمساحة عمل)، لذا يعمل مع أي مساحة عمل على الخادم.
|
||||
|
||||
<Warning>
|
||||
Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > Enterprise](/settings/admin-panel#enterprise) to enable it.
|
||||
مشاركة التطبيقات الخاصة هي ميزة ضمن باقة Enterprise. اذهب إلى [الإعدادات > لوحة الإدارة > Enterprise](/settings/admin-panel#enterprise) لتمكينها.
|
||||
</Warning>
|
||||
|
||||
### إدارة الإصدارات
|
||||
@@ -69,7 +69,7 @@ Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > E
|
||||
لطرح تحديث:
|
||||
|
||||
1. ارفع قيمة الحقل `version` في ملف `package.json`
|
||||
2. Run `yarn twenty deploy` (or `yarn twenty deploy --remote production`)
|
||||
2. شغّل `yarn twenty deploy` (أو `yarn twenty deploy --remote production`)
|
||||
3. سترى مساحات العمل التي ثبّتت التطبيق الترقية متاحة في إعداداتها
|
||||
|
||||
{/* TODO: add screenshot of the Upgrade button */}
|
||||
@@ -81,7 +81,7 @@ Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > E
|
||||
### المتطلبات
|
||||
|
||||
* حساب على [npm](https://www.npmjs.com)
|
||||
* The `twenty-app` keyword in your `package.json` `keywords` array (already included when you scaffold with `create-twenty-app`)
|
||||
* الكلمة المفتاحية `twenty-app` في مصفوفة `keywords` في `package.json` (موجودة مسبقًا عند تهيئة المشروع باستخدام `create-twenty-app`)
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -93,7 +93,7 @@ Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > E
|
||||
|
||||
### بيانات التعريف لسوق التطبيقات
|
||||
|
||||
The `defineApplication()` config supports optional fields that control how your app appears in the marketplace. Use `logoUrl` and `screenshots` to reference images from the `public/` folder:
|
||||
يدعم إعداد `defineApplication()` حقولًا اختيارية تتحكم في كيفية ظهور تطبيقك في السوق. استخدم `logoUrl` و`screenshots` للإشارة إلى الصور من مجلد `public/`:
|
||||
|
||||
```ts src/application-config.ts
|
||||
export default defineApplication({
|
||||
@@ -109,9 +109,9 @@ export default defineApplication({
|
||||
});
|
||||
```
|
||||
|
||||
See the [defineApplication accordion](/l/ar/developers/extend/apps/building#defineentity-functions) in the Building Apps page for the full list of marketplace fields (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
|
||||
اطّلع على [أكورديون defineApplication](/l/ar/developers/extend/apps/building#defineentity-functions) في صفحة بناء التطبيقات للاطلاع على القائمة الكاملة لحقول السوق (`author` و`category` و`aboutDescription` و`websiteUrl` و`termsUrl` وغيرها).
|
||||
|
||||
### Publish
|
||||
### النشر
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty publish
|
||||
@@ -127,7 +127,7 @@ yarn twenty publish --tag beta
|
||||
|
||||
يقوم خادم Twenty بمزامنة كتالوج السوق من سجل npm **كل ساعة**.
|
||||
|
||||
You can trigger the sync immediately instead of waiting:
|
||||
يمكنك تشغيل المزامنة فورًا بدلًا من الانتظار:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty catalog-sync
|
||||
@@ -135,7 +135,7 @@ yarn twenty catalog-sync
|
||||
# yarn twenty catalog-sync --remote production
|
||||
```
|
||||
|
||||
The metadata shown in the marketplace comes from your `defineApplication()` config — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
|
||||
تأتي بيانات التعريف المعروضة في السوق من إعداد `defineApplication()` — حقول مثل `displayName` و`description` و`author` و`category` و`logoUrl` و`screenshots` و`aboutDescription` و`websiteUrl` و`termsUrl`.
|
||||
|
||||
<Note>
|
||||
إذا لم يحدد تطبيقك `aboutDescription` في `defineApplication()`، فسيستخدم السوق تلقائيًا ملف `README.md` الخاص بحزمتك من npm كمحتوى لصفحة حول. هذا يعني أنه يمكنك الاحتفاظ بملف README واحد لكل من npm وسوق Twenty. إذا كنت تريد وصفًا مختلفًا في السوق، فقم بتعيين `aboutDescription` بشكل صريح.
|
||||
@@ -143,7 +143,7 @@ The metadata shown in the marketplace comes from your `defineApplication()` conf
|
||||
|
||||
### النشر عبر CI
|
||||
|
||||
Use this GitHub Actions workflow to publish automatically on every release (uses [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
استخدم سير عمل GitHub Actions هذا للنشر تلقائيًا مع كل إصدار (يستخدم [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
|
||||
```yaml filename=".github/workflows/publish.yml"
|
||||
name: Publish
|
||||
@@ -178,13 +178,13 @@ jobs:
|
||||
|
||||
## تثبيت التطبيقات
|
||||
|
||||
Once an app is published (npm) or deployed (tarball), workspaces can install it through the UI.
|
||||
بعد نشر التطبيق (npm) أو نشره (tarball)، يمكن لمساحات العمل تثبيته عبر واجهة المستخدم.
|
||||
|
||||
Go to the **Settings > Applications** page in Twenty, where both marketplace and tarball-deployed apps can be browsed and installed.
|
||||
اذهب إلى صفحة **الإعدادات > التطبيقات** في Twenty، حيث يمكن استعراض تطبيقات السوق والتطبيقات المنشورة عبر tarball وتثبيتها.
|
||||
|
||||
{/* TODO: add screenshot of the UI when the app is registered */}
|
||||
|
||||
You can also install apps from the command line:
|
||||
يمكنك أيضًا تثبيت التطبيقات من سطر الأوامر:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty install
|
||||
|
||||
@@ -4,22 +4,22 @@ description: أنشئ وأدِر تخصيصات Twenty على هيئة كود.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha. The feature works but is still evolving.
|
||||
التطبيقات حاليًا في مرحلة الألفا. الميزة تعمل لكنها لا تزال قيد التطور.
|
||||
</Warning>
|
||||
|
||||
## What are apps?
|
||||
## ما هي التطبيقات؟
|
||||
|
||||
Apps let you extend Twenty with custom objects, fields, logic functions, front components, AI skills, and more — all managed as code. Instead of configuring everything through the UI, you define your data model and logic in TypeScript and deploy it to one or more workspaces.
|
||||
تتيح لك التطبيقات توسيع Twenty باستخدام كائنات وحقول مخصّصة ووظائف منطقية ومكوّنات الواجهة الأمامية ومهارات الذكاء الاصطناعي وغير ذلك — جميعها تُدار ككود. بدلًا من تكوين كل شيء عبر واجهة المستخدم، تعرّف نموذج بياناتك ومنطقك في TypeScript وتقوم بنشره إلى مساحة عمل واحدة أو أكثر.
|
||||
|
||||
**ما الذي يمكنك بناؤه:**
|
||||
|
||||
* **Custom objects and fields** — extend your data model with new entities or add fields to existing objects like Company or Person
|
||||
* **Logic functions** — server-side functions triggered by database events, cron schedules, or HTTP routes
|
||||
* **Front components** — React components that render inside Twenty's UI (record pages, command menu, side panels)
|
||||
* **AI skills and agents** — extend Twenty's AI with custom capabilities
|
||||
* **Views and navigation** — preconfigured saved views and sidebar links
|
||||
* **الكائنات والحقول المخصّصة** — وسّع نموذج بياناتك بكيانات جديدة أو أضف حقولًا إلى الكائنات الموجودة مثل Company أو Person
|
||||
* **الوظائف المنطقية** — وظائف على جانب الخادم يتم تشغيلها بواسطة أحداث قاعدة البيانات، أو جداول cron، أو مسارات HTTP
|
||||
* **مكوّنات الواجهة الأمامية** — مكوّنات React تُعرَض داخل واجهة مستخدم Twenty (صفحات السجل، قائمة الأوامر، اللوحات الجانبية)
|
||||
* **مهارات ووكلاء الذكاء الاصطناعي** — وسّع ذكاء Twenty الاصطناعي بقدرات مخصّصة
|
||||
* **العروض والتنقّل** — عروض محفوظة مُعدّة مسبقًا وروابط الشريط الجانبي
|
||||
|
||||
## Quick start
|
||||
## البدء السريع
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
@@ -27,55 +27,55 @@ cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
This scaffolds a new app, optionally starts a local Twenty server, and begins watching your files for changes. See the [Getting Started](/l/ar/developers/extend/apps/getting-started) guide for the full walkthrough.
|
||||
يُنشئ هذا هيكل تطبيق جديدًا، ويبدأ اختياريًا خادم Twenty محليًا، ويبدأ في مراقبة ملفاتك لاكتشاف التغييرات. اطّلع على دليل [البدء](/l/ar/developers/extend/apps/getting-started) للحصول على شرح كامل.
|
||||
|
||||
## Detailed guides
|
||||
## أدلة تفصيلية
|
||||
|
||||
| Guide | الوصف |
|
||||
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Getting Started](/l/ar/developers/extend/apps/getting-started) | Scaffold an app, set up a local server, project structure, CI |
|
||||
| [Building Apps](/l/ar/developers/extend/apps/building) | Entity definitions (`defineObject`, `defineLogicFunction`, `defineFrontComponent`, etc.), API clients, npm packages, public assets, testing |
|
||||
| [Publishing](/l/ar/developers/extend/apps/publishing) | Deploy to a server, publish to npm, marketplace |
|
||||
| دليل | الوصف |
|
||||
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [البدء](/l/ar/developers/extend/apps/getting-started) | إنشاء هيكل تطبيق، إعداد خادم محلي، بنية المشروع، التكامل المستمر |
|
||||
| [بناء التطبيقات](/l/ar/developers/extend/apps/building) | تعريفات الكيانات (`defineObject`, `defineLogicFunction`, `defineFrontComponent`، إلخ)، عملاء API، حزم npm، الأصول العامة، الاختبار |
|
||||
| [النشر](/l/ar/developers/extend/apps/publishing) | النشر إلى خادم، النشر إلى npm، السوق |
|
||||
|
||||
## Key concepts
|
||||
## المفاهيم الأساسية
|
||||
|
||||
### اكتشاف الكيانات
|
||||
|
||||
The SDK detects entities by scanning your TypeScript files for `export default define<Entity>({...})` calls. File naming and folder structure are flexible — detection is AST-based, not path-based.
|
||||
يكتشف SDK الكيانات عبر فحص ملفات TypeScript لديك بحثًا عن استدعاءات `export default define<Entity>({...})`. تسمية الملفات وبنية المجلدات مرنة — يعتمد الاكتشاف على AST وليس على المسارات.
|
||||
|
||||
### Available entity types
|
||||
### أنواع الكيانات المتاحة
|
||||
|
||||
| دالة | الغرض |
|
||||
| ---------------------------------- | -------------------------------------------- |
|
||||
| `defineApplication()` | Application metadata (required, one per app) |
|
||||
| `defineObject()` | Custom objects with fields |
|
||||
| `defineField()` | Fields on existing objects |
|
||||
| `defineLogicFunction()` | Server-side logic with triggers |
|
||||
| `defineFrontComponent()` | React components in Twenty's UI |
|
||||
| `defineRole()` | Permission roles |
|
||||
| `defineView()` | Saved view configurations |
|
||||
| `defineNavigationMenuItem()` | Sidebar navigation links |
|
||||
| `defineSkill()` | AI agent skills |
|
||||
| `defineAgent()` | AI agents with prompts |
|
||||
| `definePageLayout()` | Custom record page layouts |
|
||||
| `definePreInstallLogicFunction()` | Runs before app installation |
|
||||
| `definePostInstallLogicFunction()` | Runs after app installation |
|
||||
| دالة | الغرض |
|
||||
| ---------------------------------- | ------------------------------------------------ |
|
||||
| `defineApplication()` | بيانات التعريف للتطبيق (مطلوبة، واحدة لكل تطبيق) |
|
||||
| `defineObject()` | كائنات مخصّصة مع حقول |
|
||||
| `defineField()` | حقول على الكائنات الموجودة |
|
||||
| `defineLogicFunction()` | منطق على جانب الخادم مع مشغّلات |
|
||||
| `defineFrontComponent()` | مكوّنات React ضمن واجهة مستخدم Twenty |
|
||||
| `defineRole()` | أدوار الصلاحيات |
|
||||
| `defineView()` | تكوينات العروض المحفوظة |
|
||||
| `defineNavigationMenuItem()` | روابط التنقّل في الشريط الجانبي |
|
||||
| `defineSkill()` | مهارات وكيل الذكاء الاصطناعي |
|
||||
| `defineAgent()` | وكلاء ذكاء اصطناعي مع موجّهات |
|
||||
| `definePageLayout()` | تخطيطات صفحات السجل المخصّصة |
|
||||
| `definePreInstallLogicFunction()` | يعمل قبل تثبيت التطبيق |
|
||||
| `definePostInstallLogicFunction()` | يعمل بعد تثبيت التطبيق |
|
||||
|
||||
### Development workflow
|
||||
### سير عمل التطوير
|
||||
|
||||
1. **`yarn twenty dev`** — watches source files, rebuilds on change, syncs to the server, generates typed API clients
|
||||
2. **`yarn twenty build`** — produces a distributable build
|
||||
3. **`yarn twenty deploy`** — deploys to a remote Twenty server
|
||||
4. **`yarn twenty add`** — scaffolds a new entity interactively
|
||||
1. **`yarn twenty dev`** — يراقب ملفات المصدر، ويعيد البناء عند التغيير، ويُزامن مع الخادم، ويولّد عملاء API بأنواع محددة
|
||||
2. **`yarn twenty build`** — ينتج إصدارًا قابلًا للتوزيع
|
||||
3. **`yarn twenty deploy`** — ينشر إلى خادم Twenty بعيد
|
||||
4. **`yarn twenty add`** — ينشئ هيكلًا لكيان جديد تفاعليًا
|
||||
|
||||
### مرجع CLI
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty help # List all commands
|
||||
yarn twenty server start # Start local dev server
|
||||
yarn twenty remote add # Connect to a Twenty server
|
||||
yarn twenty exec -n fn # Execute a logic function
|
||||
yarn twenty logs -n fn # Stream function logs
|
||||
yarn twenty help # عرض جميع الأوامر
|
||||
yarn twenty server start # بدء خادم التطوير المحلي
|
||||
yarn twenty remote add # الاتصال بخادم Twenty
|
||||
yarn twenty exec -n fn # تنفيذ دالة المنطق
|
||||
yarn twenty logs -n fn # بث سجلات الدالة
|
||||
```
|
||||
|
||||
See the [Getting Started](/l/ar/developers/extend/apps/getting-started) guide for the full CLI reference.
|
||||
اطّلع على دليل [البدء](/l/ar/developers/extend/apps/getting-started) للاطلاع على مرجع CLI الكامل.
|
||||
|
||||
@@ -4,142 +4,142 @@ description: Vytvořte svou první aplikaci Twenty během několika minut.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha. The feature works but is still evolving.
|
||||
Aplikace jsou aktuálně v alfa fázi. Funkce funguje, ale stále se vyvíjí.
|
||||
</Warning>
|
||||
|
||||
Aplikace vám umožňují rozšířit Twenty o vlastní objekty, pole, logické funkce, AI schopnosti a komponenty uživatelského rozhraní — vše je spravováno jako kód.
|
||||
|
||||
## Předpoklady
|
||||
|
||||
Before you begin, make sure the following is installed on your machine:
|
||||
Než začnete, ujistěte se, že máte ve svém počítači nainstalováno následující:
|
||||
|
||||
* **Node.js 24+** — [Download here](https://nodejs.org/)
|
||||
* **Yarn 4** — Comes with Node.js via Corepack. Enable it by running `corepack enable`
|
||||
* **Docker** — [Download here](https://www.docker.com/products/docker-desktop/). Required to run a local Twenty instance. Not needed if you already have a Twenty server running.
|
||||
* **Node.js 24+** — [Stáhnout zde](https://nodejs.org/)
|
||||
* **Yarn 4** — Dodává se s Node.js prostřednictvím Corepacku. Povolte jej spuštěním `corepack enable`
|
||||
* **Docker** — [Stáhnout zde](https://www.docker.com/products/docker-desktop/). Nutné pro spuštění lokální instance Twenty. Není potřeba, pokud už máte spuštěný server Twenty.
|
||||
|
||||
## Step 1: Scaffold your app
|
||||
## Krok 1: Vytvořte kostru své aplikace
|
||||
|
||||
Open a terminal and run:
|
||||
Otevřete terminál a spusťte:
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
```
|
||||
|
||||
You will be prompted to enter a name and a description for your app. Press **Enter** to accept the defaults.
|
||||
Budete vyzváni k zadání názvu a popisu své aplikace. Stisknutím **Enter** přijmete výchozí hodnoty.
|
||||
|
||||
This creates a new folder called `my-twenty-app` with everything you need.
|
||||
Tím se vytvoří nová složka s názvem `my-twenty-app` se vším potřebným.
|
||||
|
||||
<Note>
|
||||
The scaffolder supports these flags:
|
||||
Generátor kostry podporuje tyto přepínače:
|
||||
|
||||
* `--minimal` — scaffold only the essential files, no examples (default)
|
||||
* `--exhaustive` — scaffold all example entities
|
||||
* `--name <name>` — set the app name (skips the prompt)
|
||||
* `--display-name <displayName>` — set the display name (skips the prompt)
|
||||
* `--description <description>` — set the description (skips the prompt)
|
||||
* `--skip-local-instance` — skip the local server setup prompt
|
||||
* `--minimal` — vygeneruje pouze nezbytné soubory, bez příkladů (výchozí)
|
||||
* `--exhaustive` — vygeneruje všechny ukázkové entity
|
||||
* `--name <name>` — nastaví název aplikace (přeskočí výzvu)
|
||||
* `--display-name <displayName>` — nastaví zobrazovaný název (přeskočí výzvu)
|
||||
* `--description <description>` — nastaví popis (přeskočí výzvu)
|
||||
* `--skip-local-instance` — přeskočí výzvu k nastavení lokálního serveru
|
||||
</Note>
|
||||
|
||||
## Step 2: Set up a local Twenty instance
|
||||
## Krok 2: Nastavte lokální instanci Twenty
|
||||
|
||||
The scaffolder will ask:
|
||||
Generátor kostry se zeptá:
|
||||
|
||||
> **Would you like to set up a local Twenty instance?**
|
||||
> **Chcete nastavit lokální instanci Twenty?**
|
||||
|
||||
* **Type `yes`** (recommended) — This pulls the `twenty-app-dev` Docker image and starts a local Twenty server on port `2020`. Make sure Docker is running before you continue.
|
||||
* **Type `no`** — Choose this if you already have a Twenty server running locally.
|
||||
* **Zadejte `yes`** (doporučeno) — Stáhne image Dockeru `twenty-app-dev` a spustí lokální server Twenty na portu `2020`. Než budete pokračovat, ujistěte se, že Docker běží.
|
||||
* **Zadejte `no`** — Zvolte, pokud už máte lokálně spuštěný server Twenty.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Should start local instance?" />
|
||||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Spustit lokální instanci?" />
|
||||
</div>
|
||||
|
||||
## Step 3: Sign in to your workspace
|
||||
## Krok 3: Přihlaste se do svého pracovního prostoru
|
||||
|
||||
Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
|
||||
Poté se otevře okno prohlížeče se stránkou přihlášení do Twenty. Přihlaste se předpřipraveným demo účtem:
|
||||
|
||||
* **Email:** `tim@apple.dev`
|
||||
* **Password:** `tim@apple.dev`
|
||||
* **E-mail:** `tim@apple.dev`
|
||||
* **Heslo:** `tim@apple.dev`
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />
|
||||
<img src="/images/docs/developers/extends/apps/login.png" alt="Přihlašovací obrazovka Twenty" />
|
||||
</div>
|
||||
|
||||
## Step 4: Authorize the app
|
||||
## Krok 4: Autorizujte aplikaci
|
||||
|
||||
After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
|
||||
Po přihlášení uvidíte autorizační obrazovku. Tím umožníte vaší aplikaci pracovat s vaším pracovním prostorem.
|
||||
|
||||
Click **Authorize** to continue.
|
||||
Pokračujte kliknutím na **Authorize**.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI authorization screen" />
|
||||
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Autorizační obrazovka Twenty CLI" />
|
||||
</div>
|
||||
|
||||
Once authorized, your terminal will confirm that everything is set up.
|
||||
Po autorizaci váš terminál potvrdí, že je vše nastaveno.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />
|
||||
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Aplikace byla úspěšně vygenerována" />
|
||||
</div>
|
||||
|
||||
## Step 5: Start developing
|
||||
## Krok 5: Začněte vyvíjet
|
||||
|
||||
Go into your new app folder and start the development server:
|
||||
Přejděte do nové složky aplikace a spusťte vývojový server:
|
||||
|
||||
```bash filename="Terminal"
|
||||
cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
This watches your source files, rebuilds on every change, and syncs your app to the local Twenty server automatically. You should see a live status panel in your terminal.
|
||||
Sleduje zdrojové soubory, při každé změně znovu sestaví a automaticky synchronizuje vaši aplikaci s lokálním serverem Twenty. V terminálu byste měli vidět panel se stavem v reálném čase.
|
||||
|
||||
For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
|
||||
Pro podrobnější výstup (protokoly sestavení, požadavky na synchronizaci, stopy chyb) použijte přepínač `--verbose`:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev --verbose
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Dev mode is only available on Twenty instances running in development (`NODE_ENV=development`). Production instances reject dev sync requests. Use `yarn twenty deploy` to deploy to production servers — see [Publishing Apps](/l/cs/developers/extend/apps/publishing) for details.
|
||||
Vývojový režim je k dispozici pouze na instancích Twenty běžících v režimu development (`NODE_ENV=development`). Produkční instance odmítají požadavky na vývojovou synchronizaci. Pro nasazení na produkční servery použijte `yarn twenty deploy` — podrobnosti viz [Publikování aplikací](/l/cs/developers/extend/apps/publishing).
|
||||
</Warning>
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Dev mode terminal output" />
|
||||
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Výstup terminálu ve vývojovém režimu" />
|
||||
</div>
|
||||
|
||||
## Step 6: See your app in Twenty
|
||||
## Krok 6: Zobrazte svou aplikaci v Twenty
|
||||
|
||||
Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) in your browser. Navigate to **Settings > Apps** and select the **Developer** tab. You should see your app listed under **Your Apps**:
|
||||
Otevřete ve svém prohlížeči [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Přejděte do **Settings > Apps** a vyberte kartu **Developer**. Vaše aplikace by měla být uvedena v části **Your Apps**:
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps list showing My twenty app" />
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Seznam Your Apps zobrazující My twenty app" />
|
||||
</div>
|
||||
|
||||
Click on **My twenty app** to open its **application registration**. A registration is a server-level record that describes your app — its name, unique identifier, OAuth credentials, and source (local, npm, or tarball). It lives on the server, not inside any specific workspace. When you install an app into a workspace, Twenty creates a workspace-scoped **application** that points back to this registration. One registration can be installed across multiple workspaces on the same server.
|
||||
Klikněte na **My twenty app** a otevřete její **registraci aplikace**. Registrace je záznam na úrovni serveru, který popisuje vaši aplikaci — její název, jedinečný identifikátor, přihlašovací údaje OAuth a zdroj (lokální, npm nebo tarball). Existuje na serveru, ne uvnitř žádného konkrétního pracovního prostoru. Když nainstalujete aplikaci do pracovního prostoru, Twenty vytvoří **aplikaci** v rozsahu pracovního prostoru, která odkazuje zpět na tuto registraci. Jedna registrace může být nainstalována ve více pracovních prostorech na stejném serveru.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Application registration details" />
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Podrobnosti registrace aplikace" />
|
||||
</div>
|
||||
|
||||
Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
|
||||
Klikněte na **View installed app**, abyste zobrazili nainstalovanou aplikaci. Karta **About** zobrazuje aktuální verzi a možnosti správy:
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installed app — About tab" />
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Nainstalovaná aplikace — karta About" />
|
||||
</div>
|
||||
|
||||
Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
|
||||
Přepněte na kartu **Content**, abyste viděli vše, co vaše aplikace poskytuje — objekty, pole, logické funkce a agenty:
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Installed app — Content tab" />
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Nainstalovaná aplikace — karta Content" />
|
||||
</div>
|
||||
|
||||
You are all set! Edit any file in `src/` and the changes will be picked up automatically.
|
||||
Vše je připraveno! Upravte libovolný soubor ve složce `src/` a změny se zachytí automaticky.
|
||||
|
||||
Head over to [Building Apps](/l/cs/developers/extend/apps/building) for a detailed guide on creating objects, logic functions, front components, skills, and more.
|
||||
Přejděte na [Tvorba aplikací](/l/cs/developers/extend/apps/building) pro podrobný průvodce vytvářením objektů, logických funkcí, frontendových komponent, dovedností a dalšího.
|
||||
|
||||
---
|
||||
|
||||
## Project structure
|
||||
## Struktura projektu
|
||||
|
||||
The scaffolder generates the following file structure (shown with `--exhaustive` mode, which includes examples for every entity type):
|
||||
Generátor kostry vytvoří následující strukturu souborů (zobrazeno v režimu `--exhaustive`, který zahrnuje příklady pro každý typ entity):
|
||||
|
||||
```text filename="my-twenty-app/"
|
||||
my-twenty-app/
|
||||
@@ -190,30 +190,30 @@ my-twenty-app/
|
||||
└── example-agent.ts # Example AI agent definition
|
||||
```
|
||||
|
||||
By default (`--minimal`), only the core files are created: `application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts`, and `logic-functions/post-install.ts`. Use `--exhaustive` to include all the example files shown above.
|
||||
Ve výchozím nastavení (`--minimal`) se vytvoří pouze základní soubory: `application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` a `logic-functions/post-install.ts`. Pro zahrnutí všech ukázkových souborů výše použijte `--exhaustive`.
|
||||
|
||||
### Key files
|
||||
### Klíčové soubory
|
||||
|
||||
| File / Folder | Účel |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `package.json` | Declares your app name, version, and dependencies. Includes a `twenty` script so you can run `yarn twenty help` to see all commands. |
|
||||
| `src/application-config.ts` | **Required.** The main configuration file for your app. |
|
||||
| `src/roles/` | Defines roles that control what your logic functions can access. |
|
||||
| `src/logic-functions/` | Server-side functions triggered by routes, cron schedules, or database events. |
|
||||
| `src/front-components/` | React components that render inside Twenty's UI. |
|
||||
| `src/objects/` | Custom object definitions to extend your data model. |
|
||||
| `src/fields/` | Custom fields added to existing objects. |
|
||||
| `src/views/` | Saved view configurations. |
|
||||
| `src/navigation-menu-items/` | Custom links in the sidebar navigation. |
|
||||
| `src/skills/` | Dovednosti, které rozšiřují možnosti AI agentů Twenty. |
|
||||
| `src/agents/` | AI agents with custom prompts. |
|
||||
| `src/page-layouts/` | Custom page layouts for record views. |
|
||||
| `src/__tests__/` | Integration tests (setup + example test). |
|
||||
| `public/` | Static assets (images, fonts) served with your app. |
|
||||
| Soubor / Složka | Účel |
|
||||
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `package.json` | Definuje název, verzi a závislosti vaší aplikace. Obsahuje skript `twenty`, takže můžete spustit `yarn twenty help` a zobrazit všechny příkazy. |
|
||||
| `src/application-config.ts` | **Povinné.** Hlavní konfigurační soubor vaší aplikace. |
|
||||
| `src/roles/` | Definuje role, které určují, k čemu mají vaše logické funkce přístup. |
|
||||
| `src/logic-functions/` | Serverové funkce spouštěné trasami, plánovačem cron nebo událostmi databáze. |
|
||||
| `src/front-components/` | Komponenty Reactu, které se vykreslují uvnitř uživatelského rozhraní Twenty. |
|
||||
| `src/objects/` | Vlastní definice objektů pro rozšíření vašeho datového modelu. |
|
||||
| `src/fields/` | Vlastní pole přidaná k existujícím objektům. |
|
||||
| `src/views/` | Konfigurace uložených zobrazení. |
|
||||
| `src/navigation-menu-items/` | Vlastní odkazy v postranní navigaci. |
|
||||
| `src/skills/` | Dovednosti, které rozšiřují možnosti AI agentů Twenty. |
|
||||
| `src/agents/` | AI agenti s vlastními prompty. |
|
||||
| `src/page-layouts/` | Vlastní rozvržení stránek pro zobrazení záznamů. |
|
||||
| `src/__tests__/` | Integrační testy (nastavení + ukázkový test). |
|
||||
| `public/` | Statická aktiva (obrázky, písma) poskytovaná s vaší aplikací. |
|
||||
|
||||
## Managing remotes
|
||||
## Správa vzdálených serverů
|
||||
|
||||
A **remote** is a Twenty server that your app connects to. During setup, the scaffolder creates one for you automatically. You can add more remotes or switch between them at any time.
|
||||
A **remote** je server Twenty, ke kterému se vaše aplikace připojuje. Během nastavení jej generátor kostry automaticky vytvoří. Můžete kdykoli přidat další vzdálené servery nebo mezi nimi přepínat.
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Add a new remote (opens a browser for OAuth login)
|
||||
@@ -232,11 +232,11 @@ yarn twenty remote list
|
||||
yarn twenty remote switch <name>
|
||||
```
|
||||
|
||||
Your credentials are stored in `~/.twenty/config.json`.
|
||||
Vaše přihlašovací údaje jsou uloženy v `~/.twenty/config.json`.
|
||||
|
||||
## Local development server (`yarn twenty server`)
|
||||
## Lokální vývojový server (`yarn twenty server`)
|
||||
|
||||
The CLI can manage a local Twenty server running in Docker. This is the same server started automatically when you scaffold an app with `create-twenty-app`, but you can also manage it manually.
|
||||
CLI může spravovat lokální server Twenty běžící v Dockeru. Jde o stejný server, který se spustí automaticky při vytvoření kostry aplikace pomocí `create-twenty-app`, ale můžete jej spravovat i ručně.
|
||||
|
||||
### Spuštění serveru
|
||||
|
||||
@@ -244,85 +244,85 @@ The CLI can manage a local Twenty server running in Docker. This is the same ser
|
||||
yarn twenty server start
|
||||
```
|
||||
|
||||
This pulls the `twentycrm/twenty-app-dev:latest` Docker image (if not already present), creates a container named `twenty-app-dev`, and starts it on port **2020**. The CLI waits until the server passes its health check before returning.
|
||||
Stáhne image Dockeru `twentycrm/twenty-app-dev:latest` (pokud již není k dispozici), vytvoří kontejner s názvem `twenty-app-dev` a spustí jej na portu **2020**. CLI čeká, dokud server neprojde kontrolou stavu, než vrátí řízení.
|
||||
|
||||
Two Docker volumes are created to persist data between restarts:
|
||||
Vytvoří se dva svazky Dockeru pro zachování dat mezi restartováními:
|
||||
|
||||
* `twenty-app-dev-data` — PostgreSQL database
|
||||
* `twenty-app-dev-storage` — file storage
|
||||
* `twenty-app-dev-data` — databáze PostgreSQL
|
||||
* `twenty-app-dev-storage` — úložiště souborů
|
||||
|
||||
If port 2020 is already in use, you can start on a different port:
|
||||
Pokud je port 2020 již používán, můžete spustit na jiném portu:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server start --port 3030
|
||||
```
|
||||
|
||||
The CLI automatically configures the container's internal `NODE_PORT` and `SERVER_URL` to match the chosen port, so logic functions, OAuth, and all other internal networking work correctly.
|
||||
CLI automaticky nakonfiguruje interní `NODE_PORT` a `SERVER_URL` kontejneru tak, aby odpovídaly zvolenému portu, takže logické funkce, OAuth a veškerá ostatní vnitřní síťová komunikace fungují správně.
|
||||
|
||||
Once started, the server is automatically registered as the `local` remote in your CLI config.
|
||||
Po spuštění je server automaticky zaregistrován jako `local` remote ve vaší konfiguraci CLI.
|
||||
|
||||
### Checking server status
|
||||
### Kontrola stavu serveru
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server status
|
||||
```
|
||||
|
||||
Displays whether the server is running, its URL, and the default login credentials (`tim@apple.dev` / `tim@apple.dev`).
|
||||
Zobrazí, zda server běží, jeho URL a výchozí přihlašovací údaje (`tim@apple.dev` / `tim@apple.dev`).
|
||||
|
||||
### Viewing server logs
|
||||
### Zobrazení protokolů serveru
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server logs
|
||||
```
|
||||
|
||||
Streams the container logs. Use `--lines` to control how many recent lines to show:
|
||||
Streamuje protokoly kontejneru. Pomocí `--lines` ovládnete, kolik posledních řádků se má zobrazit:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server logs --lines 100
|
||||
```
|
||||
|
||||
### Stopping the server
|
||||
### Zastavení serveru
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server stop
|
||||
```
|
||||
|
||||
Stops the container. Your data is preserved in the Docker volumes — the next `start` picks up where you left off.
|
||||
Zastaví kontejner. Vaše data jsou zachována ve svazcích Dockeru — další `start` naváže tam, kde jste skončili.
|
||||
|
||||
### Resetting the server
|
||||
### Resetování serveru
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty server reset
|
||||
```
|
||||
|
||||
Removes the container **and** deletes both Docker volumes, wiping all data. The next `start` creates a fresh instance.
|
||||
Odstraní kontejner **a** smaže oba svazky Dockeru, čímž vymaže všechna data. Další `start` vytvoří čistou instanci.
|
||||
|
||||
<Note>
|
||||
The server requires **Docker** to be running. If you see a "Docker not running" error, make sure Docker Desktop (or the Docker daemon) is started.
|
||||
Server vyžaduje, aby **Docker** běžel. Pokud vidíte chybu "Docker not running", ujistěte se, že je spuštěný Docker Desktop (nebo démon Dockeru).
|
||||
</Note>
|
||||
|
||||
### Command reference
|
||||
### Přehled příkazů
|
||||
|
||||
| Příkaz | Popis |
|
||||
| -------------------------------------- | ---------------------------------------------- |
|
||||
| `yarn twenty server start` | Start the local server (pulls image if needed) |
|
||||
| `yarn twenty server start --port 3030` | Start on a custom port |
|
||||
| `yarn twenty server stop` | Stop the server (preserves data) |
|
||||
| `yarn twenty server status` | Show server status, URL, and credentials |
|
||||
| `yarn twenty server logs` | Stream server logs |
|
||||
| `yarn twenty server logs --lines 100` | Show the last 100 log lines |
|
||||
| `yarn twenty server reset` | Delete all data and start fresh |
|
||||
| Příkaz | Popis |
|
||||
| -------------------------------------- | ------------------------------------------------------ |
|
||||
| `yarn twenty server start` | Spustí lokální server (v případě potřeby stáhne image) |
|
||||
| `yarn twenty server start --port 3030` | Spustí na vlastním portu |
|
||||
| `yarn twenty server stop` | Zastaví server (zachová data) |
|
||||
| `yarn twenty server status` | Zobrazí stav serveru, URL a přihlašovací údaje |
|
||||
| `yarn twenty server logs` | Streamuje protokoly serveru |
|
||||
| `yarn twenty server logs --lines 100` | Zobrazí posledních 100 řádků logu |
|
||||
| `yarn twenty server reset` | Smaže všechna data a začne znovu |
|
||||
|
||||
## CI with GitHub Actions
|
||||
## CI s GitHub Actions
|
||||
|
||||
The scaffolder generates a ready-to-use GitHub Actions workflow at `.github/workflows/ci.yml`. It runs your integration tests automatically on every push to `main` and on pull requests.
|
||||
Generátor kostry vytvoří připravený k použití workflow GitHub Actions v `.github/workflows/ci.yml`. Automaticky spouští integrační testy při každém pushi do `main` a u pull requestů.
|
||||
|
||||
The workflow:
|
||||
Workflow:
|
||||
|
||||
1. Checks out your code
|
||||
2. Spins up a temporary Twenty server using the `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` action
|
||||
3. Installs dependencies with `yarn install --immutable`
|
||||
4. Runs `yarn test` with `TWENTY_API_URL` and `TWENTY_API_KEY` injected from the action outputs
|
||||
1. Načte váš kód (checkout).
|
||||
2. Spustí dočasný server Twenty pomocí akce `twentyhq/twenty/.github/actions/spawn-twenty-docker-image`
|
||||
3. Nainstaluje závislosti pomocí `yarn install --immutable`
|
||||
4. Spustí `yarn test` s proměnnými `TWENTY_API_URL` a `TWENTY_API_KEY` vloženými z výstupů akce
|
||||
|
||||
```yaml .github/workflows/ci.yml
|
||||
name: CI
|
||||
@@ -369,21 +369,21 @@ jobs:
|
||||
TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
|
||||
```
|
||||
|
||||
You don't need to configure any secrets — the `spawn-twenty-docker-image` action starts an ephemeral Twenty server directly in the runner and outputs the connection details. The `GITHUB_TOKEN` secret is provided automatically by GitHub.
|
||||
Není potřeba konfigurovat žádné secrets — akce `spawn-twenty-docker-image` spustí efemérní server Twenty přímo v runneru a vypíše podrobnosti připojení. Secret `GITHUB_TOKEN` je poskytován GitHubem automaticky.
|
||||
|
||||
To pin a specific Twenty version instead of `latest`, change the `TWENTY_VERSION` environment variable at the top of the workflow.
|
||||
Chcete-li připnout konkrétní verzi Twenty místo `latest`, změňte proměnnou prostředí `TWENTY_VERSION` na začátku workflow.
|
||||
|
||||
## Ruční nastavení (bez scaffolderu)
|
||||
|
||||
If you prefer to set things up yourself instead of using `create-twenty-app`, you can do it in two steps.
|
||||
Pokud dáváte přednost vlastnímu nastavení místo použití `create-twenty-app`, můžete to udělat ve dvou krocích.
|
||||
|
||||
**1. Add `twenty-sdk` and `twenty-client-sdk` as dependencies:**
|
||||
**1. Přidejte `twenty-sdk` a `twenty-client-sdk` jako závislosti:**
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn add twenty-sdk twenty-client-sdk
|
||||
```
|
||||
|
||||
**2. Add a `twenty` script to your `package.json`:**
|
||||
**2. Přidejte skript `twenty` do svého `package.json`:**
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -393,19 +393,19 @@ yarn add twenty-sdk twenty-client-sdk
|
||||
}
|
||||
```
|
||||
|
||||
You can now run `yarn twenty dev`, `yarn twenty help`, and all other commands.
|
||||
Nyní můžete spouštět `yarn twenty dev`, `yarn twenty help` a všechny ostatní příkazy.
|
||||
|
||||
<Note>
|
||||
Do not install `twenty-sdk` globally. Always use it as a local project dependency so that each project can pin its own version.
|
||||
Neinstalujte `twenty-sdk` globálně. Vždy jej používejte jako lokální závislost projektu, aby si každý projekt mohl připnout svou vlastní verzi.
|
||||
</Note>
|
||||
|
||||
## Řešení potíží
|
||||
|
||||
If you run into issues:
|
||||
Pokud narazíte na potíže:
|
||||
|
||||
* Make sure **Docker is running** before starting the scaffolder with a local instance.
|
||||
* Make sure you are using **Node.js 24+** (`node -v` to check).
|
||||
* Make sure **Corepack is enabled** (`corepack enable`) so Yarn 4 is available.
|
||||
* Try deleting `node_modules` and running `yarn install` again if dependencies seem broken.
|
||||
* Před spuštěním generátoru kostry s lokální instancí se ujistěte, že **Docker běží**.
|
||||
* Ujistěte se, že používáte **Node.js 24+** (ověříte příkazem `node -v`).
|
||||
* Ujistěte se, že je **Corepack povolen** (`corepack enable`), aby byl k dispozici Yarn 4.
|
||||
* Zkuste smazat `node_modules` a znovu spustit `yarn install`, pokud se zdají závislosti poškozené.
|
||||
|
||||
Still stuck? Ask for help on the [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).
|
||||
Pořád se nedaří? Požádejte o pomoc na [Discordu Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).
|
||||
|
||||
@@ -18,13 +18,13 @@ Obě cesty začínají stejným krokem **build**.
|
||||
|
||||
## Sestavení vaší aplikace
|
||||
|
||||
Run the build command to compile your app and generate a distribution-ready `manifest.json`:
|
||||
Spusťte příkaz build ke zkompilování své aplikace a k vygenerování souboru `manifest.json` připraveného k distribuci:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty build
|
||||
```
|
||||
|
||||
This compiles TypeScript sources, transpiles logic functions and front components, and writes everything to `.twenty/output/`. Add `--tarball` to also produce a `.tgz` package for manual distribution or the deploy command.
|
||||
Tím se zkompilují zdrojové soubory TypeScriptu, transpilují logické funkce a frontendové komponenty a vše se zapíše do `.twenty/output/`. Přidejte `--tarball`, abyste také vytvořili balíček `.tgz` pro ruční distribuci nebo příkaz deploy.
|
||||
|
||||
## Nasazení na server (tarball)
|
||||
|
||||
@@ -61,7 +61,7 @@ Aplikace ve formě tarball nejsou uvedeny ve veřejném tržišti, takže je ost
|
||||
Odkaz ke sdílení používá základní adresu URL serveru (bez jakékoli subdomény pracovního prostoru), takže funguje pro libovolný pracovní prostor na serveru.
|
||||
|
||||
<Warning>
|
||||
Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > Enterprise](/settings/admin-panel#enterprise) to enable it.
|
||||
Sdílení soukromých aplikací je funkce Enterprise. Přejděte do [Nastavení > Admin Panel > Enterprise](/settings/admin-panel#enterprise) a povolte ji.
|
||||
</Warning>
|
||||
|
||||
### Správa verzí
|
||||
@@ -69,7 +69,7 @@ Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > E
|
||||
Chcete-li vydat aktualizaci:
|
||||
|
||||
1. Zvyšte hodnotu pole `version` v souboru `package.json`
|
||||
2. Run `yarn twenty deploy` (or `yarn twenty deploy --remote production`)
|
||||
2. Spusťte `yarn twenty deploy` (nebo `yarn twenty deploy --remote production`)
|
||||
3. Pracovní prostory, které mají aplikaci nainstalovanou, uvidí dostupnou aktualizaci ve svém nastavení
|
||||
|
||||
{/* TODO: add screenshot of the Upgrade button */}
|
||||
@@ -81,7 +81,7 @@ Publikování na npm zajistí, že bude vaše aplikace dohledatelná v Marketpla
|
||||
### Požadavky
|
||||
|
||||
* Účet na [npm](https://www.npmjs.com)
|
||||
* The `twenty-app` keyword in your `package.json` `keywords` array (already included when you scaffold with `create-twenty-app`)
|
||||
* Klíčové slovo `twenty-app` ve vašem poli `keywords` v souboru `package.json` (již je zahrnuto, když založíte projekt pomocí `create-twenty-app`)
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -93,7 +93,7 @@ Publikování na npm zajistí, že bude vaše aplikace dohledatelná v Marketpla
|
||||
|
||||
### Metadata tržiště
|
||||
|
||||
The `defineApplication()` config supports optional fields that control how your app appears in the marketplace. Use `logoUrl` and `screenshots` to reference images from the `public/` folder:
|
||||
Konfigurace `defineApplication()` podporuje volitelná pole, která určují, jak se vaše aplikace zobrazuje v tržišti. Použijte `logoUrl` a `screenshots` k odkazování na obrázky ze složky `public/`:
|
||||
|
||||
```ts src/application-config.ts
|
||||
export default defineApplication({
|
||||
@@ -109,9 +109,9 @@ export default defineApplication({
|
||||
});
|
||||
```
|
||||
|
||||
See the [defineApplication accordion](/l/cs/developers/extend/apps/building#defineentity-functions) in the Building Apps page for the full list of marketplace fields (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
|
||||
Podívejte se na [sekci defineApplication](/l/cs/developers/extend/apps/building#defineentity-functions) na stránce Building Apps pro úplný seznam polí tržiště (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl` atd.).
|
||||
|
||||
### Publish
|
||||
### Publikování
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty publish
|
||||
@@ -127,7 +127,7 @@ yarn twenty publish --tag beta
|
||||
|
||||
Server Twenty synchronizuje svůj katalog tržiště z registru npm **každou hodinu**.
|
||||
|
||||
You can trigger the sync immediately instead of waiting:
|
||||
Synchronizaci můžete spustit okamžitě místo čekání:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty catalog-sync
|
||||
@@ -135,7 +135,7 @@ yarn twenty catalog-sync
|
||||
# yarn twenty catalog-sync --remote production
|
||||
```
|
||||
|
||||
The metadata shown in the marketplace comes from your `defineApplication()` config — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
|
||||
Metadata zobrazená v tržišti pocházejí z vaší konfigurace `defineApplication()` — z polí jako `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl` a `termsUrl`.
|
||||
|
||||
<Note>
|
||||
Pokud vaše aplikace nedefinuje `aboutDescription` v `defineApplication()`, tržiště automaticky použije soubor `README.md` vašeho balíčku z npm jako obsah stránky O aplikaci. To znamená, že můžete spravovat jediný soubor README jak pro npm, tak pro tržiště Twenty. Pokud chcete v tržišti jiný popis, explicitně nastavte `aboutDescription`.
|
||||
@@ -143,7 +143,7 @@ Pokud vaše aplikace nedefinuje `aboutDescription` v `defineApplication()`, trž
|
||||
|
||||
### Publikování pomocí CI
|
||||
|
||||
Use this GitHub Actions workflow to publish automatically on every release (uses [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
Použijte tento pracovní postup GitHub Actions k automatickému publikování při každém vydání (používá [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
|
||||
```yaml filename=".github/workflows/publish.yml"
|
||||
name: Publish
|
||||
@@ -178,13 +178,13 @@ Pro jiné systémy CI (GitLab CI, CircleCI atd.) platí stejné tři příkazy:
|
||||
|
||||
## Instalace aplikací
|
||||
|
||||
Once an app is published (npm) or deployed (tarball), workspaces can install it through the UI.
|
||||
Jakmile je aplikace publikována (npm) nebo nasazena (tarball), mohou ji pracovní prostory nainstalovat prostřednictvím uživatelského rozhraní.
|
||||
|
||||
Go to the **Settings > Applications** page in Twenty, where both marketplace and tarball-deployed apps can be browsed and installed.
|
||||
Přejděte na stránku **Nastavení > Aplikace** v Twenty, kde lze procházet a instalovat jak aplikace z tržiště, tak aplikace nasazené jako tarball.
|
||||
|
||||
{/* TODO: add screenshot of the UI when the app is registered */}
|
||||
|
||||
You can also install apps from the command line:
|
||||
Aplikace můžete nainstalovat také z příkazového řádku:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty install
|
||||
|
||||
@@ -4,22 +4,22 @@ description: Vytvářejte a spravujte přizpůsobení Twenty jako kód.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha. The feature works but is still evolving.
|
||||
Aplikace jsou aktuálně v alfa fázi. Funkce funguje, ale stále se vyvíjí.
|
||||
</Warning>
|
||||
|
||||
## What are apps?
|
||||
## Co jsou aplikace?
|
||||
|
||||
Apps let you extend Twenty with custom objects, fields, logic functions, front components, AI skills, and more — all managed as code. Instead of configuring everything through the UI, you define your data model and logic in TypeScript and deploy it to one or more workspaces.
|
||||
Aplikace vám umožňují rozšířit Twenty o vlastní objekty, pole, logické funkce, front-endové komponenty, AI schopnosti a další — vše je spravováno jako kód. Místo konfigurace všeho přes uživatelské rozhraní definujete v TypeScriptu svůj datový model a logiku a nasadíte je do jednoho nebo více pracovních prostorů.
|
||||
|
||||
**Co můžete vytvořit:**
|
||||
|
||||
* **Custom objects and fields** — extend your data model with new entities or add fields to existing objects like Company or Person
|
||||
* **Logic functions** — server-side functions triggered by database events, cron schedules, or HTTP routes
|
||||
* **Front components** — React components that render inside Twenty's UI (record pages, command menu, side panels)
|
||||
* **AI skills and agents** — extend Twenty's AI with custom capabilities
|
||||
* **Views and navigation** — preconfigured saved views and sidebar links
|
||||
* **Vlastní objekty a pole** — rozšiřte svůj datový model o nové entity nebo přidejte pole k existujícím objektům, jako jsou Společnost nebo Osoba
|
||||
* **Logické funkce** — serverové funkce spouštěné událostmi v databázi, plány cronu nebo HTTP routami
|
||||
* **Front-endové komponenty** — komponenty Reactu, které se vykreslují v uživatelském rozhraní Twenty (stránky záznamů, příkazová nabídka, postranní panely)
|
||||
* **Dovednosti AI a agenti** — rozšiřte AI v Twenty o vlastní možnosti
|
||||
* **Zobrazení a navigace** — předkonfigurovaná uložená zobrazení a odkazy v postranním panelu
|
||||
|
||||
## Quick start
|
||||
## Rychlý start
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
@@ -27,46 +27,46 @@ cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
This scaffolds a new app, optionally starts a local Twenty server, and begins watching your files for changes. See the [Getting Started](/l/cs/developers/extend/apps/getting-started) guide for the full walkthrough.
|
||||
Tímto se vytvoří kostra nové aplikace, volitelně se spustí lokální server Twenty a začne sledovat změny ve vašich souborech. Podrobný postup najdete v průvodci [Začínáme](/l/cs/developers/extend/apps/getting-started).
|
||||
|
||||
## Detailed guides
|
||||
## Podrobné návody
|
||||
|
||||
| Guide | Popis |
|
||||
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Getting Started](/l/cs/developers/extend/apps/getting-started) | Scaffold an app, set up a local server, project structure, CI |
|
||||
| [Building Apps](/l/cs/developers/extend/apps/building) | Entity definitions (`defineObject`, `defineLogicFunction`, `defineFrontComponent`, etc.), API clients, npm packages, public assets, testing |
|
||||
| [Publishing](/l/cs/developers/extend/apps/publishing) | Deploy to a server, publish to npm, marketplace |
|
||||
| Průvodce | Popis |
|
||||
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Začínáme](/l/cs/developers/extend/apps/getting-started) | Vytvoření kostry aplikace, nastavení lokálního serveru, struktura projektu, CI |
|
||||
| [Tvorba aplikací](/l/cs/developers/extend/apps/building) | Definice entit (`defineObject`, `defineLogicFunction`, `defineFrontComponent` atd.), klienti API, balíčky npm, veřejná aktiva, testování |
|
||||
| [Publikování](/l/cs/developers/extend/apps/publishing) | Nasazení na server, publikování na npm, tržiště |
|
||||
|
||||
## Key concepts
|
||||
## Klíčové pojmy
|
||||
|
||||
### Detekce entit
|
||||
|
||||
The SDK detects entities by scanning your TypeScript files for `export default define<Entity>({...})` calls. File naming and folder structure are flexible — detection is AST-based, not path-based.
|
||||
SDK detekuje entity prohledáváním vašich souborů TypeScript a hledá volání `export default define<Entity>({...})`. Pojmenování souborů a struktura složek jsou flexibilní — detekce je založená na AST, nikoli na cestách.
|
||||
|
||||
### Available entity types
|
||||
### Dostupné typy entit
|
||||
|
||||
| Funkce | Účel |
|
||||
| ---------------------------------- | -------------------------------------------- |
|
||||
| `defineApplication()` | Application metadata (required, one per app) |
|
||||
| `defineObject()` | Custom objects with fields |
|
||||
| `defineField()` | Fields on existing objects |
|
||||
| `defineLogicFunction()` | Server-side logic with triggers |
|
||||
| `defineFrontComponent()` | React components in Twenty's UI |
|
||||
| `defineRole()` | Permission roles |
|
||||
| `defineView()` | Saved view configurations |
|
||||
| `defineNavigationMenuItem()` | Sidebar navigation links |
|
||||
| `defineSkill()` | AI agent skills |
|
||||
| `defineAgent()` | AI agents with prompts |
|
||||
| `definePageLayout()` | Custom record page layouts |
|
||||
| `definePreInstallLogicFunction()` | Runs before app installation |
|
||||
| `definePostInstallLogicFunction()` | Runs after app installation |
|
||||
| Funkce | Účel |
|
||||
| ---------------------------------- | ------------------------------------------------ |
|
||||
| `defineApplication()` | Metadata aplikace (povinné, jedno na aplikaci) |
|
||||
| `defineObject()` | Vlastní objekty s poli |
|
||||
| `defineField()` | Pole u existujících objektů |
|
||||
| `defineLogicFunction()` | Serverová logika se spouštěči |
|
||||
| `defineFrontComponent()` | Komponenty Reactu v uživatelském rozhraní Twenty |
|
||||
| `defineRole()` | Role oprávnění |
|
||||
| `defineView()` | Konfigurace uložených zobrazení |
|
||||
| `defineNavigationMenuItem()` | Odkazy postranní navigace |
|
||||
| `defineSkill()` | Dovednosti agenta AI |
|
||||
| `defineAgent()` | AI agenti s prompty |
|
||||
| `definePageLayout()` | Vlastní rozvržení stránek záznamu |
|
||||
| `definePreInstallLogicFunction()` | Spouští se před instalací aplikace |
|
||||
| `definePostInstallLogicFunction()` | Spouští se po instalaci aplikace |
|
||||
|
||||
### Development workflow
|
||||
### Vývojový postup
|
||||
|
||||
1. **`yarn twenty dev`** — watches source files, rebuilds on change, syncs to the server, generates typed API clients
|
||||
2. **`yarn twenty build`** — produces a distributable build
|
||||
3. **`yarn twenty deploy`** — deploys to a remote Twenty server
|
||||
4. **`yarn twenty add`** — scaffolds a new entity interactively
|
||||
1. **`yarn twenty dev`** — sleduje zdrojové soubory, při změně znovu sestaví, synchronizuje se serverem a generuje typované klienty API
|
||||
2. **`yarn twenty build`** — vytvoří distribuovatelný build
|
||||
3. **`yarn twenty deploy`** — nasadí na vzdálený server Twenty
|
||||
4. **`yarn twenty add`** — interaktivně vytvoří kostru nové entity
|
||||
|
||||
### Referenční dokumentace CLI
|
||||
|
||||
@@ -78,4 +78,4 @@ yarn twenty exec -n fn # Execute a logic function
|
||||
yarn twenty logs -n fn # Stream function logs
|
||||
```
|
||||
|
||||
See the [Getting Started](/l/cs/developers/extend/apps/getting-started) guide for the full CLI reference.
|
||||
Úplný přehled příkazů CLI najdete v průvodci [Začínáme](/l/cs/developers/extend/apps/getting-started).
|
||||
|
||||
@@ -18,13 +18,13 @@ Beide Pfade beginnen mit demselben **Build**-Schritt.
|
||||
|
||||
## Erstellen Ihrer App
|
||||
|
||||
Run the build command to compile your app and generate a distribution-ready `manifest.json`:
|
||||
Führen Sie den Build-Befehl aus, um Ihre App zu kompilieren und eine distributionsfertige `manifest.json` zu erzeugen:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty build
|
||||
```
|
||||
|
||||
This compiles TypeScript sources, transpiles logic functions and front components, and writes everything to `.twenty/output/`. Add `--tarball` to also produce a `.tgz` package for manual distribution or the deploy command.
|
||||
Dabei werden TypeScript-Quelltexte kompiliert, Logikfunktionen und Frontend-Komponenten transpiliert und alles in `.twenty/output/` geschrieben. Fügen Sie `--tarball` hinzu, um zusätzlich ein `.tgz`-Paket für die manuelle Verteilung oder den Deploy-Befehl zu erzeugen.
|
||||
|
||||
## Bereitstellung auf einem Server (Tarball)
|
||||
|
||||
@@ -61,7 +61,7 @@ Tarball-Apps werden nicht im öffentlichen Marktplatz gelistet, daher entdecken
|
||||
Der Freigabelink verwendet die Basis-URL des Servers (ohne Workspace-Subdomain), sodass er für jeden Arbeitsbereich auf dem Server funktioniert.
|
||||
|
||||
<Warning>
|
||||
Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > Enterprise](/settings/admin-panel#enterprise) to enable it.
|
||||
Das Teilen privater Apps ist eine Enterprise-Funktion. Gehen Sie zu [Einstellungen > Admin-Panel > Enterprise](/settings/admin-panel#enterprise), um es zu aktivieren.
|
||||
</Warning>
|
||||
|
||||
### Versionsverwaltung
|
||||
@@ -69,7 +69,7 @@ Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > E
|
||||
So veröffentlichen Sie ein Update:
|
||||
|
||||
1. Erhöhen Sie das Feld `version` in Ihrer `package.json`
|
||||
2. Run `yarn twenty deploy` (or `yarn twenty deploy --remote production`)
|
||||
2. Führen Sie `yarn twenty deploy` aus (oder `yarn twenty deploy --remote production`)
|
||||
3. Arbeitsbereiche, die die App installiert haben, sehen in ihren Einstellungen, dass ein Upgrade verfügbar ist.
|
||||
|
||||
{/* TODO: add screenshot of the Upgrade button */}
|
||||
@@ -81,7 +81,7 @@ Die Veröffentlichung auf npm macht Ihre App im Twenty-Marktplatz auffindbar. Je
|
||||
### Anforderungen
|
||||
|
||||
* Ein [npm](https://www.npmjs.com)-Konto
|
||||
* The `twenty-app` keyword in your `package.json` `keywords` array (already included when you scaffold with `create-twenty-app`)
|
||||
* Das Schlüsselwort `twenty-app` in Ihrem `package.json`-Array `keywords` (bereits enthalten, wenn Sie mit `create-twenty-app` ein Gerüst erstellen)
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -93,7 +93,7 @@ Die Veröffentlichung auf npm macht Ihre App im Twenty-Marktplatz auffindbar. Je
|
||||
|
||||
### Marktplatz-Metadaten
|
||||
|
||||
The `defineApplication()` config supports optional fields that control how your app appears in the marketplace. Use `logoUrl` and `screenshots` to reference images from the `public/` folder:
|
||||
Die `defineApplication()`-Konfiguration unterstützt optionale Felder, die steuern, wie Ihre App im Marktplatz erscheint. Verwenden Sie `logoUrl` und `screenshots`, um Bilder aus dem Ordner `public/` zu referenzieren:
|
||||
|
||||
```ts src/application-config.ts
|
||||
export default defineApplication({
|
||||
@@ -109,9 +109,9 @@ export default defineApplication({
|
||||
});
|
||||
```
|
||||
|
||||
See the [defineApplication accordion](/l/de/developers/extend/apps/building#defineentity-functions) in the Building Apps page for the full list of marketplace fields (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
|
||||
Siehe das [defineApplication-Akkordeon](/l/de/developers/extend/apps/building#defineentity-functions) auf der Seite Building Apps für die vollständige Liste der Marktplatzfelder (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl` usw.).
|
||||
|
||||
### Publish
|
||||
### Veröffentlichen
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty publish
|
||||
@@ -125,9 +125,9 @@ yarn twenty publish --tag beta
|
||||
|
||||
### So funktioniert die Marktplatz-Erkennung
|
||||
|
||||
The Twenty server syncs its marketplace catalog from the npm registry **every hour**.
|
||||
Der Twenty-Server synchronisiert seinen Marktplatzkatalog **stündlich** aus der npm-Registry.
|
||||
|
||||
You can trigger the sync immediately instead of waiting:
|
||||
Sie können die Synchronisierung sofort auslösen, anstatt zu warten:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty catalog-sync
|
||||
@@ -135,7 +135,7 @@ yarn twenty catalog-sync
|
||||
# yarn twenty catalog-sync --remote production
|
||||
```
|
||||
|
||||
The metadata shown in the marketplace comes from your `defineApplication()` config — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
|
||||
Die im Marktplatz angezeigten Metadaten stammen aus Ihrer `defineApplication()`-Konfiguration — Felder wie `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl` und `termsUrl`.
|
||||
|
||||
<Note>
|
||||
Wenn deine App keine `aboutDescription` in `defineApplication()` definiert, verwendet der Marktplatz automatisch die `README.md` deines Pakets von npm als Inhalt der Über-uns-Seite. Das bedeutet, dass du eine einzige README sowohl für npm als auch für den Twenty-Marktplatz pflegen kannst. Wenn du im Marktplatz eine andere Beschreibung möchtest, setze `aboutDescription` explizit.
|
||||
@@ -143,7 +143,7 @@ Wenn deine App keine `aboutDescription` in `defineApplication()` definiert, verw
|
||||
|
||||
### CI-Veröffentlichung
|
||||
|
||||
Use this GitHub Actions workflow to publish automatically on every release (uses [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
Verwenden Sie diesen GitHub-Actions-Workflow, um bei jedem Release automatisch zu veröffentlichen (verwendet [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
|
||||
```yaml filename=".github/workflows/publish.yml"
|
||||
name: Publish
|
||||
@@ -178,13 +178,13 @@ Für andere CI-Systeme (GitLab CI, CircleCI usw.) gelten die gleichen drei Befeh
|
||||
|
||||
## Apps installieren
|
||||
|
||||
Once an app is published (npm) or deployed (tarball), workspaces can install it through the UI.
|
||||
Sobald eine App veröffentlicht (npm) oder bereitgestellt (Tarball) wurde, können Arbeitsbereiche sie über die Benutzeroberfläche installieren.
|
||||
|
||||
Go to the **Settings > Applications** page in Twenty, where both marketplace and tarball-deployed apps can be browsed and installed.
|
||||
Gehen Sie zur Seite **Einstellungen > Anwendungen** in Twenty, auf der sowohl Marktplatz- als auch per Tarball bereitgestellte Apps durchsucht und installiert werden können.
|
||||
|
||||
{/* TODO: add screenshot of the UI when the app is registered */}
|
||||
|
||||
You can also install apps from the command line:
|
||||
Sie können Apps auch über die Befehlszeile installieren:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty install
|
||||
|
||||
@@ -4,22 +4,22 @@ description: Twenty-Anpassungen als Code erstellen und verwalten.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha. The feature works but is still evolving.
|
||||
Apps befinden sich derzeit in der Alpha-Phase. Die Funktion ist funktionsfähig, entwickelt sich jedoch noch weiter.
|
||||
</Warning>
|
||||
|
||||
## What are apps?
|
||||
## Was sind Apps?
|
||||
|
||||
Apps let you extend Twenty with custom objects, fields, logic functions, front components, AI skills, and more — all managed as code. Instead of configuring everything through the UI, you define your data model and logic in TypeScript and deploy it to one or more workspaces.
|
||||
Apps ermöglichen es Ihnen, Twenty mit benutzerdefinierten Objekten, Feldern, Logikfunktionen, Frontend-Komponenten, KI-Fähigkeiten und mehr zu erweitern — alles als Code verwaltet. Anstatt alles über die UI zu konfigurieren, definieren Sie Ihr Datenmodell und Ihre Logik in TypeScript und stellen es in einem oder mehreren Workspaces bereit.
|
||||
|
||||
**Was Sie erstellen können:**
|
||||
|
||||
* **Custom objects and fields** — extend your data model with new entities or add fields to existing objects like Company or Person
|
||||
* **Logic functions** — server-side functions triggered by database events, cron schedules, or HTTP routes
|
||||
* **Front components** — React components that render inside Twenty's UI (record pages, command menu, side panels)
|
||||
* **AI skills and agents** — extend Twenty's AI with custom capabilities
|
||||
* **Views and navigation** — preconfigured saved views and sidebar links
|
||||
* **Benutzerdefinierte Objekte und Felder** — erweitern Sie Ihr Datenmodell mit neuen Entitäten oder fügen Sie bestehenden Objekten wie Company oder Person Felder hinzu
|
||||
* **Logikfunktionen** — serverseitige Funktionen, die durch Datenbankereignisse, Cron-Zeitpläne oder HTTP-Routen ausgelöst werden
|
||||
* **Frontend-Komponenten** — React-Komponenten, die innerhalb der UI von Twenty gerendert werden (Datensatzseiten, Befehlsmenü, Seitenpanels)
|
||||
* **KI-Fähigkeiten und -Agenten** — erweitern Sie die KI von Twenty mit benutzerdefinierten Fähigkeiten
|
||||
* **Ansichten und Navigation** — vorkonfigurierte gespeicherte Ansichten und Seitenleistenlinks
|
||||
|
||||
## Quick start
|
||||
## Schnellstart
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
@@ -27,55 +27,55 @@ cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
This scaffolds a new app, optionally starts a local Twenty server, and begins watching your files for changes. See the [Getting Started](/l/de/developers/extend/apps/getting-started) guide for the full walkthrough.
|
||||
Dies erstellt das Grundgerüst für eine neue App, startet optional einen lokalen Twenty-Server und beginnt, Ihre Dateien auf Änderungen zu überwachen. Den vollständigen Ablauf finden Sie im Leitfaden [Erste Schritte](/l/de/developers/extend/apps/getting-started).
|
||||
|
||||
## Detailed guides
|
||||
## Detaillierte Anleitungen
|
||||
|
||||
| Guide | Beschreibung |
|
||||
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Getting Started](/l/de/developers/extend/apps/getting-started) | Scaffold an app, set up a local server, project structure, CI |
|
||||
| [Building Apps](/l/de/developers/extend/apps/building) | Entity definitions (`defineObject`, `defineLogicFunction`, `defineFrontComponent`, etc.), API clients, npm packages, public assets, testing |
|
||||
| [Publishing](/l/de/developers/extend/apps/publishing) | Deploy to a server, publish to npm, marketplace |
|
||||
| Leitfaden | Beschreibung |
|
||||
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Erste Schritte](/l/de/developers/extend/apps/getting-started) | App-Gerüst erstellen, lokalen Server einrichten, Projektstruktur, CI |
|
||||
| [Apps entwickeln](/l/de/developers/extend/apps/building) | Entitätsdefinitionen (`defineObject`, `defineLogicFunction`, `defineFrontComponent` usw.), API-Clients, npm-Pakete, öffentliche Assets, Tests |
|
||||
| [Veröffentlichen](/l/de/developers/extend/apps/publishing) | Auf einem Server bereitstellen, auf npm veröffentlichen, Marktplatz |
|
||||
|
||||
## Key concepts
|
||||
## Wichtige Konzepte
|
||||
|
||||
### Entitätserkennung
|
||||
|
||||
The SDK detects entities by scanning your TypeScript files for `export default define<Entity>({...})` calls. File naming and folder structure are flexible — detection is AST-based, not path-based.
|
||||
Das SDK erkennt Entitäten, indem es Ihre TypeScript-Dateien nach Aufrufen von `export default define<Entity>({...})` scannt. Dateibenennung und Ordnerstruktur sind flexibel — die Erkennung ist AST-basiert, nicht pfadbasiert.
|
||||
|
||||
### Available entity types
|
||||
### Verfügbare Entitätstypen
|
||||
|
||||
| Funktion | Zweck |
|
||||
| ---------------------------------- | -------------------------------------------- |
|
||||
| `defineApplication()` | Application metadata (required, one per app) |
|
||||
| `defineObject()` | Custom objects with fields |
|
||||
| `defineField()` | Fields on existing objects |
|
||||
| `defineLogicFunction()` | Server-side logic with triggers |
|
||||
| `defineFrontComponent()` | React components in Twenty's UI |
|
||||
| `defineRole()` | Permission roles |
|
||||
| `defineView()` | Saved view configurations |
|
||||
| `defineNavigationMenuItem()` | Sidebar navigation links |
|
||||
| `defineSkill()` | AI agent skills |
|
||||
| `defineAgent()` | AI agents with prompts |
|
||||
| `definePageLayout()` | Custom record page layouts |
|
||||
| `definePreInstallLogicFunction()` | Runs before app installation |
|
||||
| `definePostInstallLogicFunction()` | Runs after app installation |
|
||||
| Funktion | Zweck |
|
||||
| ---------------------------------- | ------------------------------------------------ |
|
||||
| `defineApplication()` | Anwendungsmetadaten (erforderlich, eine pro App) |
|
||||
| `defineObject()` | Benutzerdefinierte Objekte mit Feldern |
|
||||
| `defineField()` | Felder bei bestehenden Objekten |
|
||||
| `defineLogicFunction()` | Serverseitige Logik mit Triggern |
|
||||
| `defineFrontComponent()` | React-Komponenten in der UI von Twenty |
|
||||
| `defineRole()` | Berechtigungsrollen |
|
||||
| `defineView()` | Konfigurationen gespeicherter Ansichten |
|
||||
| `defineNavigationMenuItem()` | Navigationslinks in der Seitenleiste |
|
||||
| `defineSkill()` | Fähigkeiten von KI-Agenten |
|
||||
| `defineAgent()` | KI-Agenten mit Prompts |
|
||||
| `definePageLayout()` | Benutzerdefinierte Layouts für Datensatzseiten |
|
||||
| `definePreInstallLogicFunction()` | Wird vor der App-Installation ausgeführt |
|
||||
| `definePostInstallLogicFunction()` | Wird nach der App-Installation ausgeführt |
|
||||
|
||||
### Development workflow
|
||||
### Entwicklungs-Workflow
|
||||
|
||||
1. **`yarn twenty dev`** — watches source files, rebuilds on change, syncs to the server, generates typed API clients
|
||||
2. **`yarn twenty build`** — produces a distributable build
|
||||
3. **`yarn twenty deploy`** — deploys to a remote Twenty server
|
||||
4. **`yarn twenty add`** — scaffolds a new entity interactively
|
||||
1. **`yarn twenty dev`** — überwacht Quelldateien, baut bei Änderungen neu, synchronisiert mit dem Server, generiert typisierte API-Clients
|
||||
2. **`yarn twenty build`** — erzeugt ein auslieferbares Build
|
||||
3. **`yarn twenty deploy`** — stellt auf einem entfernten Twenty-Server bereit
|
||||
4. **`yarn twenty add`** — erstellt interaktiv das Gerüst für eine neue Entität
|
||||
|
||||
### CLI-Referenz
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty help # List all commands
|
||||
yarn twenty server start # Start local dev server
|
||||
yarn twenty remote add # Connect to a Twenty server
|
||||
yarn twenty exec -n fn # Execute a logic function
|
||||
yarn twenty logs -n fn # Stream function logs
|
||||
yarn twenty help # Alle Befehle auflisten
|
||||
yarn twenty server start # Lokalen Dev-Server starten
|
||||
yarn twenty remote add # Mit einem Twenty-Server verbinden
|
||||
yarn twenty exec -n fn # Eine Logikfunktion ausführen
|
||||
yarn twenty logs -n fn # Funktionsprotokolle streamen
|
||||
```
|
||||
|
||||
See the [Getting Started](/l/de/developers/extend/apps/getting-started) guide for the full CLI reference.
|
||||
Die vollständige CLI-Referenz finden Sie im Leitfaden [Erste Schritte](/l/de/developers/extend/apps/getting-started).
|
||||
|
||||
@@ -18,13 +18,13 @@ Entrambi i percorsi partono dalla stessa fase di **build**.
|
||||
|
||||
## Compilazione della tua app
|
||||
|
||||
Run the build command to compile your app and generate a distribution-ready `manifest.json`:
|
||||
Esegui il comando di build per compilare la tua app e generare un `manifest.json` pronto per la distribuzione:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty build
|
||||
```
|
||||
|
||||
This compiles TypeScript sources, transpiles logic functions and front components, and writes everything to `.twenty/output/`. Add `--tarball` to also produce a `.tgz` package for manual distribution or the deploy command.
|
||||
Questo compila i sorgenti TypeScript, transpila le funzioni di logica e i componenti front-end e scrive tutto in `.twenty/output/`. Aggiungi `--tarball` per produrre anche un pacchetto `.tgz` per la distribuzione manuale o il comando di deploy.
|
||||
|
||||
## Distribuzione su un server (tarball)
|
||||
|
||||
@@ -61,7 +61,7 @@ Le app in formato tarball non sono elencate nel marketplace pubblico, quindi alt
|
||||
Il link di condivisione utilizza l'URL di base del server (senza alcun sottodominio dello spazio di lavoro) così funziona per qualsiasi spazio di lavoro sul server.
|
||||
|
||||
<Warning>
|
||||
Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > Enterprise](/settings/admin-panel#enterprise) to enable it.
|
||||
La condivisione delle app private è una funzionalità Enterprise. Vai a [Impostazioni > Pannello di amministrazione > Enterprise](/settings/admin-panel#enterprise) per abilitarla.
|
||||
</Warning>
|
||||
|
||||
### Gestione delle versioni
|
||||
@@ -69,7 +69,7 @@ Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > E
|
||||
Per rilasciare un aggiornamento:
|
||||
|
||||
1. Incrementa il campo `version` nel tuo `package.json`
|
||||
2. Run `yarn twenty deploy` (or `yarn twenty deploy --remote production`)
|
||||
2. Esegui `yarn twenty deploy` (oppure `yarn twenty deploy --remote production`)
|
||||
3. Gli spazi di lavoro che hanno l'app installata vedranno l'aggiornamento disponibile nelle proprie impostazioni
|
||||
|
||||
{/* TODO: add screenshot of the Upgrade button */}
|
||||
@@ -81,7 +81,7 @@ La pubblicazione su npm rende la tua app scopribile nel marketplace di Twenty. Q
|
||||
### Requisiti
|
||||
|
||||
* Un account [npm](https://www.npmjs.com)
|
||||
* The `twenty-app` keyword in your `package.json` `keywords` array (already included when you scaffold with `create-twenty-app`)
|
||||
* La parola chiave `twenty-app` nell'array `keywords` del tuo `package.json` (già inclusa quando inizializzi con `create-twenty-app`)
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -93,7 +93,7 @@ La pubblicazione su npm rende la tua app scopribile nel marketplace di Twenty. Q
|
||||
|
||||
### Metadati del marketplace
|
||||
|
||||
The `defineApplication()` config supports optional fields that control how your app appears in the marketplace. Use `logoUrl` and `screenshots` to reference images from the `public/` folder:
|
||||
La configurazione `defineApplication()` supporta campi opzionali che controllano come la tua app appare nel marketplace. Usa `logoUrl` e `screenshots` per fare riferimento alle immagini nella cartella `public/`:
|
||||
|
||||
```ts src/application-config.ts
|
||||
export default defineApplication({
|
||||
@@ -109,9 +109,9 @@ export default defineApplication({
|
||||
});
|
||||
```
|
||||
|
||||
See the [defineApplication accordion](/l/it/developers/extend/apps/building#defineentity-functions) in the Building Apps page for the full list of marketplace fields (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
|
||||
Vedi l'[accordion defineApplication](/l/it/developers/extend/apps/building#defineentity-functions) nella pagina Building Apps per l'elenco completo dei campi del marketplace (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, ecc.).
|
||||
|
||||
### Publish
|
||||
### Pubblica
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty publish
|
||||
@@ -127,7 +127,7 @@ yarn twenty publish --tag beta
|
||||
|
||||
Il server Twenty sincronizza il proprio catalogo del marketplace dal registro npm **ogni ora**.
|
||||
|
||||
You can trigger the sync immediately instead of waiting:
|
||||
Puoi attivare la sincronizzazione immediatamente invece di aspettare:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty catalog-sync
|
||||
@@ -135,7 +135,7 @@ yarn twenty catalog-sync
|
||||
# yarn twenty catalog-sync --remote production
|
||||
```
|
||||
|
||||
The metadata shown in the marketplace comes from your `defineApplication()` config — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
|
||||
I metadati visualizzati nel marketplace provengono dalla configurazione `defineApplication()` — campi come `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl` e `termsUrl`.
|
||||
|
||||
<Note>
|
||||
Se la tua app non definisce un `aboutDescription` in `defineApplication()`, il marketplace userà automaticamente il `README.md` del tuo pacchetto su npm come contenuto della pagina Informazioni. Questo significa che puoi mantenere un unico README sia per npm sia per il marketplace di Twenty. Se desideri una descrizione diversa nel marketplace, imposta esplicitamente `aboutDescription`.
|
||||
@@ -143,7 +143,7 @@ Se la tua app non definisce un `aboutDescription` in `defineApplication()`, il m
|
||||
|
||||
### Pubblicazione con CI
|
||||
|
||||
Use this GitHub Actions workflow to publish automatically on every release (uses [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
Usa questo workflow di GitHub Actions per pubblicare automaticamente a ogni release (usa [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
|
||||
```yaml filename=".github/workflows/publish.yml"
|
||||
name: Publish
|
||||
@@ -178,13 +178,13 @@ Per altri sistemi CI (GitLab CI, CircleCI, ecc.), si applicano gli stessi tre co
|
||||
|
||||
## Installazione delle app
|
||||
|
||||
Once an app is published (npm) or deployed (tarball), workspaces can install it through the UI.
|
||||
Una volta che un'app è stata pubblicata (npm) o distribuita (tarball), gli spazi di lavoro possono installarla tramite l'interfaccia utente.
|
||||
|
||||
Go to the **Settings > Applications** page in Twenty, where both marketplace and tarball-deployed apps can be browsed and installed.
|
||||
Vai alla pagina **Impostazioni > Applicazioni** in Twenty, dove è possibile sfogliare e installare sia le app del marketplace sia quelle distribuite tramite tarball.
|
||||
|
||||
{/* TODO: add screenshot of the UI when the app is registered */}
|
||||
|
||||
You can also install apps from the command line:
|
||||
Puoi anche installare le app dalla riga di comando:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty install
|
||||
|
||||
@@ -4,22 +4,22 @@ description: Crea e gestisci le personalizzazioni di Twenty come codice.
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha. The feature works but is still evolving.
|
||||
Le app sono attualmente in fase alfa. La funzionalità funziona ma è ancora in evoluzione.
|
||||
</Warning>
|
||||
|
||||
## What are apps?
|
||||
## Cosa sono le app?
|
||||
|
||||
Apps let you extend Twenty with custom objects, fields, logic functions, front components, AI skills, and more — all managed as code. Instead of configuring everything through the UI, you define your data model and logic in TypeScript and deploy it to one or more workspaces.
|
||||
Le app ti consentono di estendere Twenty con oggetti, campi, funzioni logiche, componenti front-end, competenze IA e altro ancora — il tutto gestito come codice. Invece di configurare tutto tramite l'interfaccia utente, definisci in TypeScript il modello dati e la logica e li distribuisci in uno o più spazi di lavoro.
|
||||
|
||||
**Cosa puoi creare:**
|
||||
|
||||
* **Custom objects and fields** — extend your data model with new entities or add fields to existing objects like Company or Person
|
||||
* **Logic functions** — server-side functions triggered by database events, cron schedules, or HTTP routes
|
||||
* **Front components** — React components that render inside Twenty's UI (record pages, command menu, side panels)
|
||||
* **AI skills and agents** — extend Twenty's AI with custom capabilities
|
||||
* **Views and navigation** — preconfigured saved views and sidebar links
|
||||
* **Oggetti e campi personalizzati** — estendi il tuo modello dati con nuove entità o aggiungi campi a oggetti esistenti come Company o Person
|
||||
* **Funzioni logiche** — funzioni lato server attivate da eventi del database, pianificazioni cron o route HTTP
|
||||
* **Componenti front-end** — componenti React che vengono renderizzati nell'interfaccia utente di Twenty (pagine dei record, menu dei comandi, pannelli laterali)
|
||||
* **Competenze e agenti IA** — estendi l'IA di Twenty con funzionalità personalizzate
|
||||
* **Viste e navigazione** — viste salvate preconfigurate e link nella barra laterale
|
||||
|
||||
## Quick start
|
||||
## Avvio rapido
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
@@ -27,46 +27,46 @@ cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
This scaffolds a new app, optionally starts a local Twenty server, and begins watching your files for changes. See the [Getting Started](/l/it/developers/extend/apps/getting-started) guide for the full walkthrough.
|
||||
Questo genera lo scheletro di una nuova app, avvia facoltativamente un server Twenty locale e inizia a monitorare i tuoi file per le modifiche. Consulta la [Guida introduttiva](/l/it/developers/extend/apps/getting-started) per l'intera procedura.
|
||||
|
||||
## Detailed guides
|
||||
## Guide dettagliate
|
||||
|
||||
| Guide | Descrizione |
|
||||
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Getting Started](/l/it/developers/extend/apps/getting-started) | Scaffold an app, set up a local server, project structure, CI |
|
||||
| [Building Apps](/l/it/developers/extend/apps/building) | Entity definitions (`defineObject`, `defineLogicFunction`, `defineFrontComponent`, etc.), API clients, npm packages, public assets, testing |
|
||||
| [Publishing](/l/it/developers/extend/apps/publishing) | Deploy to a server, publish to npm, marketplace |
|
||||
| Guide | Descrizione |
|
||||
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Guida introduttiva](/l/it/developers/extend/apps/getting-started) | Crea lo scheletro di un'app, configura un server locale, struttura del progetto, CI |
|
||||
| [Creare app](/l/it/developers/extend/apps/building) | Definizioni di entità (`defineObject`, `defineLogicFunction`, `defineFrontComponent`, ecc.), client API, pacchetti npm, asset pubblici, test |
|
||||
| [Pubblicazione](/l/it/developers/extend/apps/publishing) | Distribuisci su un server, pubblica su npm, marketplace |
|
||||
|
||||
## Key concepts
|
||||
## Concetti chiave
|
||||
|
||||
### Rilevamento delle entità
|
||||
|
||||
The SDK detects entities by scanning your TypeScript files for `export default define<Entity>({...})` calls. File naming and folder structure are flexible — detection is AST-based, not path-based.
|
||||
L'SDK rileva le entità scansionando i tuoi file TypeScript alla ricerca di chiamate a `export default define<Entity>({...})`. La denominazione dei file e la struttura delle cartelle sono flessibili — il rilevamento è basato sull'AST, non sui percorsi.
|
||||
|
||||
### Available entity types
|
||||
### Tipi di entità disponibili
|
||||
|
||||
| Funzione | Scopo |
|
||||
| ---------------------------------- | -------------------------------------------- |
|
||||
| `defineApplication()` | Application metadata (required, one per app) |
|
||||
| `defineObject()` | Custom objects with fields |
|
||||
| `defineField()` | Fields on existing objects |
|
||||
| `defineLogicFunction()` | Server-side logic with triggers |
|
||||
| `defineFrontComponent()` | React components in Twenty's UI |
|
||||
| `defineRole()` | Permission roles |
|
||||
| `defineView()` | Saved view configurations |
|
||||
| `defineNavigationMenuItem()` | Sidebar navigation links |
|
||||
| `defineSkill()` | AI agent skills |
|
||||
| `defineAgent()` | AI agents with prompts |
|
||||
| `definePageLayout()` | Custom record page layouts |
|
||||
| `definePreInstallLogicFunction()` | Runs before app installation |
|
||||
| `definePostInstallLogicFunction()` | Runs after app installation |
|
||||
| Funzione | Scopo |
|
||||
| ---------------------------------- | ------------------------------------------------------ |
|
||||
| `defineApplication()` | Metadati dell'applicazione (obbligatorio, uno per app) |
|
||||
| `defineObject()` | Oggetti personalizzati con campi |
|
||||
| `defineField()` | Campi su oggetti esistenti |
|
||||
| `defineLogicFunction()` | Logica lato server con trigger |
|
||||
| `defineFrontComponent()` | Componenti React nell'interfaccia utente di Twenty |
|
||||
| `defineRole()` | Ruoli di autorizzazione |
|
||||
| `defineView()` | Configurazioni di viste salvate |
|
||||
| `defineNavigationMenuItem()` | Link di navigazione della barra laterale |
|
||||
| `defineSkill()` | Competenze dell'agente IA |
|
||||
| `defineAgent()` | Agenti IA con prompt |
|
||||
| `definePageLayout()` | Layout personalizzati delle pagine dei record |
|
||||
| `definePreInstallLogicFunction()` | Viene eseguito prima dell'installazione dell'app |
|
||||
| `definePostInstallLogicFunction()` | Viene eseguito dopo l'installazione dell'app |
|
||||
|
||||
### Development workflow
|
||||
### Flusso di lavoro di sviluppo
|
||||
|
||||
1. **`yarn twenty dev`** — watches source files, rebuilds on change, syncs to the server, generates typed API clients
|
||||
2. **`yarn twenty build`** — produces a distributable build
|
||||
3. **`yarn twenty deploy`** — deploys to a remote Twenty server
|
||||
4. **`yarn twenty add`** — scaffolds a new entity interactively
|
||||
1. **`yarn twenty dev`** — osserva i file sorgente, ricompila alle modifiche, sincronizza con il server, genera client API tipizzati
|
||||
2. **`yarn twenty build`** — produce una build distribuibile
|
||||
3. **`yarn twenty deploy`** — distribuisce su un server Twenty remoto
|
||||
4. **`yarn twenty add`** — crea lo scheletro di una nuova entità in modo interattivo
|
||||
|
||||
### Riferimento CLI
|
||||
|
||||
@@ -78,4 +78,4 @@ yarn twenty exec -n fn # Execute a logic function
|
||||
yarn twenty logs -n fn # Stream function logs
|
||||
```
|
||||
|
||||
See the [Getting Started](/l/it/developers/extend/apps/getting-started) guide for the full CLI reference.
|
||||
Consulta la [Guida introduttiva](/l/it/developers/extend/apps/getting-started) per il riferimento completo della CLI.
|
||||
|
||||
@@ -18,13 +18,13 @@ Ambele căi pornesc din aceeași etapă de **build**.
|
||||
|
||||
## Construirea aplicației
|
||||
|
||||
Run the build command to compile your app and generate a distribution-ready `manifest.json`:
|
||||
Rulează comanda `build` pentru a compila aplicația și a genera un `manifest.json` pregătit pentru distribuire:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty build
|
||||
```
|
||||
|
||||
This compiles TypeScript sources, transpiles logic functions and front components, and writes everything to `.twenty/output/`. Add `--tarball` to also produce a `.tgz` package for manual distribution or the deploy command.
|
||||
Aceasta compilează sursele TypeScript, transpilează funcțiile de logică și componentele de front-end și scrie totul în `.twenty/output/`. Adaugă `--tarball` pentru a produce și un pachet `.tgz` pentru distribuire manuală sau pentru comanda de deploy.
|
||||
|
||||
## Implementare pe un server (tarball)
|
||||
|
||||
@@ -61,7 +61,7 @@ Aplicațiile tarball nu sunt listate în marketplace-ul public, astfel încât a
|
||||
Linkul de partajare folosește URL-ul de bază al serverului (fără niciun subdomeniu de spațiu de lucru), astfel încât funcționează pentru orice spațiu de lucru de pe server.
|
||||
|
||||
<Warning>
|
||||
Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > Enterprise](/settings/admin-panel#enterprise) to enable it.
|
||||
Partajarea aplicațiilor private este o funcționalitate Enterprise. Mergi la [Setări > Panou de administrare > Enterprise](/settings/admin-panel#enterprise) pentru a o activa.
|
||||
</Warning>
|
||||
|
||||
### Gestionarea versiunilor
|
||||
@@ -69,7 +69,7 @@ Sharing private apps is an Enterprise feature. Go to [Settings > Admin Panel > E
|
||||
Pentru a lansa o actualizare:
|
||||
|
||||
1. Actualizează câmpul `version` din `package.json`
|
||||
2. Run `yarn twenty deploy` (or `yarn twenty deploy --remote production`)
|
||||
2. Rulează `yarn twenty deploy` (sau `yarn twenty deploy --remote production`)
|
||||
3. Spațiile de lucru care au aplicația instalată vor vedea actualizarea disponibilă în setările lor
|
||||
|
||||
{/* TODO: add screenshot of the Upgrade button */}
|
||||
@@ -81,7 +81,7 @@ Publicarea pe npm face ca aplicația ta să poată fi descoperită în marketpla
|
||||
### Cerințe
|
||||
|
||||
* Un cont [npm](https://www.npmjs.com)
|
||||
* The `twenty-app` keyword in your `package.json` `keywords` array (already included when you scaffold with `create-twenty-app`)
|
||||
* Cuvântul cheie `twenty-app` din array-ul `keywords` al fișierului `package.json` (deja inclus când inițializezi proiectul cu `create-twenty-app`)
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -93,7 +93,7 @@ Publicarea pe npm face ca aplicația ta să poată fi descoperită în marketpla
|
||||
|
||||
### Metadate pentru marketplace
|
||||
|
||||
The `defineApplication()` config supports optional fields that control how your app appears in the marketplace. Use `logoUrl` and `screenshots` to reference images from the `public/` folder:
|
||||
Configurația `defineApplication()` acceptă câmpuri opționale care controlează modul în care aplicația ta apare în marketplace. Folosește `logoUrl` și `screenshots` pentru a face referire la imaginile din folderul `public/`:
|
||||
|
||||
```ts src/application-config.ts
|
||||
export default defineApplication({
|
||||
@@ -109,9 +109,9 @@ export default defineApplication({
|
||||
});
|
||||
```
|
||||
|
||||
See the [defineApplication accordion](/l/ro/developers/extend/apps/building#defineentity-functions) in the Building Apps page for the full list of marketplace fields (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
|
||||
Vezi [acordeonul defineApplication](/l/ro/developers/extend/apps/building#defineentity-functions) din pagina Building Apps pentru lista completă de câmpuri ale marketplace-ului (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
|
||||
|
||||
### Publish
|
||||
### Publicare
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty publish
|
||||
@@ -125,9 +125,9 @@ yarn twenty publish --tag beta
|
||||
|
||||
### Cum funcționează descoperirea în marketplace
|
||||
|
||||
The Twenty server syncs its marketplace catalog from the npm registry **every hour**.
|
||||
Serverul Twenty sincronizează catalogul marketplace-ului din registrul npm **la fiecare oră**.
|
||||
|
||||
You can trigger the sync immediately instead of waiting:
|
||||
Poți declanșa sincronizarea imediat, în loc să aștepți:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty catalog-sync
|
||||
@@ -135,7 +135,7 @@ yarn twenty catalog-sync
|
||||
# yarn twenty catalog-sync --remote production
|
||||
```
|
||||
|
||||
The metadata shown in the marketplace comes from your `defineApplication()` config — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
|
||||
Metadatele afișate în marketplace provin din configurația `defineApplication()` — câmpuri precum `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl` și `termsUrl`.
|
||||
|
||||
<Note>
|
||||
Dacă aplicația ta nu definește un `aboutDescription` în `defineApplication()`, piața va folosi automat fișierul `README.md` al pachetului tău de pe npm drept conținut pentru pagina Despre. Acest lucru înseamnă că poți menține un singur README atât pentru npm, cât și pentru piața Twenty. Dacă vrei o descriere diferită în piață, setează explicit `aboutDescription`.
|
||||
@@ -143,7 +143,7 @@ Dacă aplicația ta nu definește un `aboutDescription` în `defineApplication()
|
||||
|
||||
### Publicare CI
|
||||
|
||||
Use this GitHub Actions workflow to publish automatically on every release (uses [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
Folosește acest workflow GitHub Actions pentru a publica automat la fiecare release (folosește [OIDC](https://docs.npmjs.com/trusted-publishers)):
|
||||
|
||||
```yaml filename=".github/workflows/publish.yml"
|
||||
name: Publish
|
||||
@@ -178,13 +178,13 @@ Pentru alte sisteme CI (GitLab CI, CircleCI etc.), se aplică aceleași trei com
|
||||
|
||||
## Instalarea aplicațiilor
|
||||
|
||||
Once an app is published (npm) or deployed (tarball), workspaces can install it through the UI.
|
||||
După ce o aplicație este publicată (npm) sau implementată (tarball), spațiile de lucru o pot instala prin interfața utilizatorului (UI).
|
||||
|
||||
Go to the **Settings > Applications** page in Twenty, where both marketplace and tarball-deployed apps can be browsed and installed.
|
||||
Mergi la pagina **Setări > Aplicații** din Twenty, unde pot fi parcurse și instalate atât aplicațiile din marketplace, cât și cele implementate prin tarball.
|
||||
|
||||
{/* TODO: add screenshot of the UI when the app is registered */}
|
||||
|
||||
You can also install apps from the command line:
|
||||
Poți instala aplicații și din linia de comandă:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty install
|
||||
|
||||
@@ -4,22 +4,22 @@ description: Construiți și gestionați personalizările Twenty sub formă de c
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha. The feature works but is still evolving.
|
||||
Aplicațiile sunt în prezent în testare alfa. Caracteristica funcționează, dar este încă în dezvoltare.
|
||||
</Warning>
|
||||
|
||||
## What are apps?
|
||||
## Ce sunt aplicațiile?
|
||||
|
||||
Apps let you extend Twenty with custom objects, fields, logic functions, front components, AI skills, and more — all managed as code. Instead of configuring everything through the UI, you define your data model and logic in TypeScript and deploy it to one or more workspaces.
|
||||
Aplicațiile vă permit să extindeți Twenty cu obiecte personalizate, câmpuri, funcții logice, componente front-end, abilități IA și altele — toate gestionate ca cod. În loc să configurați totul prin interfața de utilizator (UI), vă definiți modelul de date și logica în TypeScript și le implementați în unul sau mai multe spații de lucru.
|
||||
|
||||
**Ce puteți construi:**
|
||||
|
||||
* **Custom objects and fields** — extend your data model with new entities or add fields to existing objects like Company or Person
|
||||
* **Logic functions** — server-side functions triggered by database events, cron schedules, or HTTP routes
|
||||
* **Front components** — React components that render inside Twenty's UI (record pages, command menu, side panels)
|
||||
* **AI skills and agents** — extend Twenty's AI with custom capabilities
|
||||
* **Views and navigation** — preconfigured saved views and sidebar links
|
||||
* **Obiecte și câmpuri personalizate** — extindeți modelul de date cu entități noi sau adăugați câmpuri la obiecte existente, precum Companie sau Persoană
|
||||
* **Funcții logice** — funcții pe partea de server declanșate de evenimente ale bazei de date, programări cron sau rute HTTP
|
||||
* **Componente front-end** — componente React care se afișează în interfața Twenty (pagini de înregistrări, meniul de comenzi, panouri laterale)
|
||||
* **Abilități și agenți IA** — extindeți IA din Twenty cu capabilități personalizate
|
||||
* **Vizualizări și navigare** — vizualizări salvate preconfigurate și linkuri în bara laterală
|
||||
|
||||
## Quick start
|
||||
## Pornire rapidă
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
@@ -27,55 +27,55 @@ cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
This scaffolds a new app, optionally starts a local Twenty server, and begins watching your files for changes. See the [Getting Started](/l/ro/developers/extend/apps/getting-started) guide for the full walkthrough.
|
||||
Aceasta creează scheletul unei aplicații noi, pornește opțional un server Twenty local și începe să monitorizeze fișierele pentru modificări. Consultați ghidul [Începeți](/l/ro/developers/extend/apps/getting-started) pentru prezentarea completă.
|
||||
|
||||
## Detailed guides
|
||||
## Ghiduri detaliate
|
||||
|
||||
| Ghid | Descriere |
|
||||
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Getting Started](/l/ro/developers/extend/apps/getting-started) | Scaffold an app, set up a local server, project structure, CI |
|
||||
| [Building Apps](/l/ro/developers/extend/apps/building) | Entity definitions (`defineObject`, `defineLogicFunction`, `defineFrontComponent`, etc.), API clients, npm packages, public assets, testing |
|
||||
| [Publishing](/l/ro/developers/extend/apps/publishing) | Deploy to a server, publish to npm, marketplace |
|
||||
| Ghid | Descriere |
|
||||
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Începeți](/l/ro/developers/extend/apps/getting-started) | Creați scheletul unei aplicații, configurați un server local, structură de proiect, CI |
|
||||
| [Crearea aplicațiilor](/l/ro/developers/extend/apps/building) | Definiții ale entităților (`defineObject`, `defineLogicFunction`, `defineFrontComponent` etc.), clienți API, pachete npm, resurse publice, testare |
|
||||
| [Publicare](/l/ro/developers/extend/apps/publishing) | Implementare pe un server, publicare pe npm, marketplace |
|
||||
|
||||
## Key concepts
|
||||
## Concepte cheie
|
||||
|
||||
### Detectarea entităților
|
||||
|
||||
The SDK detects entities by scanning your TypeScript files for `export default define<Entity>({...})` calls. File naming and folder structure are flexible — detection is AST-based, not path-based.
|
||||
SDK-ul detectează entitățile scanând fișierele TypeScript pentru apeluri `export default define<Entity>({...})`. Denumirea fișierelor și structura folderelor sunt flexibile — detectarea este bazată pe AST, nu pe căi.
|
||||
|
||||
### Available entity types
|
||||
### Tipuri de entități disponibile
|
||||
|
||||
| Funcție | Scop |
|
||||
| ---------------------------------- | -------------------------------------------- |
|
||||
| `defineApplication()` | Application metadata (required, one per app) |
|
||||
| `defineObject()` | Custom objects with fields |
|
||||
| `defineField()` | Fields on existing objects |
|
||||
| `defineLogicFunction()` | Server-side logic with triggers |
|
||||
| `defineFrontComponent()` | React components in Twenty's UI |
|
||||
| `defineRole()` | Permission roles |
|
||||
| `defineView()` | Saved view configurations |
|
||||
| `defineNavigationMenuItem()` | Sidebar navigation links |
|
||||
| `defineSkill()` | AI agent skills |
|
||||
| `defineAgent()` | AI agents with prompts |
|
||||
| `definePageLayout()` | Custom record page layouts |
|
||||
| `definePreInstallLogicFunction()` | Runs before app installation |
|
||||
| `definePostInstallLogicFunction()` | Runs after app installation |
|
||||
| Funcție | Scop |
|
||||
| ---------------------------------- | -------------------------------------------------------- |
|
||||
| `defineApplication()` | Metadate ale aplicației (obligatoriu, una per aplicație) |
|
||||
| `defineObject()` | Obiecte personalizate cu câmpuri |
|
||||
| `defineField()` | Câmpuri pe obiecte existente |
|
||||
| `defineLogicFunction()` | Logică pe partea de server cu declanșatoare |
|
||||
| `defineFrontComponent()` | Componente React în interfața Twenty |
|
||||
| `defineRole()` | Roluri de permisiuni |
|
||||
| `defineView()` | Configurații pentru vizualizări salvate |
|
||||
| `defineNavigationMenuItem()` | Linkuri de navigare în bara laterală |
|
||||
| `defineSkill()` | Abilități ale agentului IA |
|
||||
| `defineAgent()` | Agenți IA cu prompturi |
|
||||
| `definePageLayout()` | Dispuneri personalizate pentru paginile de înregistrare |
|
||||
| `definePreInstallLogicFunction()` | Rulează înainte de instalarea aplicației |
|
||||
| `definePostInstallLogicFunction()` | Rulează după instalarea aplicației |
|
||||
|
||||
### Development workflow
|
||||
### Flux de lucru pentru dezvoltare
|
||||
|
||||
1. **`yarn twenty dev`** — watches source files, rebuilds on change, syncs to the server, generates typed API clients
|
||||
2. **`yarn twenty build`** — produces a distributable build
|
||||
3. **`yarn twenty deploy`** — deploys to a remote Twenty server
|
||||
4. **`yarn twenty add`** — scaffolds a new entity interactively
|
||||
1. **`yarn twenty dev`** — monitorizează fișierele sursă, reconstruiește la modificări, sincronizează cu serverul, generează clienți API tipizați
|
||||
2. **`yarn twenty build`** — produce o versiune distribuibilă
|
||||
3. **`yarn twenty deploy`** — implementează pe un server Twenty la distanță
|
||||
4. **`yarn twenty add`** — generează interactiv o entitate nouă
|
||||
|
||||
### Referință CLI
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty help # List all commands
|
||||
yarn twenty server start # Start local dev server
|
||||
yarn twenty remote add # Connect to a Twenty server
|
||||
yarn twenty exec -n fn # Execute a logic function
|
||||
yarn twenty logs -n fn # Stream function logs
|
||||
yarn twenty help # Listează toate comenzile
|
||||
yarn twenty server start # Pornește serverul local de dezvoltare
|
||||
yarn twenty remote add # Conectează-te la un server Twenty
|
||||
yarn twenty exec -n fn # Execută o funcție logică
|
||||
yarn twenty logs -n fn # Transmite în flux jurnalele funcției
|
||||
```
|
||||
|
||||
See the [Getting Started](/l/ro/developers/extend/apps/getting-started) guide for the full CLI reference.
|
||||
Consultați ghidul [Începeți](/l/ro/developers/extend/apps/getting-started) pentru referința completă CLI.
|
||||
|
||||
Reference in New Issue
Block a user