-
);
};
export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
+ universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+ name: 'hello-world',
+ description: 'A simple front component',
+ component: HelloWorld,
+ command: {
+ universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+ shortLabel: 'Hello',
+ label: 'Hello World',
+ icon: 'IconBolt',
+ isPinned: true,
+ availabilityType: 'GLOBAL',
+ },
});
```
-النقاط الرئيسية:
+بعد المزامنة باستخدام `yarn twenty dev`، يظهر الإجراء السريع في الزاوية العلوية اليمنى من الصفحة:
-* المكوّنات الأمامية هي مكوّنات React تُعرَض ضمن سياقات معزولة داخل Twenty.
-* يشير الحقل `component` إلى مكوّن React الخاص بك.
-* يتم بناء المكوّنات ومزامنتها تلقائيًا أثناء `yarn twenty dev`.
+My Custom Widget
-This is a custom front component for Twenty.
+Hello from my app!
+This component renders inside Twenty.
+ 
+
-يمكنك إنشاء مكوّنات أمامية جديدة بطريقتين:
+انقره لعرض المكوّن مضمنًا داخل الصفحة.
-* **مُنشأ بالقالب**: شغّل `yarn twenty add` واختر خيار إضافة مكوّن أمامي جديد.
-* **يدوي**: أنشئ ملفًا جديدًا `.tsx` واستخدم `defineFrontComponent()` مع اتباع النمط نفسه.
+{/* TODO: add screenshot of the rendered front component */}
-### المهارات
+#### حقول التكوين
+
+| الحقل | مطلوب | الوصف |
+| --------------------- | ----- | ----------------------------------------------------------------- |
+| `universalIdentifier` | نعم | معرّف فريد ثابت لهذا المكوّن |
+| `component` | نعم | دالة مكوّن React |
+| `name` | لا | اسم العرض |
+| `الوصف` | لا | وصف لما يفعله المكوّن |
+| `isHeadless` | لا | عيِّنه إلى `true` إذا كان المكوّن بلا واجهة مرئية (انظر أدناه) |
+| `أمر` | لا | سجّل المكوّن كأمر (انظر [خيارات الأوامر](#command-options) أدناه) |
+
+#### وضع مكوّن أمامي على صفحة
+
+إضافةً إلى الأوامر، يمكنك تضمين مكوّن أمامي مباشرةً في صفحة سجل عبر إضافته كودجت في **تخطيط صفحة**. راجع قسم [definePageLayout](#definepagelayout) للتفاصيل.
+
+#### مكوّنات عديمة الواجهة (`isHeadless: true`)
+
+المكوّنات عديمة الواجهة لا تُظهر واجهة مرئية لكنها ما تزال تُشغِّل منطق React. يكون هذا مفيدًا لـ **مكوّنات التأثير** — وهي مكوّنات تُجري تأثيرات جانبية عند التثبيت، مثل مزامنة البيانات، بدء مؤقّت، الاستماع إلى الأحداث، أو إطلاق إشعار.
+
+```tsx src/front-components/sync-tracker.tsx
+import { defineFrontComponent, useRecordId, enqueueSnackbar } from 'twenty-sdk';
+import { useEffect } from 'react';
+
+const SyncTracker = () => {
+ const recordId = useRecordId();
+
+ useEffect(() => {
+ enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
+ }, [recordId]);
+
+ return null;
+};
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'sync-tracker',
+ description: 'Tracks record views silently',
+ isHeadless: true,
+ component: SyncTracker,
+});
+```
+
+نظرًا لأن المكوّن يُرجع `null`، فإن Twenty يتخطّى عرض حاوية له — ولن تظهر مساحة فارغة في التخطيط. لا يزال لدى المكوّن إمكانية الوصول إلى جميع الخطافات وواجهة برمجة الاتصال مع المضيف.
+
+#### الوصول إلى سياق وقت التشغيل
+
+داخل مكوّنك، استخدم خطافات SDK للوصول إلى المستخدم الحالي، والسجل، ومثيل المكوّن:
+
+```tsx src/front-components/record-info.tsx
+import {
+ defineFrontComponent,
+ useUserId,
+ useRecordId,
+ useFrontComponentId,
+} from 'twenty-sdk';
+
+const RecordInfo = () => {
+ const userId = useUserId();
+ const recordId = useRecordId();
+ const componentId = useFrontComponentId();
+
+ return (
+
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
+ name: 'record-info',
+ component: RecordInfo,
+});
+```
+
+الخطافات المتاحة:
+
+| الخطّاف | القيم المعادة | الوصف |
+| --------------------------------------------- | ------------------ | ---------------------------------------------- |
+| `useUserId()` | `string` أو `null` | معرّف المستخدم الحالي |
+| `useRecordId()` | `string` أو `null` | معرّف السجل الحالي (عند وضعه على صفحة سجل) |
+| `useFrontComponentId()` | `string` | معرّف مثيل هذا المكوّن |
+| `useFrontComponentExecutionContext(selector)` | يختلف | الوصول إلى سياق التنفيذ الكامل عبر دالة محدِّد |
+
+#### واجهة الاتصال مع المضيف
+
+يمكن للمكوّنات الأمامية تشغيل التنقّل والنوافذ المنبثقة والإشعارات باستخدام دوال من `twenty-sdk`:
+
+| دالة | الوصف |
+| ----------------------------------------------- | ------------------------------ |
+| `navigate(to, params?, queryParams?, options?)` | الانتقال إلى صفحة داخل التطبيق |
+| `openSidePanelPage(params)` | فتح لوحة جانبية |
+| `closeSidePanel()` | إغلاق اللوحة الجانبية |
+| `openCommandConfirmationModal(params)` | عرض مربع حوار تأكيد |
+| `enqueueSnackbar(params)` | عرض إشعار توست |
+| `unmountFrontComponent()` | إلغاء تركيب المكوّن |
+| `updateProgress(progress)` | تحديث مؤشّر التقدّم |
+
+#### خيارات الأوامر
+
+إضافة حقل `command` إلى `defineFrontComponent` تُسجِّل المكوّن في قائمة الأوامر (Cmd+K). إذا كانت قيمة `isPinned` هي `true`، فسيظهر أيضًا كزر إجراء سريع في الزاوية العلوية اليمنى من الصفحة.
+
+| الحقل | مطلوب | الوصف |
+| --------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `universalIdentifier` | نعم | معرّف فريد ثابت للأمر |
+| `التسمية` | نعم | التسمية الكاملة المعروضة في قائمة الأوامر (Cmd+K) |
+| `shortLabel` | لا | تسمية أقصر تُعرَض على زر الإجراء السريع المثبّت |
+| `أيقونة` | لا | اسم الأيقونة المعروض بجانب التسمية (مثل `'IconBolt'` و`'IconSend'`) |
+| `isPinned` | لا | عند كونها `true`، يعرض الأمر كزر إجراء سريع في الزاوية العلوية اليمنى من الصفحة |
+| `availabilityType` | لا | تتحكّم في مكان ظهور الأمر: `'GLOBAL'` (متاح دائمًا)، و`'RECORD_SELECTION'` (فقط عند تحديد سجلات)، أو `'FALLBACK'` (يُعرَض عند عدم تطابق أي أوامر أخرى) |
+| `availabilityObjectUniversalIdentifier` | لا | تقييد الأمر بصفحات نوع كائن معيّن (مثل سجلات Company فقط) |
+| `conditionalAvailabilityExpression` | لا | تعبير منطقي للتحكم ديناميكيًا في ما إذا كان الأمر مرئيًا (انظر أدناه) |
+
+#### تعابير الإتاحة الشرطية
+
+يتيح لك الحقل `conditionalAvailabilityExpression` التحكّم في وقت ظهور الأمر بناءً على سياق الصفحة الحالي. استورد متغيّرات ومشغّلات مضبوطة الأنواع من `twenty-sdk` لبناء التعابير:
+
+```tsx
+import {
+ defineFrontComponent,
+ pageType,
+ numberOfSelectedRecords,
+ objectPermissions,
+ everyEquals,
+ isDefined,
+} from 'twenty-sdk';
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'bulk-action',
+ component: BulkAction,
+ command: {
+ universalIdentifier: '...',
+ label: 'Bulk Update',
+ availabilityType: 'RECORD_SELECTION',
+ conditionalAvailabilityExpression: everyEquals(
+ objectPermissions,
+ 'canUpdateObjectRecords',
+ true,
+ ),
+ },
+});
+```
+
+**متغيّرات السياق** — تُمثّل الحالة الحالية للصفحة:
+
+| المتغيّر | النوع | الوصف |
+| ------------------------------ | ------------- | --------------------------------------------------------------- |
+| `pageType` | `string` | نوع الصفحة الحالي (مثل `'RecordIndexPage'` و`'RecordShowPage'`) |
+| `isInSidePanel` | `قيمة منطقية` | ما إذا كان المكوّن معروضًا في لوحة جانبية |
+| `numberOfSelectedRecords` | `رقم` | عدد السجلات المحدّدة حاليًا |
+| `isSelectAll` | `قيمة منطقية` | ما إذا كان "تحديد الكل" مفعّلًا |
+| `selectedRecords` | `array` | كائنات السجلات المحدّدة |
+| `favoriteRecordIds` | `array` | معرّفات السجلات المفضّلة |
+| `objectPermissions` | `الكائن` | الأذونات الخاصة بنوع الكائن الحالي |
+| `targetObjectReadPermissions` | `الكائن` | أذونات القراءة للكائن الهدف |
+| `targetObjectWritePermissions` | `الكائن` | أذونات الكتابة للكائن الهدف |
+| `featureFlags` | `الكائن` | أعلام الميزات المفعَّلة |
+| `objectMetadataItem` | `الكائن` | بيانات التعريف لنوع الكائن الحالي |
+| `hasAnySoftDeleteFilterOnView` | `قيمة منطقية` | ما إذا كان العرض الحالي يحتوي على مرشّح حذف منطقي |
+
+**المُشغِّلات** — جمّع المتغيّرات في تعابير منطقية:
+
+| المُشغِّل | الوصف |
+| ----------------------------------- | -------------------------------------------------------------- |
+| `isDefined(value)` | `true` إذا لم تكن القيمة null/undefined |
+| `isNonEmptyString(value)` | `true` إذا كانت القيمة سلسلة غير فارغة |
+| `includes(array, value)` | `true` إذا كانت المصفوفة تحتوي على القيمة |
+| `includesEvery(array, prop, value)` | `true` إذا كانت خاصية كل عنصر تتضمن القيمة |
+| `every(array, prop)` | `true` إذا كانت الخاصية تُقيَّم بصحّة في كل عنصر |
+| `everyDefined(array, prop)` | `true` إذا كانت الخاصية معرّفة في كل عنصر |
+| `everyEquals(array, prop, value)` | `true` إذا كانت الخاصية تساوي القيمة في كل عنصر |
+| `some(array, prop)` | `true` إذا كانت الخاصية تُقيَّم بصحّة في عنصر واحد على الأقل |
+| `someDefined(array, prop)` | `true` إذا كانت الخاصية معرّفة في عنصر واحد على الأقل |
+| `someEquals(array, prop, value)` | `true` إذا كانت الخاصية تساوي القيمة في عنصر واحد على الأقل |
+| `someNonEmptyString(array, prop)` | `true` إذا كانت الخاصية سلسلة غير فارغة في عنصر واحد على الأقل |
+| `none(array, prop)` | `true` إذا كانت الخاصية تُقيَّم بخطأ في كل عنصر |
+| `noneDefined(array, prop)` | `true` إذا كانت الخاصية غير معرّفة في كل عنصر |
+| `noneEquals(array, prop, value)` | `true` إذا لم تكن الخاصية تساوي القيمة في أي عنصر |
+
+#### الأصول العامة
+
+يمكن للمكوّنات الأمامية الوصول إلى ملفات من دليل `public/` للتطبيق باستخدام `getPublicAssetUrl`:
+
+```tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk';
+
+const Logo = () => User: {userId}
+Record: {recordId ?? 'No record context'}
+Component: {componentId}
+})
;
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'logo',
+ component: Logo,
+});
+```
+
+راجع [قسم الأصول العامة](#accessing-public-assets-with-getpublicasseturl) للتفاصيل.
+
+#### التنسيق
+
+تدعم المكوّنات الأمامية عدة أساليب للتنسيق. يمكنك استخدام:
+
+* **أنماط مضمنة** — `style={{ color: 'red' }}`
+* **مكوّنات Twenty لواجهة المستخدم** — استورد من `twenty-sdk/ui` (Button وTag وStatus وChip وAvatar وغيرها)
+* **Emotion** — CSS-in-JS مع `@emotion/react`
+* **Styled-components** — أنماط `styled.div`
+* **Tailwind CSS** — أصناف مساعدة
+* **أي مكتبة CSS-in-JS** متوافقة مع React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { Button, Tag, Status } from 'twenty-sdk/ui';
+
+const StyledWidget = () => {
+ return (
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
+ name: 'styled-widget',
+ component: StyledWidget,
+});
+```
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### كيف يعمل التجميع + +تستخدم خطوة البناء (`yarn twenty dev` أو `yarn twenty build`) أداة esbuild لإنتاج ملف واحد مستقل لكل دالة منطقية وكل مكوّن أمامي. تُضمَّن جميع الحزم المستوردة داخل الحزمة. + +**الدوال المنطقية** تعمل في بيئة Node.js. الوحدات المدمجة في Node (`fs` و`path` و`crypto` و`http` وغيرها) متاحة ولا تحتاج إلى تثبيت. + +**المكوّنات الأمامية** تعمل ضمن Web Worker. وحدات Node المدمجة غير متاحة — المتاح فقط واجهات برمجة المتصفّح وحِزَم npm التي تعمل في بيئة المتصفّح. + +كلتا البيئتين تحتويان على `twenty-client-sdk/core` و`twenty-client-sdk/metadata` كوحدات متاحة مُسبقًا — لا تُضمَّن هذه ضمن الحزم بل تُحلّ وقت التشغيل بواسطة الخادم. + +## توليد قوالب الكيانات باستخدام `yarn twenty add` + +بدلًا من إنشاء ملفات الكيانات يدويًا، يمكنك استخدام أداة القوالب التفاعلية: + +```bash filename="Terminal" +yarn twenty add +``` + +ستطالبك باختيار نوع الكيان وتُرشدك خلال الحقول المطلوبة. تُولّد ملفًا جاهزًا للاستخدام مع `universalIdentifier` ثابت واستدعاء `defineEntity()` الصحيح. + +يمكنك أيضًا تمرير نوع الكيان مباشرة لتخطي المطالبة الأولى: + +```bash filename="Terminal" +yarn twenty add object +yarn twenty add logicFunction +yarn twenty add frontComponent +``` + +### أنواع الكيانات المتاحة + +| نوع الكيان | أمر | الملف المُولَّد | +| ------------------ | ------------------------------------ | ------------------------------------- | +| كائن | `yarn twenty add object` | `src/objects/
+ 
+
+
+## Step 3: Sign in to your workspace
+
+Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+ 
+
+
+## Step 4: Authorize the app
+
+After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
+
+Click **Authorize** to continue.
+
+
+
+ 
+
+
+Once authorized, your terminal will confirm that everything is set up.
+
+
+
+ 
+
+
+## Step 5: Start developing
+
+Go into your new app folder and start the development server:
```bash filename="Terminal"
-# Add a new entity to your application (guided)
-yarn twenty add
-
-# Watch your application's function logs
-yarn twenty function:logs
-
-# Execute a function by name
-yarn twenty function:execute -n my-function -p '{"name": "test"}'
-
-# Execute the pre-install function
-yarn twenty function:execute --preInstall
-
-# Execute the post-install function
-yarn twenty function:execute --postInstall
-
-# Uninstall the application from the current workspace
-yarn twenty uninstall
-
-# Display commands' help
-yarn twenty help
+cd my-twenty-app
+yarn twenty dev
```
-راجع أيضًا: صفحات مرجع CLI لـ [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) و[twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
+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.
-## هيكل المشروع (مُنشأ بالقالب)
+For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
-عند تشغيل `npx create-twenty-app@latest my-twenty-app`، يقوم المُهيئ بما يلي:
+```bash filename="Terminal"
+yarn twenty dev --verbose
+```
-* ينسخ تطبيقًا أساسيًا مصغّرًا إلى `my-twenty-app/`
-* يضيف اعتمادًا محليًا `twenty-sdk` وتهيئة Yarn 4
-* ينشئ ملفات ضبط ونصوصًا مرتبطة بـ `twenty` CLI
-* يُنشئ الملفات الأساسية (تهيئة التطبيق، دور الدالة الافتراضي، دالتا ما قبل التثبيت وما بعد التثبيت) بالإضافة إلى ملفات أمثلة استنادًا إلى وضع الإنشاء.
+
+
+ 
+
+
+## Step 6: See your app in 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**:
+
+
+
+ 
+
+
+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.
+
+
+
+ 
+
+
+Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
+
+
+
+ 
+
+
+Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
+
+
+
+ 
+
+
+You are all set! Edit any file in `src/` and the changes will be picked up automatically.
+
+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.
+
+---
+
+## Project structure
+
+The scaffolder generates the following file structure (shown with `--exhaustive` mode, which includes examples for every entity type):
```text filename="my-twenty-app/"
my-twenty-app/
@@ -83,124 +152,238 @@ my-twenty-app/
install-state.gz
.oxlintrc.json
tsconfig.json
+ tsconfig.spec.json # TypeScript config for tests
+ vitest.config.ts # Vitest test runner configuration
+ LLMS.md
README.md
- public/ # Public assets folder (images, fonts, etc.)
+ .github/
+ └── workflows/
+ └── ci.yml # GitHub Actions CI workflow
+ public/ # Public assets (images, fonts, etc.)
src/
- ├── application-config.ts # Required - main application configuration
+ ├── application-config.ts # Required — main application configuration
+ ├── __tests__/
+ │ ├── setup-test.ts # Test setup (server health check, config)
+ │ └── app-install.integration-test.ts # Example integration test
├── roles/
- │ └── default-role.ts # Default role for logic functions
+ │ └── default-role.ts # Default role for logic functions
├── objects/
- │ └── example-object.ts # Example custom object definition
+ │ └── example-object.ts # Example custom object definition
├── fields/
- │ └── example-field.ts # Example standalone field definition
+ │ └── example-field.ts # Example standalone field definition
├── logic-functions/
- │ ├── hello-world.ts # Example logic function
- │ ├── pre-install.ts # Pre-install logic function
- │ └── post-install.ts # Post-install logic function
+ │ ├── hello-world.ts # Example logic function
+ │ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
+ │ ├── pre-install.ts # Runs before installation
+ │ └── post-install.ts # Runs after installation
├── front-components/
- │ └── hello-world.tsx # Example front component
+ │ └── hello-world.tsx # Example front component
+ ├── page-layouts/
+ │ └── example-record-page-layout.ts # Example page layout with front component
├── views/
- │ └── example-view.ts # Example saved view definition
+ │ └── example-view.ts # Example saved view definition
├── navigation-menu-items/
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
- └── skills/
- └── example-skill.ts # Example AI agent skill definition
+ ├── skills/
+ │ └── example-skill.ts # Example AI agent skill definition
+ └── agents/
+ └── example-agent.ts # Example AI agent definition
```
-مع `--minimal`، سيتم إنشاء الملفات الأساسية فقط (`application-config.ts`، `roles/default-role.ts`، `logic-functions/pre-install.ts`، و`logic-functions/post-install.ts`).
+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.
-بشكل عام:
+### Key files
-* **package.json**: يصرّح باسم التطبيق والإصدار والمحرّكات (Node 24+، Yarn 4)، ويضيف `twenty-sdk` بالإضافة إلى نص برمجي `twenty` يفوِّض إلى `twenty` CLI المحلي. شغِّل `yarn twenty help` لعرض جميع الأوامر المتاحة.
-* **.gitignore**: يتجاهل العناصر الشائعة مثل `node_modules` و`.yarn` و`.twenty/` و`dist/` و`build/` ومجلدات التغطية وملفات السجلات وملفات `.env*`.
-* **yarn.lock**، **.yarnrc.yml**، **.yarn/**: تقوم بقفل وتكوين حزمة أدوات Yarn 4 المستخدمة في المشروع.
-* **.nvmrc**: يثبّت إصدار Node.js المتوقع للمشروع.
-* **.oxlintrc.json** و **tsconfig.json**: يقدّمان إعدادات الفحص والتهيئة لـ TypeScript لمصادر TypeScript في تطبيقك.
-* **README.md**: ملف README قصير في جذر التطبيق يتضمن تعليمات أساسية.
-* **public/**: مجلد لتخزين الأصول العامة (صور، خطوط، ملفات ثابتة) التي سيتم تقديمها مع تطبيقك. الملفات الموضوعة هنا تُرفع أثناء المزامنة وتكون متاحة أثناء وقت التشغيل.
-* **src/**: المكان الرئيسي حيث تعرّف تطبيقك ككود
+| 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. |
+| `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. |
-### اكتشاف الكيانات
+## Managing remotes
-يكتشف SDK الكيانات عبر تحليل ملفات TypeScript الخاصة بك بحثًا عن استدعاءات **`export default define
+
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
-});
-```
-
-النقاط الرئيسية:
-
-* المكوّنات الأمامية هي مكوّنات React تُعرَض ضمن سياقات معزولة داخل Twenty.
-* يشير الحقل `component` إلى مكوّن React الخاص بك.
-* يتم بناء المكوّنات ومزامنتها تلقائيًا أثناء `yarn twenty dev`.
-
-يمكنك إنشاء مكوّنات أمامية جديدة بطريقتين:
-
-* **مُنشأ بالقالب**: شغّل `yarn twenty entity:add` واختر خيار إضافة مكوّن أمامي جديد.
-* **يدوي**: أنشئ ملفًا جديدًا `.tsx` واستخدم `defineFrontComponent()` مع اتباع النمط نفسه.
-
-#### أين يمكن استخدام مكوّنات الواجهة الأمامية
-
-يمكن عرض مكوّنات الواجهة الأمامية في موقعين داخل Twenty:
-
-* **اللوحة الجانبية** — المكوّنات غير عديمة الرأس تفتح في اللوحة الجانبية اليمنى. هذا هو السلوك الافتراضي عندما يتم تشغيل مكوّن واجهة أمامية من قائمة الأوامر.
-* **الويدجت (لوحات المعلومات وصفحات السجلات)** — يمكن تضمين مكوّنات الواجهة الأمامية كويدجت داخل تخطيطات الصفحات. عند تكوين لوحة معلومات أو تخطيط صفحة سجل، يمكن للمستخدمين إضافة ويدجت لمكوّن واجهة أمامية.
-
-#### عديم الرأس مقابل غير عديم الرأس
-
-تأتي مكوّنات الواجهة الأمامية بوضعَي عرض يتحكّم بهما الخيار `isHeadless`:
-
-**غير عديم الرأس (افتراضي)** — يعرض المكوّن واجهة مستخدم مرئية. عند تشغيله من قائمة الأوامر يفتح في اللوحة الجانبية. هذا هو السلوك الافتراضي عندما تكون `isHeadless` تساوي `false` أو يتم تجاهلها.
-
-**عديم الرأس** — يتم تركيب المكوّن بشكل غير مرئي في الخلفية. لا يفتح اللوحة الجانبية. تم تصميم المكوّنات عديمة الرأس لإجراءات تنفّذ منطقًا ثم تُزيل تركيبها ذاتيًا — على سبيل المثال، تشغيل مهمة غير متزامنة، أو الانتقال إلى صفحة، أو إظهار نافذة تأكيد منبثقة. تتوافق بشكل طبيعي مع مكوّنات Command في SDK الموصوفة أدناه.
-
-```typescript
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-action',
- description: 'Runs an action without opening the side panel',
- component: MyAction,
- isHeadless: true,
- command: {
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
- label: 'Run my action',
- },
-});
-```
-
-#### إضافة عناصر قائمة الأوامر
-
-لجعل مكوّن واجهة أمامية يظهر كعنصر في قائمة الأوامر في Twenty، أضف الخاصية `command` إلى `defineFrontComponent()`. عند فتح المستخدمين لقائمة الأوامر (Cmd+K / Ctrl+K)، يظهر العنصر ويشغّل مكوّن الواجهة الأمامية عند النقر.
-
-يقبل كائن `command` الحقول التالية:
-
-| الحقل | النوع | الوصف |
-| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
-| `universalIdentifier` | `string` (إلزامي) | معرّف فريد لعنصر قائمة الأوامر |
-| `التسمية` | `string` (إلزامي) | التسمية المعروضة في قائمة الأوامر |
-| `أيقونة` | `string` (اختياري) | اسم الأيقونة (مثال: `'IconSparkles'`) |
-| `isPinned` | `boolean` (اختياري) | ما إذا كان الأمر مثبتًا أعلى القائمة |
-| `availabilityType` | `'GLOBAL' \| 'RECORD_SELECTION'` (اختياري) | `GLOBAL` يعرض الأمر في كل مكان؛ `RECORD_SELECTION` يعرضه فقط في سياقات السجلّات |
-| `availabilityObjectUniversalIdentifier` | `string` (اختياري) | تقييد الأمر بنوع كائن محدّد (مثال: Person) |
-
-إليك مثالًا من تطبيق تسجيل المكالمات يضيف أمرًا محصورًا بسجلات Person:
-
-```typescript
-import { defineFrontComponent } from 'twenty-sdk';
-
-export default defineFrontComponent({
- universalIdentifier: 'c3d4e5f6-a7b8-9012-cdef-123456789012',
- name: 'Summarize Person Call Recordings',
- description: 'Generates a summary of call recordings for a person',
- component: SummarizePersonRecordings,
- command: {
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-234567890123',
- label: 'Summarize call recordings',
- icon: 'IconSparkles',
- isPinned: false,
- availabilityType: 'RECORD_SELECTION',
- availabilityObjectUniversalIdentifier:
- '20202020-e674-48e5-a542-72570eee7213',
- },
-});
-```
-
-عند مزامنة الأمر، يظهر في قائمة الأوامر. إذا كان مكوّن الواجهة الأمامية غير عديم الرأس، تُفتح اللوحة الجانبية مع عرض المكوّن بداخلها. إذا كان عديم الرأس، فسيتم تركيب المكوّن في الخلفية وتنفيذ منطقه.
-
-#### مكوّنات Command في SDK
-
-توفر حزمة `twenty-sdk` أربعة مكوّنات مساعدة من نوع Command مصممة للمكوّنات عديمة الرأس في الواجهة الأمامية. كل مكوّن ينفّذ إجراءً عند التركيب، ويتعامل مع الأخطاء بعرض إشعار Snackbar، ويزيل تركيب مكوّن الواجهة الأمامية تلقائيًا عند الانتهاء.
-
-استوردها من `twenty-sdk/command`:
-
-* **`Command`** — يشغّل رد نداء غير متزامن عبر الخاصية `execute`.
-* **`CommandLink`** — ينتقل إلى مسار في التطبيق. الخصائص: `to`، `params`، `queryParams`، `options`.
-* **`CommandModal`** — يفتح نافذة تأكيد منبثقة. إذا أكّد المستخدم، ينفّذ رد النداء `execute`. الخصائص: `title`، `subtitle`، `execute`، `confirmButtonText`، `confirmButtonAccent`.
-* **`CommandOpenSidePanelPage`** — يفتح صفحة محدّدة في اللوحة الجانبية. الخصائص: `page`، `pageTitle`، `pageIcon`.
-
-فيما يلي مثال كامل لمكوّن واجهة أمامية عديم الرأس يستخدم `Command` لتشغيل إجراء من قائمة الأوامر:
-
-```typescript
-// src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk';
-import { Command } from 'twenty-sdk/command';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const RunAction = () => {
- const execute = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- createTask: {
- __args: { data: { title: 'Created by my app' } },
- id: true,
- },
- });
- };
-
- return My Custom Widget
-This is a custom front component for Twenty.
-
-
- );
-};
-```
-
-السياق تفاعلي — إذا تغيّر السجل المحيط، فستُرجع الخطافات القيم المحدّثة تلقائيًا.
-
-#### دوال واجهة برمجة تطبيقات المضيف
-
-تعمل مكوّنات الواجهة الأمامية في بيئة معزولة، لكنها تستطيع التفاعل مع واجهة مستخدم Twenty عبر مجموعة من الدوال التي يوفّرها المضيف. استوردها مباشرةً من `twenty-sdk`:
-
-```typescript
-import {
- navigate,
- closeSidePanel,
- enqueueSnackbar,
- unmountFrontComponent,
- openSidePanelPage,
- openCommandConfirmationModal,
-} from 'twenty-sdk';
-```
-
-| دالة | التوقيع | الوصف |
-| ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `التنقل` | `(to, params?, queryParams?, options?) => PromiseRecord: {recordId ?? 'none'}
-User: {userId ?? 'anonymous'}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### المهارات
-
-تُحدِّد المهارات تعليمات وإمكانات قابلة لإعادة الاستخدام يمكن لوكلاء الذكاء الاصطناعي استخدامها داخل مساحة العمل لديك. استخدم `defineSkill()` لتعريف مهارات مع تحقّق مدمج:
-
-```typescript
-// src/skills/example-skill.ts
-import { defineSkill } from 'twenty-sdk';
-
-export default defineSkill({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-outreach',
- label: 'التواصل البيعي',
- description: 'يرشد وكيل الذكاء الاصطناعي خلال عملية منظّمة للتواصل البيعي',
- icon: 'IconBrain',
- content: `أنت مساعد للتواصل البيعي. عند التواصل مع عميل محتمل:
-1. ابحث عن الشركة وآخر الأخبار
-2. حدِّد دور العميل المحتمل ونقاط الألم المرجّحة
-3. صِغ رسالة مخصّصة تشير إلى تفاصيل محدّدة
-4. حافظ على نبرة احترافية ولكن حوارية`,
-});
-```
-
-النقاط الرئيسية:
-
-* `name` هي سلسلة معرّف فريدة للمهارة (يُنصَح باستخدام kebab-case).
-* `label` هو اسم العرض المقروء للبشر الظاهر في واجهة المستخدم.
-* `content` يحتوي على تعليمات المهارة — وهو النص الذي يستخدمه وكيل الذكاء الاصطناعي.
-* `icon` (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
-* `description` (اختياري) يوفّر سياقًا إضافيًا حول غرض المهارة.
-
-يمكنك إنشاء مهارات جديدة بطريقتين:
-
-* **مُنشأ بالقالب**: شغِّل `yarn twenty entity:add` واختر خيار إضافة مهارة جديدة.
-* **يدوي**: أنشئ ملفًا جديدًا واستخدم `defineSkill()` مع اتباع النمط نفسه.
-
-### الوكلاء
-
-تمكّنك ميزة الوكلاء من تعريف وكلاء ذكاء اصطناعي قادرين على العمل ضمن مساحة عملك، باستخدام موجهات النظام. استخدم `defineAgent()` لتعريف وكلاء مع تحقق مدمج:
-
-```typescript
-// src/agents/example-agent.ts
-import { defineAgent } from 'twenty-sdk';
-
-export default defineAgent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-assistant',
- label: 'Sales Assistant',
- description: 'An AI agent that helps with sales tasks',
- icon: 'IconRobot',
- prompt: `You are a sales assistant. Help users with:
-1. Researching prospects and companies
-2. Drafting personalized outreach messages
-3. Tracking follow-ups and next steps
-4. Analyzing deal pipeline and suggesting actions`,
-});
-```
-
-النقاط الرئيسية:
-
-* `name` هي سلسلة معرّف فريدة للوكيل (يُنصَح باستخدام kebab-case).
-* `label` هو اسم العرض المقروء للبشر الظاهر في واجهة المستخدم.
-* `prompt` يحتوي موجه النظام — وهو نص التعليمات الذي يحدد سلوك الوكيل.
-* `icon` (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
-* `description` (اختياري) يوفّر سياقًا إضافيًا حول غرض الوكيل.
-
-يمكنك إنشاء وكلاء جدد بطريقتين:
-
-* **مُنشأ بالقالب**: شغِّل `yarn twenty entity:add` واختر خيار إضافة وكيل جديد.
-* **يدوي**: أنشئ ملفًا جديدًا واستخدم `defineAgent()` مع اتباع النمط نفسه.
-
-### عملاء مُولَّدون مضبوطو الأنواع
-
-يتم توليد عميلين مضبوطي الأنواع تلقائيًا بواسطة `yarn twenty dev` وتخزينهما في `node_modules/twenty-sdk/clients` استنادًا إلى مخطط مساحة العمل لديك:
-
-* **`CoreApiClient`** — يُجري استعلامات إلى نقطة النهاية `/graphql` للحصول على بيانات مساحة العمل
-* **`MetadataApiClient`** — يستعلم عن نقطة النهاية `/metadata` لتكوين مساحة العمل وتحميل الملفات.
-
-```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-
-const client = new CoreApiClient();
-const { me } = await client.query({ me: { id: true, displayName: true } });
-
-const metadataClient = new MetadataApiClient();
-const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });},{
-```
-
-`CoreApiClient` يُعاد توليده تلقائيًا بواسطة `yarn twenty dev` كلما تغيّرت كائناتك أو حقولك. `MetadataApiClient` يأتي مُجهزًا مسبقًا مع SDK.
-
-#### بيانات الاعتماد وقت التشغيل في الوظائف المنطقية
-
-عندما تعمل وظيفتك على Twenty، يقوم النظام الأساسي بحقن بيانات الاعتماد كمتغيرات بيئة قبل تنفيذ كودك:
-
-* `TWENTY_API_URL`: عنوان URL الأساسي لواجهة Twenty البرمجية التي يستهدفها تطبيقك.
-* `TWENTY_API_KEY`: مفتاح قصير العمر ذو نطاق يقتصر على الدور الافتراضي لوظيفة تطبيقك.
-
-الملاحظات:
-
-* لا تحتاج إلى تمرير عنوان URL أو مفتاح واجهة برمجة التطبيقات إلى العميل المُولَّد. يقوم بقراءة `TWENTY_API_URL` و`TWENTY_API_KEY` من process.env وقت التشغيل.
-* تُحدَّد أذونات مفتاح واجهة برمجة التطبيقات بواسطة الدور المشار إليه في `application-config.ts` عبر `defaultRoleUniversalIdentifier`. هذا هو الدور الافتراضي الذي تستخدمه الوظائف المنطقية في تطبيقك.
-* يمكن للتطبيقات تعريف أدوار لاتباع مبدأ أقل الامتياز. امنح فقط الأذونات التي تحتاجها وظائفك، ثم وجّه `defaultRoleUniversalIdentifier` إلى المعرّف الشامل لذلك الدور.
-
-#### رفع الملفات
-
-يتضمن `MetadataApiClient` طريقة `uploadFile` لإرفاق الملفات بالحقول من نوع ملف ضمن كائنات مساحة العمل الخاصة بك. نظرًا لأن عملاء GraphQL القياسيون لا يدعمون تحميل الملفات متعددة الأجزاء افتراضيًا، يوفر العميل هذه الطريقة المخصصة التي تطبق [مواصفة طلب GraphQL متعدد الأجزاء](https://github.com/jaydenseric/graphql-multipart-request-spec) في الخلفية.
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-import * as fs from 'fs';
-
-const metadataClient = new MetadataApiClient();
-
-const fileBuffer = fs.readFileSync('./invoice.pdf');
-
-const uploadedFile = await metadataClient.uploadFile(
- fileBuffer, // محتوى الملف كـ Buffer
- 'invoice.pdf', // اسم الملف
- 'application/pdf', // نوع MIME (القيمة الافتراضية 'application/octet-stream')
- '58a0a314-d7ea-4865-9850-7fb84e72f30b', // المعرّف العالمي للحقل
-);
-
-console.log(uploadedFile);
-// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
-```
-
-توقيع الطريقة:
-
-```typescript
-uploadFile(
- fileBuffer: Buffer,
- filename: string,
- contentType: string,
- fieldMetadataUniversalIdentifier: string,
-): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
-```
-
-| المعلمة | النوع | الوصف |
-| ---------------------------------- | -------- | ---------------------------------------------------------------------------------- |
-| `fileBuffer` | `Buffer` | المحتوى الخام للملف |
-| `filename` | `string` | اسم الملف (يُستخدم للتخزين والعرض) |
-| `contentType` | `string` | نوع MIME للملف (القيمة الافتراضية هي `application/octet-stream` إذا لم يتم تحديده) |
-| `fieldMetadataUniversalIdentifier` | `string` | قيمة `universalIdentifier` لحقل نوع الملف في كائنك |
-
-النقاط الرئيسية:
-
-* تتوفر طريقة `uploadFile` على `MetadataApiClient` لأن عملية الـ mutation الخاصة بالرفع تُعالَج عبر نقطة النهاية `/metadata`.
-* تستخدم `universalIdentifier` الخاص بالحقل (وليس المعرّف الخاص بمساحة العمل)، ليعمل كود الرفع لديك عبر أي مساحة عمل مُثبَّت فيها تطبيقك — بما يتماشى مع كيفية إشارة التطبيقات إلى الحقول في كل مكان آخر.
-* العنوان `url` المُعاد هو عنوان URL موقّع يمكنك استخدامه للوصول إلى الملف المرفوع.
-
-### مثال Hello World
-
-استكشف مثالًا بسيطًا شاملًا من البداية إلى النهاية يوضح الكائنات والوظائف المنطقية والمكوّنات الأمامية ومشغّلات متعددة [هنا](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
-
-## بناء تطبيقك
-
-بمجرد أن تطوّر تطبيقك باستخدام `app:dev`، استخدم `app:build` لإنشاء حزمة قابلة للتوزيع منه.
-
-```bash filename="Terminal"
-# ابنِ التطبيق (الإخراج يذهب إلى .twenty/output/)
-yarn twenty build
-
-# ابنِ وأنشئ ملف tarball (.tgz) للتوزيع
-yarn twenty build --tarball
-```
-
-عملية البناء:
-
-1. **يقوم بتحليل ملف البيان والتحقق من صحته** — يقرأ جميع الكيانات `defineX()` من ملفات المصدر لديك ويُتحقّق من بنية ملف البيان.
-2. **يُصرِّف دوال المنطق ومكوّنات الواجهة** — يُجمّع مصادر TypeScript إلى ملفات ESM `.mjs` باستخدام esbuild.
-3. **يولّد قيم التحقّق** — يحسب تجزئات MD5 لكل ملف مُبنًى، وتُخزَّن في ملف البيان كـ `builtHandlerChecksum` / `builtComponentChecksum`.
-4. **ينشئ عميل API مضبوط الأنواع** — يفحص مخطط GraphQL ويُنشئ عميلَي `CoreApiClient` و`MetadataApiClient` مضبوطي الأنواع.
-5. **يشغّل فحص الأنواع لـ TypeScript** — يشغّل `tsc --noEmit` لاكتشاف أخطاء الأنواع قبل النشر.
-6. **يعيد البناء باستخدام العميل المُولَّد** — يُجري مرحلة ترجمة ثانية بحيث تُدرَج أنواع العميل المُولَّد.
-7. **ينشئ أرشيف tar اختياريًا** — إذا تم تمرير `--tarball`، يشغّل `npm pack` لإنشاء ملف `.tgz` جاهز للتوزيع.
-
-مخرجات البناء في `.twenty/output/` تتضمّن:
-
-```text
-.twenty/output/
-├── manifest.json # Manifest with checksums for all built files
-├── package.json # Copied from app root
-├── yarn.lock # Copied from app root
-├── src/
-│ ├── logic-functions/ # Compiled .mjs logic function files
-│ └── front-components/ # Compiled .mjs front component files
-├── public/ # Static assets (if any)
-└── my-app-1.0.0.tgz # Only with --tarball flag
-```
-
-| الخيار | الوصف |
-| ----------- | -------------------------------------------------- |
-| `[appPath]` | المسار إلى دليل التطبيق (افتراضيًا: الدليل الحالي) |
-| `--tarball` | قم أيضًا بحزم المخرجات في أرشيف `.tgz` |
-
-## نشر تطبيقك
-
-استخدم `app:publish` لتوزيع تطبيقك — إما إلى سجل npm أو مباشرةً إلى خادم Twenty.
-
-### النشر إلى npm (الإعداد الافتراضي)
-
-```bash filename="Terminal"
-# انشر إلى npm (يتطلب تسجيل الدخول إلى npm)
-yarn twenty publish
-
-# انشر باستخدام وسم توزيع (مثل beta، next)
-yarn twenty publish --tag beta
-```
-
-يقوم هذا ببناء التطبيق وتشغيل `npm publish` من دليل `.twenty/output/`. بعد ذلك يمكن تثبيت الحزمة المنشورة من سوق Twenty بواسطة أي مساحة عمل.
-
-### النشر إلى خادم Twenty
-
-```bash filename="Terminal"
-# انشر مباشرةً إلى خادم Twenty
-yarn twenty publish --server https://app.twenty.com
-```
-
-يقوم هذا ببناء التطبيق مع أرشيف tar، ويرفعه إلى الخادم عبر العملية `uploadAppTarball` في GraphQL، ويبدأ التثبيت في خطوة واحدة. يكون هذا مفيدًا لعمليات النشر الخاصة أو للاختبار مقابل خادم محدّد.
-
-| الخيار | الوصف |
-| ----------------- | -------------------------------------------------------- |
-| `[appPath]` | المسار إلى دليل التطبيق (افتراضيًا: الدليل الحالي) |
-| `--server Archive this record?
- -
-
);
};
export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
+ universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+ name: 'hello-world',
+ description: 'A simple front component',
+ component: HelloWorld,
+ command: {
+ universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+ shortLabel: 'Hello',
+ label: 'Hello World',
+ icon: 'IconBolt',
+ isPinned: true,
+ availabilityType: 'GLOBAL',
+ },
});
```
-Hlavní body:
+Po synchronizaci pomocí `yarn twenty dev` se rychlá akce zobrazí v pravém horním rohu stránky:
-* Frontendové komponenty jsou React komponenty, které se vykreslují v izolovaných kontextech v rámci Twenty.
-* Pole `component` odkazuje na vaši React komponentu.
-* Komponenty se během `yarn twenty dev` automaticky sestaví a synchronizují.
+My Custom Widget
-This is a custom front component for Twenty.
+Hello from my app!
+This component renders inside Twenty.
+
+
-Nové frontendové komponenty můžete vytvořit dvěma způsoby:
+Kliknutím na něj vykreslíte komponentu přímo ve stránce.
-* **Vygenerované**: Spusťte `yarn twenty add` a zvolte možnost přidat novou frontendovou komponentu.
-* **Ruční**: Vytvořte nový soubor `.tsx` a použijte `defineFrontComponent()`, podle stejného vzoru.
+{/* TODO: add screenshot of the rendered front component */}
-### Dovednosti
+#### Konfigurační pole
+
+| Pole | Povinné | Popis |
+| --------------------- | ------- | ------------------------------------------------------------------------------------ |
+| `universalIdentifier` | Ano | Stabilní jedinečné ID pro tuto komponentu |
+| `component` | Ano | Funkce komponenty React |
+| `name` | Ne | Zobrazovaný název |
+| `description` | Ne | Popis toho, co komponenta dělá |
+| `isHeadless` | Ne | Nastavte na `true`, pokud komponenta nemá viditelné UI (viz níže) |
+| `command` | Ne | Zaregistrujte komponentu jako příkaz (viz [možnosti příkazu](#command-options) níže) |
+
+#### Umístění frontendové komponenty na stránku
+
+Mimo příkazy můžete frontendovou komponentu vložit přímo na stránku záznamu přidáním jako widget v **rozvržení stránky**. Podrobnosti viz sekce [definePageLayout](#definepagelayout).
+
+#### Headless komponenty (`isHeadless: true`)
+
+Headless komponenty nevykreslují viditelné UI, ale stále spouštějí logiku Reactu. To je užitečné pro **efektové komponenty** — komponenty, které po připojení provádějí vedlejší efekty, jako je synchronizace dat, spuštění časovače, naslouchání událostem nebo vyvolání oznámení.
+
+```tsx src/front-components/sync-tracker.tsx
+import { defineFrontComponent, useRecordId, enqueueSnackbar } from 'twenty-sdk';
+import { useEffect } from 'react';
+
+const SyncTracker = () => {
+ const recordId = useRecordId();
+
+ useEffect(() => {
+ enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
+ }, [recordId]);
+
+ return null;
+};
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'sync-tracker',
+ description: 'Tracks record views silently',
+ isHeadless: true,
+ component: SyncTracker,
+});
+```
+
+Protože komponenta vrací `null`, Twenty přeskočí vykreslení kontejneru — v rozvržení se neobjeví žádné prázdné místo. Komponenta má však stále přístup ke všem hookům a API komunikace s hostitelem.
+
+#### Přístup k běhovému kontextu
+
+Uvnitř komponenty použijte hooky SDK pro přístup k aktuálnímu uživateli, záznamu a instanci komponenty:
+
+```tsx src/front-components/record-info.tsx
+import {
+ defineFrontComponent,
+ useUserId,
+ useRecordId,
+ useFrontComponentId,
+} from 'twenty-sdk';
+
+const RecordInfo = () => {
+ const userId = useUserId();
+ const recordId = useRecordId();
+ const componentId = useFrontComponentId();
+
+ return (
+
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
+ name: 'record-info',
+ component: RecordInfo,
+});
+```
+
+Dostupné hooky:
+
+| Hook | Vrací | Popis |
+| --------------------------------------------- | -------------------- | ------------------------------------------------------------ |
+| `useUserId()` | `string` nebo `null` | ID aktuálního uživatele |
+| `useRecordId()` | `string` nebo `null` | ID aktuálního záznamu (pokud je umístěna na stránce záznamu) |
+| `useFrontComponentId()` | `string` | ID této instance komponenty |
+| `useFrontComponentExecutionContext(selector)` | různé | Přístup k úplnému kontextu běhu pomocí selektorové funkce |
+
+#### API komunikace s hostitelem
+
+Frontendové komponenty mohou pomocí funkcí z `twenty-sdk` vyvolávat navigaci, modály a oznámení:
+
+| Funkce | Popis |
+| ----------------------------------------------- | ------------------------------ |
+| `navigate(to, params?, queryParams?, options?)` | Přejít na stránku v aplikaci |
+| `openSidePanelPage(params)` | Otevřít postranní panel |
+| `closeSidePanel()` | Zavře postranní panel |
+| `openCommandConfirmationModal(params)` | Zobrazit potvrzovací dialog |
+| `enqueueSnackbar(params)` | Zobrazit oznámení typu toast |
+| `unmountFrontComponent()` | Odmontovat komponentu |
+| `updateProgress(progress)` | Aktualizovat indikátor průběhu |
+
+#### Možnosti příkazu
+
+Přidání pole `command` do `defineFrontComponent` zaregistruje komponentu v příkazovém menu (Cmd+K). Pokud je `isPinned` nastaveno na `true`, zobrazí se také jako tlačítko rychlé akce v pravém horním rohu stránky.
+
+| Pole | Povinné | Popis |
+| --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `universalIdentifier` | Ano | Stabilní jedinečné ID pro příkaz |
+| `label` | Ano | Plný popisek zobrazený v příkazovém menu (Cmd+K) |
+| `shortLabel` | Ne | Kratší popisek zobrazený na připnutém tlačítku rychlé akce |
+| `icon` | Ne | Název ikony zobrazený vedle popisku (např. `'IconBolt'`, `'IconSend'`) |
+| `isPinned` | Ne | Pokud je `true`, zobrazí příkaz jako tlačítko rychlé akce v pravém horním rohu stránky |
+| `availabilityType` | Ne | Určuje, kde se příkaz zobrazuje: `'GLOBAL'` (vždy dostupné), `'RECORD_SELECTION'` (pouze když jsou vybrány záznamy) nebo `'FALLBACK'` (zobrazeno, když neodpovídají žádné jiné příkazy) |
+| `availabilityObjectUniversalIdentifier` | Ne | Omezí příkaz na stránky konkrétního typu objektu (např. pouze u záznamů Company) |
+| `conditionalAvailabilityExpression` | Ne | Logický výraz pro dynamické řízení, zda je příkaz viditelný (viz níže) |
+
+#### Výrazy podmíněné dostupnosti
+
+Pole `conditionalAvailabilityExpression` vám umožní řídit viditelnost příkazu na základě aktuálního kontextu stránky. Pro sestavení výrazů importujte typované proměnné a operátory z `twenty-sdk`:
+
+```tsx
+import {
+ defineFrontComponent,
+ pageType,
+ numberOfSelectedRecords,
+ objectPermissions,
+ everyEquals,
+ isDefined,
+} from 'twenty-sdk';
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'bulk-action',
+ component: BulkAction,
+ command: {
+ universalIdentifier: '...',
+ label: 'Bulk Update',
+ availabilityType: 'RECORD_SELECTION',
+ conditionalAvailabilityExpression: everyEquals(
+ objectPermissions,
+ 'canUpdateObjectRecords',
+ true,
+ ),
+ },
+});
+```
+
+**Kontextové proměnné** — reprezentují aktuální stav stránky:
+
+| Proměnná | Typ | Popis |
+| ------------------------------ | --------- | -------------------------------------------------------------------- |
+| `pageType` | `string` | Aktuální typ stránky (např. `'RecordIndexPage'`, `'RecordShowPage'`) |
+| `isInSidePanel` | `boolean` | Zda je komponenta vykreslena v postranním panelu |
+| `numberOfSelectedRecords` | `number` | Počet aktuálně vybraných záznamů |
+| `isSelectAll` | `boolean` | Zda je aktivní "vybrat vše" |
+| `selectedRecords` | `array` | Vybrané objekty záznamů |
+| `favoriteRecordIds` | `array` | ID oblíbených záznamů |
+| `objectPermissions` | `object` | Oprávnění pro aktuální typ objektu |
+| `targetObjectReadPermissions` | `object` | Oprávnění ke čtení pro cílový objekt |
+| `targetObjectWritePermissions` | `object` | Oprávnění k zápisu pro cílový objekt |
+| `featureFlags` | `object` | Aktivní příznaky funkcí |
+| `objectMetadataItem` | `object` | Metadata aktuálního typu objektu |
+| `hasAnySoftDeleteFilterOnView` | `boolean` | Zda má aktuální zobrazení filtr soft-delete |
+
+**Operátory** — kombinují proměnné do logických výrazů:
+
+| Operátor | Popis |
+| ----------------------------------- | -------------------------------------------------------------------- |
+| `isDefined(value)` | `true`, pokud hodnota není null/undefined |
+| `isNonEmptyString(value)` | `true`, pokud je hodnota neprázdný řetězec |
+| `includes(array, value)` | `true`, pokud pole obsahuje danou hodnotu |
+| `includesEvery(array, prop, value)` | `true`, pokud vlastnost každé položky zahrnuje danou hodnotu |
+| `every(array, prop)` | `true`, pokud je vlastnost u každé položky pravdivá (truthy) |
+| `everyDefined(array, prop)` | `true`, pokud je vlastnost definována u každé položky |
+| `everyEquals(array, prop, value)` | `true`, pokud se vlastnost rovná hodnotě u každé položky |
+| `some(array, prop)` | `true`, pokud je vlastnost pravdivá (truthy) alespoň u jedné položky |
+| `someDefined(array, prop)` | `true`, pokud je vlastnost definována alespoň u jedné položky |
+| `someEquals(array, prop, value)` | `true`, pokud se vlastnost rovná hodnotě alespoň u jedné položky |
+| `someNonEmptyString(array, prop)` | `true`, pokud je vlastnost neprázdný řetězec alespoň u jedné položky |
+| `none(array, prop)` | `true`, pokud je vlastnost u všech položek nepravdivá (falsy) |
+| `noneDefined(array, prop)` | `true`, pokud je vlastnost u všech položek nedefinovaná |
+| `noneEquals(array, prop, value)` | `true`, pokud se vlastnost nerovná hodnotě u žádné položky |
+
+#### Veřejná aktiva
+
+Frontendové komponenty mohou přistupovat k souborům ze složky aplikace `public/` pomocí `getPublicAssetUrl`:
+
+```tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk';
+
+const Logo = () => User: {userId}
+Record: {recordId ?? 'No record context'}
+Component: {componentId}
+;
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'logo',
+ component: Logo,
+});
+```
+
+Podrobnosti viz [sekce veřejných aktiv](#accessing-public-assets-with-getpublicasseturl).
+
+#### Styling
+
+Frontendové komponenty podporují více přístupů ke stylování. Můžete použít:
+
+* **Inline styly** — `style={{ color: 'red' }}`
+* **Komponenty Twenty UI** — import z `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar a další)
+* **Emotion** — CSS-in-JS s `@emotion/react`
+* **Styled-components** — vzory `styled.div`
+* **Tailwind CSS** — utilitní třídy
+* **Jakákoli CSS-in-JS knihovna** kompatibilní s Reactem
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { Button, Tag, Status } from 'twenty-sdk/ui';
+
+const StyledWidget = () => {
+ return (
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
+ name: 'styled-widget',
+ component: StyledWidget,
+});
+```
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### Jak funguje bundlování + +Krok sestavení (`yarn twenty dev` nebo `yarn twenty build`) používá esbuild k vytvoření jediného samostatného souboru pro každou logickou funkci a každou frontendovou komponentu. Všechny importované balíčky jsou vloženy přímo do bundlu. + +**Logické funkce** běží v prostředí Node.js. Vestavěné moduly Node (`fs`, `path`, `crypto`, `http` atd.) jsou k dispozici a není je třeba instalovat. + +**Frontendové komponenty** běží ve Web Workeru. Vestavěné moduly Node nejsou k dispozici — pouze prohlížečová API a balíčky npm, které fungují v prohlížečovém prostředí. + +V obou prostředích jsou jako předpřipravené moduly k dispozici `twenty-client-sdk/core` a `twenty-client-sdk/metadata` — nejsou součástí bundlu, ale server je za běhu načítá. + +## Generování entit pomocí `yarn twenty add` + +Místo ručního vytváření souborů entit můžete použít interaktivní generátor: + +```bash filename="Terminal" +yarn twenty add +``` + +Požádá vás o výběr typu entity a provede vás požadovanými poli. Vygeneruje soubor připravený k použití se stabilním `universalIdentifier` a správným voláním `defineEntity()`. + +Můžete také předat typ entity přímo a přeskočit první dotaz: + +```bash filename="Terminal" +yarn twenty add object +yarn twenty add logicFunction +yarn twenty add frontComponent +``` + +### Dostupné typy entit + +| Typ entity | Příkaz | Vygenerovaný soubor | +| ------------------------- | ------------------------------------ | ------------------------------------- | +| Objekt | `yarn twenty add object` | `src/objects/
+
+
+
+## Step 3: Sign in to your workspace
+
+Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+## Step 4: Authorize the app
+
+After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
+
+Click **Authorize** to continue.
+
+
+
+
+
+
+Once authorized, your terminal will confirm that everything is set up.
+
+
+
+
+
+
+## Step 5: Start developing
+
+Go into your new app folder and start the development server:
```bash filename="Terminal"
-# Add a new entity to your application (guided)
-yarn twenty add
-
-# Watch your application's function logs
-yarn twenty function:logs
-
-# Execute a function by name
-yarn twenty function:execute -n my-function -p '{"name": "test"}'
-
-# Execute the pre-install function
-yarn twenty function:execute --preInstall
-
-# Execute the post-install function
-yarn twenty function:execute --postInstall
-
-# Uninstall the application from the current workspace
-yarn twenty uninstall
-
-# Display commands' help
-yarn twenty help
+cd my-twenty-app
+yarn twenty dev
```
-Viz také: referenční stránky CLI pro [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) a [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
+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.
-## Struktura projektu (vytvořená scaffolderem)
+For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
-Když spustíte `npx create-twenty-app@latest my-twenty-app`, scaffolder:
+```bash filename="Terminal"
+yarn twenty dev --verbose
+```
-* Zkopíruje minimální základní aplikaci do `my-twenty-app/`
-* Přidá lokální závislost `twenty-sdk` a konfiguraci pro Yarn 4
-* Vytvoří konfigurační soubory a skripty napojené na `twenty` CLI
-* Vygeneruje základní soubory (konfigurace aplikace, výchozí role funkcí, předinstalační a postinstalační funkce) a k nim ukázkové soubory podle zvoleného režimu generování kostry
+
+
+
+
+
+## Step 6: See your app in 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**:
+
+
+
+
+
+
+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.
+
+
+
+
+
+
+Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
+
+
+
+
+
+
+Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
+
+
+
+
+
+
+You are all set! Edit any file in `src/` and the changes will be picked up automatically.
+
+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.
+
+---
+
+## Project structure
+
+The scaffolder generates the following file structure (shown with `--exhaustive` mode, which includes examples for every entity type):
```text filename="my-twenty-app/"
my-twenty-app/
@@ -83,124 +152,238 @@ my-twenty-app/
install-state.gz
.oxlintrc.json
tsconfig.json
+ tsconfig.spec.json # TypeScript config for tests
+ vitest.config.ts # Vitest test runner configuration
+ LLMS.md
README.md
- public/ # Public assets folder (images, fonts, etc.)
+ .github/
+ └── workflows/
+ └── ci.yml # GitHub Actions CI workflow
+ public/ # Public assets (images, fonts, etc.)
src/
- ├── application-config.ts # Required - main application configuration
+ ├── application-config.ts # Required — main application configuration
+ ├── __tests__/
+ │ ├── setup-test.ts # Test setup (server health check, config)
+ │ └── app-install.integration-test.ts # Example integration test
├── roles/
- │ └── default-role.ts # Default role for logic functions
+ │ └── default-role.ts # Default role for logic functions
├── objects/
- │ └── example-object.ts # Example custom object definition
+ │ └── example-object.ts # Example custom object definition
├── fields/
- │ └── example-field.ts # Example standalone field definition
+ │ └── example-field.ts # Example standalone field definition
├── logic-functions/
- │ ├── hello-world.ts # Example logic function
- │ ├── pre-install.ts # Pre-install logic function
- │ └── post-install.ts # Post-install logic function
+ │ ├── hello-world.ts # Example logic function
+ │ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
+ │ ├── pre-install.ts # Runs before installation
+ │ └── post-install.ts # Runs after installation
├── front-components/
- │ └── hello-world.tsx # Example front component
+ │ └── hello-world.tsx # Example front component
+ ├── page-layouts/
+ │ └── example-record-page-layout.ts # Example page layout with front component
├── views/
- │ └── example-view.ts # Example saved view definition
+ │ └── example-view.ts # Example saved view definition
├── navigation-menu-items/
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
- └── skills/
- └── example-skill.ts # Example AI agent skill definition
+ ├── skills/
+ │ └── example-skill.ts # Example AI agent skill definition
+ └── agents/
+ └── example-agent.ts # Example AI agent definition
```
-S volbou `--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`).
+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.
-V kostce:
+### Key files
-* **package.json**: Deklaruje název aplikace, verzi, engines (Node 24+, Yarn 4) a přidává `twenty-sdk` plus skript `twenty`, který deleguje na lokální `twenty` CLI. Spusťte `yarn twenty help` pro výpis všech dostupných příkazů.
-* **.gitignore**: Ignoruje běžné artefakty jako `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, složky s coverage, soubory s logy a soubory `.env*`.
-* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Zamykají a konfigurují nástrojový řetězec Yarn 4 používaný projektem.
-* **.nvmrc**: Fixuje verzi Node.js požadovanou projektem.
-* **.oxlintrc.json** a **tsconfig.json**: Poskytují lintování a konfiguraci TypeScriptu pro zdrojové soubory vaší aplikace v TypeScriptu.
-* **README.md**: Krátké README v kořeni aplikace se základními pokyny.
-* **public/**: Složka pro ukládání veřejných prostředků (obrázky, písma, statické soubory), které bude vaše aplikace poskytovat. Soubory umístěné zde se během synchronizace nahrají a jsou za běhu dostupné.
-* **src/**: Hlavní místo, kde definujete svou aplikaci jako kód
+| 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. |
-### Detekce entit
+## Managing remotes
-SDK detekuje entity analýzou vašich souborů TypeScript a hledá volání **`export default define
+
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
-});
-```
-
-Hlavní body:
-
-* Frontendové komponenty jsou React komponenty, které se vykreslují v izolovaných kontextech v rámci Twenty.
-* Pole `component` odkazuje na vaši React komponentu.
-* Komponenty se během `yarn twenty dev` automaticky sestaví a synchronizují.
-
-Nové frontendové komponenty můžete vytvořit dvěma způsoby:
-
-* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat novou frontendovou komponentu.
-* **Ruční**: Vytvořte nový soubor `.tsx` a použijte `defineFrontComponent()`, podle stejného vzoru.
-
-#### Kde lze použít front komponenty
-
-Front komponenty se mohou vykreslovat na dvou místech v rámci Twenty:
-
-* **Postranní panel** — Ne-headless front komponenty se otevírají v pravém postranním panelu. Toto je výchozí chování, když je front komponenta vyvolána z menu příkazů.
-* **Widgety (nástěnky a stránky záznamů)** — Front komponenty lze vkládat jako widgety do rozložení stránek. Při konfiguraci nástěnky nebo rozložení stránky záznamu mohou uživatelé přidat widget front komponenty.
-
-#### Headless vs. ne-headless
-
-Front komponenty existují ve dvou režimech vykreslování řízených volbou `isHeadless`:
-
-**Ne-headless (výchozí)** — Komponenta vykreslí viditelné uživatelské rozhraní. Po vyvolání z menu příkazů se otevře v postranním panelu. Toto je výchozí chování, když je `isHeadless` `false` nebo když tato volba není uvedena.
-
-**Headless** — Komponenta se neviditelně inicializuje na pozadí. Neotevírá postranní panel. Headless komponenty jsou určené pro akce, které provedou logiku a poté se odpojí — například spuštění asynchronního úkolu, navigaci na stránku nebo zobrazení potvrzovacího modálního okna. Přirozeně se hodí ke komponentám SDK Command popsaným níže.
-
-```typescript
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-action',
- description: 'Runs an action without opening the side panel',
- component: MyAction,
- isHeadless: true,
- command: {
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
- label: 'Run my action',
- },
-});
-```
-
-#### Přidávání položek menu příkazů
-
-Aby se front komponenta zobrazila jako položka v menu příkazů Twenty, přidejte vlastnost `command` k `defineFrontComponent()`. Když uživatelé otevřou menu příkazů (Cmd+K / Ctrl+K), položka se zobrazí a po kliknutí spustí front komponentu.
-
-Objekt `command` přijímá následující pole:
-
-| Pole | Typ | Popis |
-| --------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | `string` (povinné) | Jedinečné ID položky menu příkazů |
-| `štítek` | `string` (povinné) | Text zobrazený v menu příkazů |
-| `ikona` | `string` (nepovinné) | Název ikony (např. `'IconSparkles'`) |
-| `isPinned` | `boolean` (nepovinné) | Zda je příkaz připnutý nahoře v menu |
-| `availabilityType` | `'GLOBAL' \| 'RECORD_SELECTION'` (nepovinné) | `GLOBAL` zobrazuje příkaz všude; `RECORD_SELECTION` jej zobrazuje pouze v kontextech záznamů |
-| `availabilityObjectUniversalIdentifier` | `string` (nepovinné) | Omezí příkaz na konkrétní typ objektu (např. Person) |
-
-Zde je příklad z aplikace pro nahrávání hovorů, který přidává příkaz omezený na záznamy typu Person:
-
-```typescript
-import { defineFrontComponent } from 'twenty-sdk';
-
-export default defineFrontComponent({
- universalIdentifier: 'c3d4e5f6-a7b8-9012-cdef-123456789012',
- name: 'Summarize Person Call Recordings',
- description: 'Generates a summary of call recordings for a person',
- component: SummarizePersonRecordings,
- command: {
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-234567890123',
- label: 'Summarize call recordings',
- icon: 'IconSparkles',
- isPinned: false,
- availabilityType: 'RECORD_SELECTION',
- availabilityObjectUniversalIdentifier:
- '20202020-e674-48e5-a542-72570eee7213',
- },
-});
-```
-
-Když se příkaz synchronizuje, objeví se v menu příkazů. Pokud je front komponenta ne-headless, otevře se postranní panel s komponentou vykreslenou uvnitř. Pokud je headless, komponenta se inicializuje na pozadí a provede svou logiku.
-
-#### Komponenty SDK Command
-
-Balíček `twenty-sdk` poskytuje čtyři pomocné komponenty Command navržené pro headless front komponenty. Každá komponenta při připojení provede akci, chyby zpracuje zobrazením oznámení ve snackbaru a po dokončení automaticky odpojí front komponentu.
-
-Importujte je z `twenty-sdk/command`:
-
-* **`Command`** — Spustí asynchronní callback přes prop `execute`.
-* **`CommandLink`** — Naviguje na cestu v aplikaci. Props: `to`, `params`, `queryParams`, `options`.
-* **`CommandModal`** — Otevře potvrzovací modální okno. Pokud uživatel potvrdí, provede callback `execute`. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
-* **`CommandOpenSidePanelPage`** — Otevře konkrétní stránku postranního panelu. Props: `page`, `pageTitle`, `pageIcon`.
-
-Zde je kompletní příklad headless front komponenty, která pomocí `Command` spouští akci z menu příkazů:
-
-```typescript
-// src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk';
-import { Command } from 'twenty-sdk/command';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const RunAction = () => {
- const execute = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- createTask: {
- __args: { data: { title: 'Created by my app' } },
- id: true,
- },
- });
- };
-
- return My Custom Widget
-This is a custom front component for Twenty.
-
-
- );
-};
-```
-
-Kontext je reaktivní — pokud se okolní záznam změní, hooky automaticky vrátí aktualizované hodnoty.
-
-#### Funkce hostitelského API
-
-Front komponenty běží v izolovaném sandboxu, ale mohou interagovat s UI Twenty prostřednictvím sady funkcí poskytovaných hostitelem. Importujte je přímo z `twenty-sdk`:
-
-```typescript
-import {
- navigate,
- closeSidePanel,
- enqueueSnackbar,
- unmountFrontComponent,
- openSidePanelPage,
- openCommandConfirmationModal,
-} from 'twenty-sdk';
-```
-
-| Funkce | Signatura | Popis |
-| ------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `navigovat` | `(to, params?, queryParams?, options?) => PromiseRecord: {recordId ?? 'none'}
-User: {userId ?? 'anonymous'}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Dovednosti
-
-Dovednosti definují znovupoužitelné pokyny a schopnosti, které mohou agenti AI používat ve vašem pracovním prostoru. K definování dovedností s vestavěnou validací použijte `defineSkill()`:
-
-```typescript
-// src/skills/example-skill.ts
-import { defineSkill } from 'twenty-sdk';
-
-export default defineSkill({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-outreach',
- label: 'Sales Outreach',
- description: 'Guides the AI agent through a structured sales outreach process',
- icon: 'IconBrain',
- content: `You are a sales outreach assistant. When reaching out to a prospect:
-1. Research the company and recent news
-2. Identify the prospect's role and likely pain points
-3. Draft a personalized message referencing specific details
-4. Keep the tone professional but conversational`,
-});
-```
-
-Hlavní body:
-
-* `name` je jedinečný identifikátor dovednosti (doporučuje se kebab-case).
-* `label` je uživatelsky čitelný název zobrazovaný v UI.
-* `content` obsahuje pokyny dovednosti — je to text, který agent AI používá.
-* `icon` (volitelné) nastavuje ikonu zobrazovanou v UI.
-* `description` (volitelné) poskytuje doplňující kontext o účelu dovednosti.
-
-Nové dovednosti můžete vytvářet dvěma způsoby:
-
-* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat novou dovednost.
-* **Ruční**: Vytvořte nový soubor a použijte `defineSkill()` podle stejného vzoru.
-
-### Agenti
-
-Agenti jsou AI agenti se systémovými prompty, kteří mohou fungovat ve vašem pracovním prostoru. K definování agentů s vestavěnou validací použijte `defineAgent()`:
-
-```typescript
-// src/agents/example-agent.ts
-import { defineAgent } from 'twenty-sdk';
-
-export default defineAgent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-assistant',
- label: 'Sales Assistant',
- description: 'An AI agent that helps with sales tasks',
- icon: 'IconRobot',
- prompt: `You are a sales assistant. Help users with:
-1. Researching prospects and companies
-2. Drafting personalized outreach messages
-3. Tracking follow-ups and next steps
-4. Analyzing deal pipeline and suggesting actions`,
-});
-```
-
-Hlavní body:
-
-* `name` je jedinečný identifikátor agenta (doporučuje se kebab-case).
-* `label` je uživatelsky čitelný název zobrazovaný v UI.
-* `prompt` obsahuje systémový prompt — jde o instrukční text, který určuje chování agenta.
-* `icon` (volitelné) nastavuje ikonu zobrazovanou v UI.
-* `description` (volitelné) poskytuje doplňující kontext o účelu agenta.
-
-Nové agenty můžete vytvářet dvěma způsoby:
-
-* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat nového agenta.
-* **Ruční**: Vytvořte nový soubor a použijte `defineAgent()` podle stejného vzoru.
-
-### Generované typované klienty
-
-Dva typované klienty jsou automaticky vygenerovány pomocí `yarn twenty dev` a uloženy do `node_modules/twenty-sdk/clients` podle schématu vašeho pracovního prostoru:
-
-* **`CoreApiClient`** — provádí dotazy na endpoint `/graphql` za účelem získání dat pracovního prostoru
-* **`MetadataApiClient`** — odesílá dotazy na endpoint `/metadata` pro konfiguraci pracovního prostoru a nahrávání souborů
-
-```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-
-const client = new CoreApiClient();
-const { me } = await client.query({ me: { id: true, displayName: true } });
-
-const metadataClient = new MetadataApiClient();
-const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
-```
-
-`CoreApiClient` se automaticky znovu generuje pomocí `yarn twenty dev` kdykoli se změní vaše objekty nebo pole. `MetadataApiClient` je v SDK k dispozici již předem sestavený.
-
-#### Běhové přihlašovací údaje v logických funkcích
-
-Když vaše funkce běží na Twenty, platforma před spuštěním kódu vloží přihlašovací údaje jako proměnné prostředí:
-
-* `TWENTY_API_URL`: Základní URL Twenty API, na které vaše aplikace cílí.
-* `TWENTY_API_KEY`: Krátkodobý klíč s rozsahem omezeným na výchozí roli funkce vaší aplikace.
-
-Poznámky:
-
-* Není nutné předávat URL ani klíč API vygenerovanému klientovi. Za běhu čte `TWENTY_API_URL` a `TWENTY_API_KEY` z process.env.
-* Oprávnění klíče API jsou určena rolí odkazovanou ve vašem `application-config.ts` prostřednictvím `defaultRoleUniversalIdentifier`. Toto je výchozí role používaná logickými funkcemi vaší aplikace.
-* Aplikace mohou definovat role podle principu nejmenších oprávnění. Udělte pouze oprávnění, která vaše funkce potřebují, a poté nastavte `defaultRoleUniversalIdentifier` na univerzální identifikátor této role.
-
-#### Nahrávání souborů
-
-`MetadataApiClient` obsahuje metodu `uploadFile` pro připojování souborů k polím typu souboru u objektů ve vašem pracovním prostoru. Protože standardní klienti GraphQL nativně nepodporují nahrávání souborů pomocí multipart, klient poskytuje tuto speciální metodu, která interně implementuje [specifikaci multipart požadavků GraphQL](https://github.com/jaydenseric/graphql-multipart-request-spec).
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-import * as fs from 'fs';
-
-const metadataClient = new MetadataApiClient();
-
-const fileBuffer = fs.readFileSync('./invoice.pdf');
-
-const uploadedFile = await metadataClient.uploadFile(
- fileBuffer, // file contents as a Buffer
- 'invoice.pdf', // filename
- 'application/pdf', // MIME type (defaults to 'application/octet-stream')
- '58a0a314-d7ea-4865-9850-7fb84e72f30b', // field universal identifier
-);
-
-console.log(uploadedFile);
-// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
-```
-
-Signatura metody:
-
-```typescript
-uploadFile(
- fileBuffer: Buffer,
- filename: string,
- contentType: string,
- fieldMetadataUniversalIdentifier: string,
-): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
-```
-
-| Parametr | Typ | Popis |
-| ---------------------------------- | -------- | --------------------------------------------------------------------------- |
-| `fileBuffer` | `Buffer` | Surový obsah souboru |
-| `filename` | `string` | Název souboru (používá se pro ukládání a zobrazení) |
-| `contentType` | `string` | Typ MIME souboru (pokud je vynechán, výchozí je `application/octet-stream`) |
-| `fieldMetadataUniversalIdentifier` | `string` | `universalIdentifier` pole typu souboru ve vašem objektu |
-
-Hlavní body:
-
-* Metoda `uploadFile` je k dispozici v `MetadataApiClient`, protože mutaci nahrávání obsluhuje endpoint `/metadata`.
-* Používá `universalIdentifier` pole (nikoli jeho ID specifické pro pracovní prostor), takže váš kód pro nahrávání funguje ve všech pracovních prostorech, kde je vaše aplikace nainstalována — v souladu s tím, jak aplikace odkazují na pole všude jinde.
-* Vrácená hodnota `url` je podepsaná adresa URL, kterou můžete použít k přístupu k nahranému souboru.
-
-### Příklad Hello World
-
-Prozkoumejte minimalistický end-to-end příklad, který demonstruje objekty, logické funkce, frontendové komponenty a více spouštěčů [zde](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
-
-## Sestavení vaší aplikace
-
-Jakmile vyvinete svou aplikaci pomocí `app:dev`, použijte `app:build` k jejímu zkompilování do distribučního balíčku.
-
-```bash filename="Terminal"
-# Sestavte aplikaci (výstup se uloží do .twenty/output/)
-yarn twenty build
-
-# Sestavte a vytvořte tarball (.tgz) pro distribuci
-yarn twenty build --tarball
-```
-
-Proces sestavení:
-
-1. **Parsuje a ověřuje manifest** — čte všechny entity `defineX()` z vašich zdrojových souborů a ověřuje strukturu manifestu.
-2. **Kompiluje logické funkce a frontendové komponenty** — slučuje zdrojové soubory TypeScriptu do ESM souborů `.mjs` pomocí esbuild.
-3. **Generuje kontrolní součty** — vypočítá MD5 hashe pro každý sestavený soubor, které jsou v manifestu uloženy jako `builtHandlerChecksum` / `builtComponentChecksum`.
-4. **Vygeneruje typovaného klienta API** — prozkoumá schéma GraphQL a vygeneruje typované klienty `CoreApiClient` a `MetadataApiClient`.
-5. **Spustí kontrolu typů TypeScriptu** — spustí `tsc --noEmit`, aby zachytil chyby typů před publikováním.
-6. **Znovu sestaví s vygenerovaným klientem** — provede druhý průchod kompilace, aby byly zahrnuty typy vygenerovaného klienta.
-7. **Volitelně vytvoří tarball** — pokud je předán `--tarball`, spustí `npm pack` a vytvoří soubor `.tgz` připravený k distribuci.
-
-Výstup sestavení v `.twenty/output/` obsahuje:
-
-```text
-.twenty/output/
-├── manifest.json # Manifest with checksums for all built files
-├── package.json # Copied from app root
-├── yarn.lock # Copied from app root
-├── src/
-│ ├── logic-functions/ # Compiled .mjs logic function files
-│ └── front-components/ # Compiled .mjs front component files
-├── public/ # Static assets (if any)
-└── my-app-1.0.0.tgz # Only with --tarball flag
-```
-
-| Možnost | Popis |
-| ----------- | ----------------------------------------------------- |
-| `[appPath]` | Cesta k adresáři aplikace (výchozí: aktuální adresář) |
-| `--tarball` | Také zabalí výstup do tarballu `.tgz` |
-
-## Publikování vaší aplikace
-
-Použijte `app:publish` k distribuci své aplikace — buď do registru npm, nebo přímo na server Twenty.
-
-### Publikovat na npm (výchozí)
-
-```bash filename="Terminal"
-# Publikujte na npm (vyžaduje přihlášení k npm)
-yarn twenty publish
-
-# Publikujte s dist-tagem (např. beta, next)
-yarn twenty publish --tag beta
-```
-
-Tímto se aplikace sestaví a spustí se `npm publish` z adresáře `.twenty/output/`. Publikovaný balíček pak může být nainstalován z tržiště Twenty jakýmkoli pracovním prostorem.
-
-### Publikovat na server Twenty
-
-```bash filename="Terminal"
-# Publikujte přímo na server Twenty
-yarn twenty publish --server https://app.twenty.com
-```
-
-Tímto se aplikace sestaví s tarballem, nahraje se na server pomocí GraphQL mutace `uploadAppTarball` a v jednom kroku se spustí instalace. To je užitečné pro soukromá nasazení nebo testování proti konkrétnímu serveru.
-
-| Možnost | Popis |
-| ----------------- | ------------------------------------------------------------------ |
-| `[appPath]` | Cesta k adresáři aplikace (výchozí: aktuální adresář) |
-| `--server Archive this record?
- -
-
);
};
export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
+ universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+ name: 'hello-world',
+ description: 'A simple front component',
+ component: HelloWorld,
+ command: {
+ universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+ shortLabel: 'Hello',
+ label: 'Hello World',
+ icon: 'IconBolt',
+ isPinned: true,
+ availabilityType: 'GLOBAL',
+ },
});
```
-Hauptpunkte:
+After syncing with `yarn twenty dev`, the quick action appears in the top-right corner of the page:
-* Frontend-Komponenten sind React-Komponenten, die in isolierten Kontexten innerhalb von Twenty gerendert werden.
-* Das Feld `component` verweist auf Ihre React-Komponente.
-* Komponenten werden während `yarn twenty dev` automatisch gebaut und synchronisiert.
+My Custom Widget
-This is a custom front component for Twenty.
+Hello from my app!
+This component renders inside Twenty.
+
+
-Sie können neue Frontend-Komponenten auf zwei Arten erstellen:
+Click it to render the component inline.
-* **Generiert**: Führen Sie `yarn twenty add` aus und wählen Sie die Option zum Hinzufügen einer neuen Frontend-Komponente.
-* **Manuell**: Erstellen Sie eine neue `.tsx`-Datei und verwenden Sie `defineFrontComponent()` nach demselben Muster.
+{/* TODO: add screenshot of the rendered front component */}
-### Fähigkeiten
+#### Configuration fields
+
+| Feld | Erforderlich | Beschreibung |
+| --------------------- | ------------ | ----------------------------------------------------------------------------------- |
+| `universalIdentifier` | Ja | Stable unique ID for this component |
+| `component` | Ja | A React component function |
+| `name` | Nein | Display name |
+| `description` | Nein | Description of what the component does |
+| `isHeadless` | Nein | Set to `true` if the component has no visible UI (see below) |
+| `command` | Nein | Register the component as a command (see [command options](#command-options) below) |
+
+#### Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See the [definePageLayout](#definepagelayout) section for details.
+
+#### Headless components (`isHeadless: true`)
+
+Headless components render no visible UI but still run React logic. This is useful for **effect components** — components that perform side effects when mounted, such as syncing data, starting a timer, listening to events, or triggering a notification.
+
+```tsx src/front-components/sync-tracker.tsx
+import { defineFrontComponent, useRecordId, enqueueSnackbar } from 'twenty-sdk';
+import { useEffect } from 'react';
+
+const SyncTracker = () => {
+ const recordId = useRecordId();
+
+ useEffect(() => {
+ enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
+ }, [recordId]);
+
+ return null;
+};
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'sync-tracker',
+ description: 'Tracks record views silently',
+ isHeadless: true,
+ component: SyncTracker,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+#### Accessing runtime context
+
+Inside your component, use SDK hooks to access the current user, record, and component instance:
+
+```tsx src/front-components/record-info.tsx
+import {
+ defineFrontComponent,
+ useUserId,
+ useRecordId,
+ useFrontComponentId,
+} from 'twenty-sdk';
+
+const RecordInfo = () => {
+ const userId = useUserId();
+ const recordId = useRecordId();
+ const componentId = useFrontComponentId();
+
+ return (
+
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
+ name: 'record-info',
+ component: RecordInfo,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Beschreibung |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useRecordId()` | `string` or `null` | The current record's ID (when placed on a record page) |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | variiert | Access the full execution context with a selector function |
+
+#### Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Funktion | Beschreibung |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Seitenpanel schließen |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+#### Command options
+
+Adding a `command` field to `defineFrontComponent` registers the component in the command menu (Cmd+K). If `isPinned` is `true`, it also appears as a quick-action button in the top-right corner of the page.
+
+| Feld | Erforderlich | Beschreibung |
+| --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `universalIdentifier` | Ja | Stable unique ID for the command |
+| `label` | Ja | Full label shown in the command menu (Cmd+K) |
+| `shortLabel` | Nein | Shorter label displayed on the pinned quick-action button |
+| `icon` | Nein | Icon name displayed next to the label (e.g. `'IconBolt'`, `'IconSend'`) |
+| `isPinned` | Nein | When `true`, shows the command as a quick-action button in the top-right corner of the page |
+| `availabilityType` | Nein | Controls where the command appears: `'GLOBAL'` (always available), `'RECORD_SELECTION'` (only when records are selected), or `'FALLBACK'` (shown when no other commands match) |
+| `availabilityObjectUniversalIdentifier` | Nein | Restrict the command to pages of a specific object type (e.g. only on Company records) |
+| `conditionalAvailabilityExpression` | Nein | A boolean expression to dynamically control whether the command is visible (see below) |
+
+#### Conditional availability expressions
+
+The `conditionalAvailabilityExpression` field lets you control when a command is visible based on the current page context. Import typed variables and operators from `twenty-sdk` to build expressions:
+
+```tsx
+import {
+ defineFrontComponent,
+ pageType,
+ numberOfSelectedRecords,
+ objectPermissions,
+ everyEquals,
+ isDefined,
+} from 'twenty-sdk';
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'bulk-action',
+ component: BulkAction,
+ command: {
+ universalIdentifier: '...',
+ label: 'Bulk Update',
+ availabilityType: 'RECORD_SELECTION',
+ conditionalAvailabilityExpression: everyEquals(
+ objectPermissions,
+ 'canUpdateObjectRecords',
+ true,
+ ),
+ },
+});
+```
+
+**Context variables** — these represent the current state of the page:
+
+| Variable | Typ | Beschreibung |
+| ------------------------------ | --------- | ---------------------------------------------------------------- |
+| `pageType` | `string` | Current page type (e.g. `'RecordIndexPage'`, `'RecordShowPage'`) |
+| `isInSidePanel` | `boolean` | Whether the component is rendered in a side panel |
+| `numberOfSelectedRecords` | `number` | Number of currently selected records |
+| `isSelectAll` | `boolean` | Whether "select all" is active |
+| `selectedRecords` | `array` | The selected record objects |
+| `favoriteRecordIds` | `array` | IDs of favorited records |
+| `objectPermissions` | `object` | Permissions for the current object type |
+| `targetObjectReadPermissions` | `object` | Read permissions for the target object |
+| `targetObjectWritePermissions` | `object` | Write permissions for the target object |
+| `featureFlags` | `object` | Active feature flags |
+| `objectMetadataItem` | `object` | Metadata of the current object type |
+| `hasAnySoftDeleteFilterOnView` | `boolean` | Whether the current view has a soft-delete filter |
+
+**Operators** — combine variables into boolean expressions:
+
+| Operator | Beschreibung |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| `isDefined(value)` | `true` if the value is not null/undefined |
+| `isNonEmptyString(value)` | `true` if the value is a non-empty string |
+| `includes(array, value)` | `true` if the array contains the value |
+| `includesEvery(array, prop, value)` | `true` if every item's property includes the value |
+| `every(array, prop)` | `true` if the property is truthy on every item |
+| `everyDefined(array, prop)` | `true` if the property is defined on every item |
+| `everyEquals(array, prop, value)` | `true` if the property equals the value on every item |
+| `some(array, prop)` | `true` if the property is truthy on at least one item |
+| `someDefined(array, prop)` | `true` if the property is defined on at least one item |
+| `someEquals(array, prop, value)` | `true` if the property equals the value on at least one item |
+| `someNonEmptyString(array, prop)` | `true` if the property is a non-empty string on at least one item |
+| `none(array, prop)` | `true` if the property is falsy on every item |
+| `noneDefined(array, prop)` | `true` if the property is undefined on every item |
+| `noneEquals(array, prop, value)` | `true` if the property does not equal the value on any item |
+
+#### Public assets
+
+Front components can access files from the app's `public/` directory using `getPublicAssetUrl`:
+
+```tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk';
+
+const Logo = () => User: {userId}
+Record: {recordId ?? 'No record context'}
+Component: {componentId}
+;
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'logo',
+ component: Logo,
+});
+```
+
+See the [public assets section](#accessing-public-assets-with-getpublicasseturl) for details.
+
+#### Styling
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { Button, Tag, Status } from 'twenty-sdk/ui';
+
+const StyledWidget = () => {
+ return (
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
+ name: 'styled-widget',
+ component: StyledWidget,
+});
+```
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step (`yarn twenty dev` or `yarn twenty build`) uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Scaffolding entities with `yarn twenty add` + +Instead of creating entity files by hand, you can use the interactive scaffolder: + +```bash filename="Terminal" +yarn twenty add +``` + +This prompts you to pick an entity type and walks you through the required fields. It generates a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call. + +You can also pass the entity type directly to skip the first prompt: + +```bash filename="Terminal" +yarn twenty add object +yarn twenty add logicFunction +yarn twenty add frontComponent +``` + +### Available entity types + +| Entitätstyp | Befehl | Generated file | +| -------------------- | ------------------------------------ | ------------------------------------- | +| Objekt | `yarn twenty add object` | `src/objects/
+
+
+
+## Step 3: Sign in to your workspace
+
+Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+## Step 4: Authorize the app
+
+After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
+
+Click **Authorize** to continue.
+
+
+
+
+
+
+Once authorized, your terminal will confirm that everything is set up.
+
+
+
+
+
+
+## Step 5: Start developing
+
+Go into your new app folder and start the development server:
```bash filename="Terminal"
-# Add a new entity to your application (guided)
-yarn twenty add
-
-# Watch your application's function logs
-yarn twenty function:logs
-
-# Execute a function by name
-yarn twenty function:execute -n my-function -p '{"name": "test"}'
-
-# Execute the pre-install function
-yarn twenty function:execute --preInstall
-
-# Execute the post-install function
-yarn twenty function:execute --postInstall
-
-# Uninstall the application from the current workspace
-yarn twenty uninstall
-
-# Display commands' help
-yarn twenty help
+cd my-twenty-app
+yarn twenty dev
```
-Siehe auch: die CLI-Referenzseiten für [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) und [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
+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.
-## Projektstruktur (vom Scaffolder erzeugt)
+For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
-Wenn Sie `npx create-twenty-app@latest my-twenty-app` ausführen, erledigt der Scaffolder Folgendes:
+```bash filename="Terminal"
+yarn twenty dev --verbose
+```
-* Kopiert eine minimale Basisanwendung nach `my-twenty-app/`
-* Fügt eine lokale `twenty-sdk`-Abhängigkeit und die Yarn-4-Konfiguration hinzu
-* Erstellt Konfigurationsdateien und Skripte, die an die `twenty`-CLI angebunden sind
-* Erzeugt Kerndateien (Anwendungskonfiguration, Standardrolle für Logikfunktionen, Pre-Installations- und Post-Installationsfunktionen) sowie Beispieldateien entsprechend dem Scaffolding-Modus
+
+
+
+
+
+## Step 6: See your app in 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**:
+
+
+
+
+
+
+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.
+
+
+
+
+
+
+Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
+
+
+
+
+
+
+Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
+
+
+
+
+
+
+You are all set! Edit any file in `src/` and the changes will be picked up automatically.
+
+Head over to [Building Apps](/l/de/developers/extend/apps/building) for a detailed guide on creating objects, logic functions, front components, skills, and more.
+
+---
+
+## Project structure
+
+The scaffolder generates the following file structure (shown with `--exhaustive` mode, which includes examples for every entity type):
```text filename="my-twenty-app/"
my-twenty-app/
@@ -83,124 +152,238 @@ my-twenty-app/
install-state.gz
.oxlintrc.json
tsconfig.json
+ tsconfig.spec.json # TypeScript config for tests
+ vitest.config.ts # Vitest test runner configuration
+ LLMS.md
README.md
- public/ # Public assets folder (images, fonts, etc.)
+ .github/
+ └── workflows/
+ └── ci.yml # GitHub Actions CI workflow
+ public/ # Public assets (images, fonts, etc.)
src/
- ├── application-config.ts # Required - main application configuration
+ ├── application-config.ts # Required — main application configuration
+ ├── __tests__/
+ │ ├── setup-test.ts # Test setup (server health check, config)
+ │ └── app-install.integration-test.ts # Example integration test
├── roles/
- │ └── default-role.ts # Default role for logic functions
+ │ └── default-role.ts # Default role for logic functions
├── objects/
- │ └── example-object.ts # Example custom object definition
+ │ └── example-object.ts # Example custom object definition
├── fields/
- │ └── example-field.ts # Example standalone field definition
+ │ └── example-field.ts # Example standalone field definition
├── logic-functions/
- │ ├── hello-world.ts # Example logic function
- │ ├── pre-install.ts # Pre-install logic function
- │ └── post-install.ts # Post-install logic function
+ │ ├── hello-world.ts # Example logic function
+ │ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
+ │ ├── pre-install.ts # Runs before installation
+ │ └── post-install.ts # Runs after installation
├── front-components/
- │ └── hello-world.tsx # Example front component
+ │ └── hello-world.tsx # Example front component
+ ├── page-layouts/
+ │ └── example-record-page-layout.ts # Example page layout with front component
├── views/
- │ └── example-view.ts # Example saved view definition
+ │ └── example-view.ts # Example saved view definition
├── navigation-menu-items/
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
- └── skills/
- └── example-skill.ts # Example AI agent skill definition
+ ├── skills/
+ │ └── example-skill.ts # Example AI agent skill definition
+ └── agents/
+ └── example-agent.ts # Example AI agent definition
```
-Mit `--minimal` werden nur die Kerndateien erstellt (`application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` und `logic-functions/post-install.ts`).
+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.
-Auf hoher Ebene:
+### Key files
-* **package.json**: Deklariert den App-Namen, die Version und die Engines (Node 24+, Yarn 4) und fügt `twenty-sdk` sowie ein `twenty`-Skript hinzu, das an die lokale `twenty`-CLI delegiert. Führen Sie `yarn twenty help` aus, um alle verfügbaren Befehle aufzulisten.
-* **.gitignore**: Ignoriert übliche Artefakte wie `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, Coverage-Ordner, Logdateien und `.env*`-Dateien.
-* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Fixieren und konfigurieren die vom Projekt verwendete Yarn-4-Toolchain.
-* **.nvmrc**: Legt die vom Projekt erwartete Node.js-Version fest.
-* **.oxlintrc.json** und **tsconfig.json**: Stellen Linting und TypeScript-Konfiguration für die TypeScript-Quellen Ihrer App bereit.
-* **README.md**: Ein kurzes README im App-Root mit grundlegenden Anweisungen.
-* **public/**: Ein Ordner zum Speichern öffentlicher Assets (Bilder, Schriftarten, statische Dateien), die zusammen mit Ihrer Anwendung bereitgestellt werden. Hier abgelegte Dateien werden während der Synchronisierung hochgeladen und sind zur Laufzeit zugänglich.
-* **src/**: Der Hauptort, an dem Sie Ihre Anwendung als Code definieren
+| File / Folder | Zweck |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `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/` | Skills, die die KI-Agenten von Twenty erweitern. |
+| `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. |
-### Entitätserkennung
+## Managing remotes
-Das SDK erkennt Entitäten, indem es Ihre TypeScript-Dateien nach Aufrufen von **`export default define
+
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
-});
-```
-
-Hauptpunkte:
-
-* Frontend-Komponenten sind React-Komponenten, die in isolierten Kontexten innerhalb von Twenty gerendert werden.
-* Das Feld `component` verweist auf Ihre React-Komponente.
-* Komponenten werden während `yarn twenty dev` automatisch gebaut und synchronisiert.
-
-Sie können neue Frontend-Komponenten auf zwei Arten erstellen:
-
-* **Generiert**: Führen Sie `yarn twenty entity:add` aus und wählen Sie die Option zum Hinzufügen einer neuen Frontend-Komponente.
-* **Manuell**: Erstellen Sie eine neue `.tsx`-Datei und verwenden Sie `defineFrontComponent()` nach demselben Muster.
-
-#### Wo Front-Komponenten verwendet werden können
-
-Front-Komponenten können an zwei Stellen innerhalb von Twenty gerendert werden:
-
-* **Seitenpanel** — Nicht-Headless-Front-Komponenten werden im rechten Seitenpanel geöffnet. Dies ist das Standardverhalten, wenn eine Front-Komponente über das Befehlsmenü ausgelöst wird.
-* **Widgets (Dashboards und Datensatzseiten)** — Front-Komponenten können als Widgets in Seitenlayouts eingebettet werden. Beim Konfigurieren eines Dashboards oder eines Datensatzseiten-Layouts können Benutzer ein Front-Komponenten-Widget hinzufügen.
-
-#### Headless vs. Nicht-Headless
-
-Front-Komponenten gibt es in zwei Rendering-Modi, die durch die Option `isHeadless` gesteuert werden:
-
-**Nicht-Headless (Standard)** — Die Komponente rendert eine sichtbare UI. Wird sie über das Befehlsmenü ausgelöst, öffnet sie sich im Seitenpanel. Dies ist das Standardverhalten, wenn `isHeadless` `false` ist oder weggelassen wird.
-
-**Headless** — Die Komponente wird unsichtbar im Hintergrund gemountet. Sie öffnet das Seitenpanel nicht. Headless-Komponenten sind für Aktionen konzipiert, die Logik ausführen und sich anschließend selbst unmounten — zum Beispiel das Ausführen einer asynchronen Aufgabe, das Navigieren zu einer Seite oder das Anzeigen eines Bestätigungsdialogs. Sie lassen sich gut mit den unten beschriebenen SDK-Command-Komponenten kombinieren.
-
-```typescript
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-action',
- description: 'Runs an action without opening the side panel',
- component: MyAction,
- isHeadless: true,
- command: {
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
- label: 'Run my action',
- },
-});
-```
-
-#### Befehlsmenü-Einträge hinzufügen
-
-Damit eine Front-Komponente als Eintrag im Befehlsmenü von Twenty erscheint, fügen Sie die Eigenschaft `command` zu `defineFrontComponent()` hinzu. Wenn Benutzer das Befehlsmenü öffnen (Cmd+K / Ctrl+K), erscheint der Eintrag und löst beim Klicken die Front-Komponente aus.
-
-Das Objekt `command` akzeptiert die folgenden Felder:
-
-| Feld | Typ | Beschreibung |
-| --------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | `string` (erforderlich) | Eindeutige ID für den Befehlsmenü-Eintrag |
-| `beschriftung` | `string` (erforderlich) | Angezeigtes Label im Befehlsmenü |
-| `symbol` | `string` (optional) | Iconname (z. B. 'IconSparkles') |
-| `isPinned` | `boolean` (optional) | Ob der Befehl oben im Menü angeheftet ist |
-| `availabilityType` | `'GLOBAL' \| 'RECORD_SELECTION'` (optional) | `GLOBAL` zeigt den Befehl überall an; `RECORD_SELECTION` zeigt ihn nur in Datensatzkontexten an |
-| `availabilityObjectUniversalIdentifier` | `string` (optional) | Beschränkt den Befehl auf einen bestimmten Objekttyp (z. B. Person) |
-
-Hier ist ein Beispiel aus der Call-Recording-App, das einen auf Person-Datensätze beschränkten Befehl hinzufügt:
-
-```typescript
-import { defineFrontComponent } from 'twenty-sdk';
-
-export default defineFrontComponent({
- universalIdentifier: 'c3d4e5f6-a7b8-9012-cdef-123456789012',
- name: 'Summarize Person Call Recordings',
- description: 'Generates a summary of call recordings for a person',
- component: SummarizePersonRecordings,
- command: {
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-234567890123',
- label: 'Summarize call recordings',
- icon: 'IconSparkles',
- isPinned: false,
- availabilityType: 'RECORD_SELECTION',
- availabilityObjectUniversalIdentifier:
- '20202020-e674-48e5-a542-72570eee7213',
- },
-});
-```
-
-Wenn der Befehl synchronisiert wird, erscheint er im Befehlsmenü. Wenn die Front-Komponente Nicht-Headless ist, öffnet sich das Seitenpanel und die Komponente wird darin gerendert. Wenn sie Headless ist, wird die Komponente im Hintergrund gemountet und führt ihre Logik aus.
-
-#### SDK-Command-Komponenten
-
-Das Paket `twenty-sdk` stellt vier Command-Hilfskomponenten bereit, die für Headless-Front-Komponenten ausgelegt sind. Jede Komponente führt beim Mounten eine Aktion aus, behandelt Fehler durch Anzeige einer Snackbar-Benachrichtigung und unmountet die Front-Komponente nach Abschluss automatisch.
-
-Importieren Sie sie aus `twenty-sdk/command`:
-
-* **`Command`** — Führt einen asynchronen Callback über das Prop `execute` aus.
-* **`CommandLink`** — Navigiert zu einem App-Pfad. Props: `to`, `params`, `queryParams`, `options`.
-* **`CommandModal`** — Öffnet einen Bestätigungsdialog. Bestätigt der Benutzer, wird der Callback `execute` ausgeführt. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
-* **`CommandOpenSidePanelPage`** — Öffnet eine bestimmte Seite im Seitenpanel. Props: `page`, `pageTitle`, `pageIcon`.
-
-Hier ist ein vollständiges Beispiel einer Headless-Front-Komponente, die `Command` verwendet, um eine Aktion aus dem Befehlsmenü auszuführen:
-
-```typescript
-// src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk';
-import { Command } from 'twenty-sdk/command';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const RunAction = () => {
- const execute = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- createTask: {
- __args: { data: { title: 'Created by my app' } },
- id: true,
- },
- });
- };
-
- return My Custom Widget
-This is a custom front component for Twenty.
-
-
- );
-};
-```
-
-Der Kontext ist reaktiv — ändert sich der umgebende Datensatz, liefern die Hooks automatisch die aktualisierten Werte.
-
-#### Host-API-Funktionen
-
-Front-Komponenten laufen in einer isolierten Sandbox, können jedoch über eine Reihe vom Host bereitgestellter Funktionen mit der UI von Twenty interagieren. Importieren Sie sie direkt aus `twenty-sdk`:
-
-```typescript
-import {
- navigate,
- closeSidePanel,
- enqueueSnackbar,
- unmountFrontComponent,
- openSidePanelPage,
- openCommandConfirmationModal,
-} from 'twenty-sdk';
-```
-
-| Funktion | Signatur | Beschreibung |
-| ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `navigieren` | `(to, params?, queryParams?, options?) => PromiseRecord: {recordId ?? 'none'}
-User: {userId ?? 'anonymous'}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Fähigkeiten
-
-Skills definieren wiederverwendbare Anweisungen und Fähigkeiten, die KI-Agenten in Ihrem Arbeitsbereich verwenden können. Verwenden Sie `defineSkill()`, um Skills mit eingebauter Validierung zu definieren:
-
-```typescript
-// src/skills/example-skill.ts
-import { defineSkill } from 'twenty-sdk';
-
-export default defineSkill({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-outreach',
- label: 'Sales Outreach',
- description: 'Guides the AI agent through a structured sales outreach process',
- icon: 'IconBrain',
- content: `You are a sales outreach assistant. When reaching out to a prospect:
-1. Research the company and recent news
-2. Identify the prospect's role and likely pain points
-3. Draft a personalized message referencing specific details
-4. Keep the tone professional but conversational`,
-});
-```
-
-Hauptpunkte:
-
-* `name` ist eine eindeutige Kennung (als Zeichenfolge) für den Skill (kebab-case empfohlen).
-* `label` ist der menschenlesbare Anzeigename, der in der UI angezeigt wird.
-* `content` enthält die Skill-Anweisungen — dies ist der Text, den der KI-Agent verwendet.
-* `icon` (optional) legt das in der UI angezeigte Symbol fest.
-* `description` (optional) liefert zusätzlichen Kontext zum Zweck des Skills.
-
-Sie können neue Skills auf zwei Arten erstellen:
-
-* **Generiert**: Führen Sie `yarn twenty entity:add` aus und wählen Sie die Option zum Hinzufügen eines neuen Skills.
-* **Manuell**: Erstellen Sie eine neue Datei und verwenden Sie `defineSkill()` nach demselben Muster.
-
-### Agenten
-
-Mit Agents definieren Sie KI-Agenten mit System-Prompts, die in Ihrem Arbeitsbereich arbeiten können. Verwenden Sie `defineAgent()`, um Agenten mit eingebauter Validierung zu definieren:
-
-```typescript
-// src/agents/example-agent.ts
-import { defineAgent } from 'twenty-sdk';
-
-export default defineAgent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-assistant',
- label: 'Sales Assistant',
- description: 'An AI agent that helps with sales tasks',
- icon: 'IconRobot',
- prompt: `You are a sales assistant. Help users with:
-1. Researching prospects and companies
-2. Drafting personalized outreach messages
-3. Tracking follow-ups and next steps
-4. Analyzing deal pipeline and suggesting actions`,
-});
-```
-
-Hauptpunkte:
-
-* `name` ist eine eindeutige Kennung (als Zeichenfolge) für den Agenten (kebab-case empfohlen).
-* `label` ist der menschenlesbare Anzeigename, der in der UI angezeigt wird.
-* `prompt` enthält den System-Prompt — dies ist der Anweisungstext, der das Verhalten des Agenten definiert.
-* `icon` (optional) legt das in der UI angezeigte Symbol fest.
-* `description` (optional) liefert zusätzlichen Kontext zum Zweck des Agenten.
-
-Sie können neue Agenten auf zwei Arten erstellen:
-
-* **Generiert**: Führen Sie `yarn twenty entity:add` aus und wählen Sie die Option zum Hinzufügen eines neuen Agenten.
-* **Manuell**: Erstellen Sie eine neue Datei und verwenden Sie `defineAgent()` nach demselben Muster.
-
-### Generierte typisierte Clients
-
-Zwei typisierte Clients werden von `yarn twenty dev` automatisch generiert und basierend auf Ihrem Arbeitsbereichs-Schema in `node_modules/twenty-sdk/clients` gespeichert:
-
-* **`CoreApiClient`** — fragt den `/graphql`-Endpunkt nach Arbeitsbereichsdaten ab
-* **`MetadataApiClient`** — ruft über den Endpunkt `/metadata` die Arbeitsbereichskonfiguration und Datei-Uploads ab.
-
-```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-
-const client = new CoreApiClient();
-const { me } = await client.query({ me: { id: true, displayName: true } });
-
-const metadataClient = new MetadataApiClient();
-const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });},{
-```
-
-`CoreApiClient` wird von `yarn twenty dev` automatisch neu generiert, sobald sich Ihre Objekte oder Felder ändern. `MetadataApiClient` ist im SDK bereits enthalten.
-
-#### Laufzeit-Anmeldedaten in Logikfunktionen
-
-Wenn Ihre Funktion auf Twenty läuft, injiziert die Plattform vor der Ausführung Ihres Codes Anmeldedaten als Umgebungsvariablen:
-
-* `TWENTY_API_URL`: Basis-URL der Twenty-API, auf die Ihre App abzielt.
-* `TWENTY_API_KEY`: Kurzlebiger Schlüssel, der auf die Standard-Funktionsrolle Ihrer Anwendung begrenzt ist.
-
-Notizen:
-
-* Sie müssen dem generierten Client weder URL noch API-Schlüssel übergeben. Er liest `TWENTY_API_URL` und `TWENTY_API_KEY` zur Laufzeit aus process.env.
-* Die Berechtigungen des API-Schlüssels werden durch die Rolle bestimmt, auf die in Ihrer `application-config.ts` über `defaultRoleUniversalIdentifier` verwiesen wird. Dies ist die Standardrolle, die von den Logikfunktionen Ihrer Anwendung verwendet wird.
-* Anwendungen können Rollen definieren, um das Least-Privilege-Prinzip einzuhalten. Gewähren Sie nur die Berechtigungen, die Ihre Funktionen benötigen, und verweisen Sie dann mit `defaultRoleUniversalIdentifier` auf den universellen Bezeichner dieser Rolle.
-
-#### Dateien hochladen
-
-Der `MetadataApiClient` enthält eine Methode `uploadFile`, um Dateien an Felder des Typs Datei in Ihren Arbeitsbereichsobjekten anzuhängen. Da Standard-GraphQL-Clients Multipart-Datei-Uploads nicht nativ unterstützen, stellt der Client diese dedizierte Methode bereit, die unter der Haube die [GraphQL-Multipart-Anfragespezifikation](https://github.com/jaydenseric/graphql-multipart-request-spec) implementiert.
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-import * as fs from 'fs';
-
-const metadataClient = new MetadataApiClient();
-
-const fileBuffer = fs.readFileSync('./invoice.pdf');
-
-const uploadedFile = await metadataClient.uploadFile(
- fileBuffer, // Dateiinhalte als Buffer
- 'invoice.pdf', // Dateiname
- 'application/pdf', // MIME-Typ (Standard: 'application/octet-stream')
- '58a0a314-d7ea-4865-9850-7fb84e72f30b', // Universeller Feldbezeichner
-);
-
-console.log(uploadedFile);
-// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
-```
-
-Die Methodensignatur:
-
-```typescript
-uploadFile(
- fileBuffer: Buffer,
- filename: string,
- contentType: string,
- fieldMetadataUniversalIdentifier: string,
-): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
-```
-
-| Parameter | Typ | Beschreibung |
-| ---------------------------------- | -------------- | ------------------------------------------------------------------------------- |
-| `fileBuffer` | `Buffer` | Der Rohinhalt der Datei |
-| `filename` | `string` | Der Name der Datei (wird für Speicherung und Anzeige verwendet) |
-| `contentType` | `string` | MIME-Typ der Datei (standardmäßig `application/octet-stream`, wenn weggelassen) |
-| `fieldMetadataUniversalIdentifier` | `Zeichenkette` | Der `universalIdentifier` des Dateityp-Felds in Ihrem Objekt |
-
-Hauptpunkte:
-
-* Die Methode `uploadFile` ist auf dem `MetadataApiClient` verfügbar, weil die Upload-Mutation vom Endpunkt `/metadata` aufgelöst wird.
-* Sie verwendet den `universalIdentifier` des Feldes (nicht dessen arbeitsbereichsspezifische ID), sodass Ihr Upload-Code in jedem Arbeitsbereich funktioniert, in dem Ihre App installiert ist — im Einklang damit, wie Apps Felder überall sonst referenzieren.
-* Die zurückgegebene `url` ist eine signierte URL, mit der Sie auf die hochgeladene Datei zugreifen können.
-
-### Hello-World-Beispiel
-
-Ein minimales End-to-End-Beispiel, das Objekte, Logikfunktionen, Frontend-Komponenten und mehrere Trigger demonstriert, finden Sie [hier](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
-
-## Erstellen Ihrer App
-
-Sobald Sie Ihre App mit `app:dev` entwickelt haben, verwenden Sie `app:build`, um sie in ein verteilbares Paket zu kompilieren.
-
-```bash filename="Terminal"
-# Die App erstellen (Ausgabe nach .twenty/output/)
-yarn twenty build
-
-# Build ausführen und ein Tarball (.tgz) für die Verteilung erstellen
-yarn twenty build --tarball
-```
-
-Der Build-Prozess:
-
-1. **Parst und validiert das Manifest** — liest alle `defineX()`-Entitäten aus Ihren Quelldateien und validiert die Manifeststruktur.
-2. **Kompiliert Logikfunktionen und Front-Komponenten** — bündelt TypeScript-Quellcode in ESM `.mjs`-Dateien mit esbuild.
-3. **Erzeugt Checksummen** — berechnet MD5-Hashes für jede erstellte Datei, die im Manifest als `builtHandlerChecksum` / `builtComponentChecksum` gespeichert werden.
-4. **Generiert den typisierten API-Client** — führt eine Introspektion des GraphQL-Schemas durch und generiert die typisierten Clients `CoreApiClient` und `MetadataApiClient`.
-5. **Führt eine TypeScript-Typprüfung aus** — führt `tsc --noEmit` aus, um Typfehler vor der Veröffentlichung zu erkennen.
-6. **Baut mit dem generierten Client neu** — führt einen zweiten Kompiliervorgang durch, damit die generierten Client-Typen enthalten sind.
-7. **Erstellt optional einen Tarball** — wenn `--tarball` übergeben wird, wird `npm pack` ausgeführt, um eine `.tgz`-Datei zu erstellen, die für die Verteilung bereit ist.
-
-Der Build-Output in `.twenty/output/` enthält:
-
-```text
-.twenty/output/
-├── manifest.json # Manifest with checksums for all built files
-├── package.json # Copied from app root
-├── yarn.lock # Copied from app root
-├── src/
-│ ├── logic-functions/ # Compiled .mjs logic function files
-│ └── front-components/ # Compiled .mjs front component files
-├── public/ # Static assets (if any)
-└── my-app-1.0.0.tgz # Only with --tarball flag
-```
-
-| Option | Beschreibung |
-| ----------- | -------------------------------------------------------------- |
-| `[appPath]` | Pfad zum App-Verzeichnis (standardmäßig aktuelles Verzeichnis) |
-| `--tarball` | Den Output zusätzlich in einen `.tgz`-Tarball packen |
-
-## Veröffentlichen Ihrer App
-
-Verwenden Sie `app:publish`, um Ihre App zu verteilen — entweder zur npm-Registry oder direkt zu einem Twenty-Server.
-
-### Bei npm veröffentlichen (Standard)
-
-```bash filename="Terminal"
-# Auf npm veröffentlichen (erfordert npm login)
-yarn twenty publish
-
-# Mit einem dist-tag veröffentlichen (z. B. beta, next)
-yarn twenty publish --tag beta
-```
-
-Dies baut die App und führt `npm publish` aus dem Verzeichnis `.twenty/output/` aus. Das veröffentlichte Paket kann dann von jedem Arbeitsbereich über den Twenty-Marktplatz installiert werden.
-
-### Auf einem Twenty-Server veröffentlichen
-
-```bash filename="Terminal"
-# Direkt auf einen Twenty-Server veröffentlichen
-yarn twenty publish --server https://app.twenty.com
-```
-
-Dies erstellt beim Build einen Tarball, lädt ihn über die GraphQL-Mutation `uploadAppTarball` auf den Server hoch und stößt die Installation in einem Schritt an. Dies ist nützlich für private Bereitstellungen oder Tests gegen einen bestimmten Server.
-
-| Option | Beschreibung |
-| ----------------- | ------------------------------------------------------------------ |
-| `[appPath]` | Pfad zum App-Verzeichnis (standardmäßig aktuelles Verzeichnis) |
-| `--server Archive this record?
- -
-
);
};
export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
+ universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+ name: 'hello-world',
+ description: 'A simple front component',
+ component: HelloWorld,
+ command: {
+ universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+ shortLabel: 'Hello',
+ label: 'Hello World',
+ icon: 'IconBolt',
+ isPinned: true,
+ availabilityType: 'GLOBAL',
+ },
});
```
-Punti chiave:
+After syncing with `yarn twenty dev`, the quick action appears in the top-right corner of the page:
-* I componenti front-end sono componenti React che eseguono il rendering in contesti isolati all'interno di Twenty.
-* Il campo `component` fa riferimento al tuo componente React.
-* I componenti vengono compilati e sincronizzati automaticamente durante `yarn twenty dev`.
+My Custom Widget
-This is a custom front component for Twenty.
+Hello from my app!
+This component renders inside Twenty.
+
+
-Puoi creare nuovi componenti front-end in due modi:
+Click it to render the component inline.
-* **Generata dallo scaffolder**: Esegui `yarn twenty add` e scegli l'opzione per aggiungere un nuovo componente front-end.
-* **Manuale**: Crea un nuovo file `.tsx` e usa `defineFrontComponent()`, seguendo lo stesso schema.
+{/* TODO: add screenshot of the rendered front component */}
-### Abilità
+#### Configuration fields
+
+| Campo | Obbligatorio | Descrizione |
+| --------------------- | ------------ | ----------------------------------------------------------------------------------- |
+| `universalIdentifier` | Sì | Stable unique ID for this component |
+| `component` | Sì | A React component function |
+| `name` | No | Display name |
+| `descrizione` | No | Description of what the component does |
+| `isHeadless` | No | Set to `true` if the component has no visible UI (see below) |
+| `comando` | No | Register the component as a command (see [command options](#command-options) below) |
+
+#### Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See the [definePageLayout](#definepagelayout) section for details.
+
+#### Headless components (`isHeadless: true`)
+
+Headless components render no visible UI but still run React logic. This is useful for **effect components** — components that perform side effects when mounted, such as syncing data, starting a timer, listening to events, or triggering a notification.
+
+```tsx src/front-components/sync-tracker.tsx
+import { defineFrontComponent, useRecordId, enqueueSnackbar } from 'twenty-sdk';
+import { useEffect } from 'react';
+
+const SyncTracker = () => {
+ const recordId = useRecordId();
+
+ useEffect(() => {
+ enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
+ }, [recordId]);
+
+ return null;
+};
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'sync-tracker',
+ description: 'Tracks record views silently',
+ isHeadless: true,
+ component: SyncTracker,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+#### Accessing runtime context
+
+Inside your component, use SDK hooks to access the current user, record, and component instance:
+
+```tsx src/front-components/record-info.tsx
+import {
+ defineFrontComponent,
+ useUserId,
+ useRecordId,
+ useFrontComponentId,
+} from 'twenty-sdk';
+
+const RecordInfo = () => {
+ const userId = useUserId();
+ const recordId = useRecordId();
+ const componentId = useFrontComponentId();
+
+ return (
+
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
+ name: 'record-info',
+ component: RecordInfo,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Descrizione |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useRecordId()` | `string` or `null` | The current record's ID (when placed on a record page) |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | varia | Access the full execution context with a selector function |
+
+#### Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Funzione | Descrizione |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Chiudi il pannello laterale |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+#### Command options
+
+Adding a `command` field to `defineFrontComponent` registers the component in the command menu (Cmd+K). If `isPinned` is `true`, it also appears as a quick-action button in the top-right corner of the page.
+
+| Campo | Obbligatorio | Descrizione |
+| --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `universalIdentifier` | Sì | Stable unique ID for the command |
+| `etichetta` | Sì | Full label shown in the command menu (Cmd+K) |
+| `shortLabel` | No | Shorter label displayed on the pinned quick-action button |
+| `icona` | No | Icon name displayed next to the label (e.g. `'IconBolt'`, `'IconSend'`) |
+| `isPinned` | No | When `true`, shows the command as a quick-action button in the top-right corner of the page |
+| `availabilityType` | No | Controls where the command appears: `'GLOBAL'` (always available), `'RECORD_SELECTION'` (only when records are selected), or `'FALLBACK'` (shown when no other commands match) |
+| `availabilityObjectUniversalIdentifier` | No | Restrict the command to pages of a specific object type (e.g. only on Company records) |
+| `conditionalAvailabilityExpression` | No | A boolean expression to dynamically control whether the command is visible (see below) |
+
+#### Conditional availability expressions
+
+The `conditionalAvailabilityExpression` field lets you control when a command is visible based on the current page context. Import typed variables and operators from `twenty-sdk` to build expressions:
+
+```tsx
+import {
+ defineFrontComponent,
+ pageType,
+ numberOfSelectedRecords,
+ objectPermissions,
+ everyEquals,
+ isDefined,
+} from 'twenty-sdk';
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'bulk-action',
+ component: BulkAction,
+ command: {
+ universalIdentifier: '...',
+ label: 'Bulk Update',
+ availabilityType: 'RECORD_SELECTION',
+ conditionalAvailabilityExpression: everyEquals(
+ objectPermissions,
+ 'canUpdateObjectRecords',
+ true,
+ ),
+ },
+});
+```
+
+**Context variables** — these represent the current state of the page:
+
+| Variabile | Tipo | Descrizione |
+| ------------------------------ | --------- | ---------------------------------------------------------------- |
+| `pageType` | `string` | Current page type (e.g. `'RecordIndexPage'`, `'RecordShowPage'`) |
+| `isInSidePanel` | `boolean` | Whether the component is rendered in a side panel |
+| `numberOfSelectedRecords` | `numero` | Number of currently selected records |
+| `isSelectAll` | `boolean` | Whether "select all" is active |
+| `selectedRecords` | `array` | The selected record objects |
+| `favoriteRecordIds` | `array` | IDs of favorited records |
+| `objectPermissions` | `oggetto` | Permissions for the current object type |
+| `targetObjectReadPermissions` | `oggetto` | Read permissions for the target object |
+| `targetObjectWritePermissions` | `oggetto` | Write permissions for the target object |
+| `featureFlags` | `oggetto` | Active feature flags |
+| `objectMetadataItem` | `oggetto` | Metadata of the current object type |
+| `hasAnySoftDeleteFilterOnView` | `boolean` | Whether the current view has a soft-delete filter |
+
+**Operators** — combine variables into boolean expressions:
+
+| Operator | Descrizione |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| `isDefined(value)` | `true` if the value is not null/undefined |
+| `isNonEmptyString(value)` | `true` if the value is a non-empty string |
+| `includes(array, value)` | `true` if the array contains the value |
+| `includesEvery(array, prop, value)` | `true` if every item's property includes the value |
+| `every(array, prop)` | `true` if the property is truthy on every item |
+| `everyDefined(array, prop)` | `true` if the property is defined on every item |
+| `everyEquals(array, prop, value)` | `true` if the property equals the value on every item |
+| `some(array, prop)` | `true` if the property is truthy on at least one item |
+| `someDefined(array, prop)` | `true` if the property is defined on at least one item |
+| `someEquals(array, prop, value)` | `true` if the property equals the value on at least one item |
+| `someNonEmptyString(array, prop)` | `true` if the property is a non-empty string on at least one item |
+| `none(array, prop)` | `true` if the property is falsy on every item |
+| `noneDefined(array, prop)` | `true` if the property is undefined on every item |
+| `noneEquals(array, prop, value)` | `true` if the property does not equal the value on any item |
+
+#### Public assets
+
+Front components can access files from the app's `public/` directory using `getPublicAssetUrl`:
+
+```tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk';
+
+const Logo = () => User: {userId}
+Record: {recordId ?? 'No record context'}
+Component: {componentId}
+;
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'logo',
+ component: Logo,
+});
+```
+
+See the [public assets section](#accessing-public-assets-with-getpublicasseturl) for details.
+
+#### Stile
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { Button, Tag, Status } from 'twenty-sdk/ui';
+
+const StyledWidget = () => {
+ return (
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
+ name: 'styled-widget',
+ component: StyledWidget,
+});
+```
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step (`yarn twenty dev` or `yarn twenty build`) uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Scaffolding entities with `yarn twenty add` + +Instead of creating entity files by hand, you can use the interactive scaffolder: + +```bash filename="Terminal" +yarn twenty add +``` + +This prompts you to pick an entity type and walks you through the required fields. It generates a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call. + +You can also pass the entity type directly to skip the first prompt: + +```bash filename="Terminal" +yarn twenty add object +yarn twenty add logicFunction +yarn twenty add frontComponent +``` + +### Available entity types + +| Tipo di entità | Comando | Generated file | +| -------------------- | ------------------------------------ | ------------------------------------- | +| Oggetto | `yarn twenty add object` | `src/objects/
+
+
+
+## Step 3: Sign in to your workspace
+
+Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+## Step 4: Authorize the app
+
+After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
+
+Click **Authorize** to continue.
+
+
+
+
+
+
+Once authorized, your terminal will confirm that everything is set up.
+
+
+
+
+
+
+## Step 5: Start developing
+
+Go into your new app folder and start the development server:
```bash filename="Terminal"
-# Add a new entity to your application (guided)
-yarn twenty add
-
-# Watch your application's function logs
-yarn twenty function:logs
-
-# Execute a function by name
-yarn twenty function:execute -n my-function -p '{"name": "test"}'
-
-# Execute the pre-install function
-yarn twenty function:execute --preInstall
-
-# Execute the post-install function
-yarn twenty function:execute --postInstall
-
-# Uninstall the application from the current workspace
-yarn twenty uninstall
-
-# Display commands' help
-yarn twenty help
+cd my-twenty-app
+yarn twenty dev
```
-Vedi anche: le pagine di riferimento della CLI per [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) e [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
+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.
-## Struttura del progetto (generata dallo scaffolder)
+For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
-Quando esegui `npx create-twenty-app@latest my-twenty-app`, lo scaffolder:
+```bash filename="Terminal"
+yarn twenty dev --verbose
+```
-* Copia un'applicazione base minimale in `my-twenty-app/`
-* Aggiunge una dipendenza locale `twenty-sdk` e la configurazione di Yarn 4
-* Crea file di configurazione e script collegati alla CLI `twenty`
-* Genera i file principali (configurazione dell'applicazione, ruolo predefinito per le funzioni logiche, funzioni di pre-installazione e post-installazione) più i file di esempio in base alla modalità di scaffolding
+
+
+
+
+
+## Step 6: See your app in 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**:
+
+
+
+
+
+
+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.
+
+
+
+
+
+
+Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
+
+
+
+
+
+
+Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
+
+
+
+
+
+
+You are all set! Edit any file in `src/` and the changes will be picked up automatically.
+
+Head over to [Building Apps](/l/it/developers/extend/apps/building) for a detailed guide on creating objects, logic functions, front components, skills, and more.
+
+---
+
+## Project structure
+
+The scaffolder generates the following file structure (shown with `--exhaustive` mode, which includes examples for every entity type):
```text filename="my-twenty-app/"
my-twenty-app/
@@ -83,124 +152,238 @@ my-twenty-app/
install-state.gz
.oxlintrc.json
tsconfig.json
+ tsconfig.spec.json # TypeScript config for tests
+ vitest.config.ts # Vitest test runner configuration
+ LLMS.md
README.md
- public/ # Public assets folder (images, fonts, etc.)
+ .github/
+ └── workflows/
+ └── ci.yml # GitHub Actions CI workflow
+ public/ # Public assets (images, fonts, etc.)
src/
- ├── application-config.ts # Required - main application configuration
+ ├── application-config.ts # Required — main application configuration
+ ├── __tests__/
+ │ ├── setup-test.ts # Test setup (server health check, config)
+ │ └── app-install.integration-test.ts # Example integration test
├── roles/
- │ └── default-role.ts # Default role for logic functions
+ │ └── default-role.ts # Default role for logic functions
├── objects/
- │ └── example-object.ts # Example custom object definition
+ │ └── example-object.ts # Example custom object definition
├── fields/
- │ └── example-field.ts # Example standalone field definition
+ │ └── example-field.ts # Example standalone field definition
├── logic-functions/
- │ ├── hello-world.ts # Example logic function
- │ ├── pre-install.ts # Pre-install logic function
- │ └── post-install.ts # Post-install logic function
+ │ ├── hello-world.ts # Example logic function
+ │ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
+ │ ├── pre-install.ts # Runs before installation
+ │ └── post-install.ts # Runs after installation
├── front-components/
- │ └── hello-world.tsx # Example front component
+ │ └── hello-world.tsx # Example front component
+ ├── page-layouts/
+ │ └── example-record-page-layout.ts # Example page layout with front component
├── views/
- │ └── example-view.ts # Example saved view definition
+ │ └── example-view.ts # Example saved view definition
├── navigation-menu-items/
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
- └── skills/
- └── example-skill.ts # Example AI agent skill definition
+ ├── skills/
+ │ └── example-skill.ts # Example AI agent skill definition
+ └── agents/
+ └── example-agent.ts # Example AI agent definition
```
-Con `--minimal`, vengono creati solo i file principali (`application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` e `logic-functions/post-install.ts`).
+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.
-A livello generale:
+### Key files
-* **package.json**: Dichiara il nome dell'app, la versione, i motori (Node 24+, Yarn 4) e aggiunge `twenty-sdk` più uno script `twenty` che delega alla CLI locale `twenty`. Esegui `yarn twenty help` per elencare tutti i comandi disponibili.
-* **.gitignore**: Ignora i file generati comuni come `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, cartelle di coverage, file di log e file `.env*`.
-* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Bloccano e configurano la toolchain Yarn 4 utilizzata dal progetto.
-* **.nvmrc**: Fissa la versione di Node.js prevista dal progetto.
-* **.oxlintrc.json** e **tsconfig.json**: Forniscono linting e configurazione TypeScript per i sorgenti TypeScript della tua app.
-* **README.md**: Un breve README nella radice dell'app con istruzioni di base.
-* **public/**: Una cartella per archiviare risorse pubbliche (immagini, font, file statici) che saranno servite con la tua applicazione. I file collocati qui vengono caricati durante la sincronizzazione e sono accessibili in fase di esecuzione.
-* **src/**: Il luogo principale in cui definisci la tua applicazione come codice
+| File / Folder | Scopo |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `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/` | Abilità che estendono gli agenti IA di 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. |
-### Rilevamento delle entità
+## Managing remotes
-L'SDK rileva le entità analizzando i tuoi file TypeScript alla ricerca di chiamate **`export default define
+
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
-});
-```
-
-Punti chiave:
-
-* I componenti front-end sono componenti React che eseguono il rendering in contesti isolati all'interno di Twenty.
-* Il campo `component` fa riferimento al tuo componente React.
-* I componenti vengono compilati e sincronizzati automaticamente durante `yarn twenty dev`.
-
-Puoi creare nuovi componenti front-end in due modi:
-
-* **Generata dallo scaffolder**: Esegui `yarn twenty entity:add` e scegli l'opzione per aggiungere un nuovo componente front-end.
-* **Manuale**: Crea un nuovo file `.tsx` e usa `defineFrontComponent()`, seguendo lo stesso schema.
-
-#### Dove possono essere utilizzati i componenti front.
-
-I componenti front possono essere renderizzati in due posizioni all'interno di Twenty:
-
-* **Pannello laterale** — I componenti front non headless si aprono nel pannello laterale destro. Questo è il comportamento predefinito quando un componente front viene avviato dal menu comandi.
-* **Widget (dashboard e pagine dei record)** — I componenti front possono essere incorporati come widget all'interno dei layout di pagina. Quando si configura una dashboard o il layout di una pagina record, gli utenti possono aggiungere un widget del componente front.
-
-#### Headless vs non headless
-
-I componenti front prevedono due modalità di rendering controllate dall'opzione `isHeadless`:
-
-**Non headless (predefinito)** — Il componente renderizza un'interfaccia utente visibile. Quando viene avviato dal menu comandi, si apre nel pannello laterale. Questo è il comportamento predefinito quando `isHeadless` è `false` o omesso.
-
-**Headless** — Il componente viene montato in modo invisibile in background. Non apre il pannello laterale. I componenti headless sono pensati per azioni che eseguono una logica e poi si smontano — ad esempio, eseguire un'attività asincrona, navigare a una pagina o mostrare una finestra modale di conferma. Si abbinano naturalmente ai componenti Command dell'SDK descritti di seguito.
-
-```typescript
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-action',
- description: 'Runs an action without opening the side panel',
- component: MyAction,
- isHeadless: true,
- command: {
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
- label: 'Run my action',
- },
-});
-```
-
-#### Aggiungere voci al menu comandi
-
-Per far comparire un componente front come voce nel menu comandi di Twenty, aggiungi la proprietà `command` a `defineFrontComponent()`. Quando gli utenti aprono il menu comandi (Cmd+K / Ctrl+K), la voce viene mostrata e al clic attiva il componente front.
-
-L'oggetto `command` accetta i seguenti campi:
-
-| Campo | Tipo | Descrizione |
-| --------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | `string` (obbligatorio) | ID univoco per la voce del menu comandi |
-| `etichetta` | `string` (obbligatorio) | Etichetta visualizzata nel menu comandi |
-| `icona` | `string` (facoltativo) | Nome dell'icona (ad es., `'IconSparkles'`) |
-| `isPinned` | `boolean` (facoltativo) | Indica se il comando è fissato in alto nel menu |
-| `availabilityType` | `'GLOBAL' \| 'RECORD_SELECTION'` (facoltativo) | `GLOBAL` mostra il comando ovunque; `RECORD_SELECTION` lo mostra solo nei contesti dei record |
-| `availabilityObjectUniversalIdentifier` | `string` (facoltativo) | Limita il comando a uno specifico tipo di oggetto (ad es., Person) |
-
-Ecco un esempio dall'app di registrazione delle chiamate che aggiunge un comando limitato ai record Person:
-
-```typescript
-import { defineFrontComponent } from 'twenty-sdk';
-
-export default defineFrontComponent({
- universalIdentifier: 'c3d4e5f6-a7b8-9012-cdef-123456789012',
- name: 'Summarize Person Call Recordings',
- description: 'Generates a summary of call recordings for a person',
- component: SummarizePersonRecordings,
- command: {
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-234567890123',
- label: 'Summarize call recordings',
- icon: 'IconSparkles',
- isPinned: false,
- availabilityType: 'RECORD_SELECTION',
- availabilityObjectUniversalIdentifier:
- '20202020-e674-48e5-a542-72570eee7213',
- },
-});
-```
-
-Quando il comando viene sincronizzato, appare nel menu comandi. Se il componente front è non headless, si apre il pannello laterale con il componente renderizzato al suo interno. Se è headless, il componente viene montato in background ed esegue la propria logica.
-
-#### Componenti Command dell'SDK
-
-Il pacchetto `twenty-sdk` fornisce quattro componenti di supporto Command progettati per i componenti front headless. Ogni componente esegue un'azione al montaggio, gestisce gli errori mostrando una notifica snackbar e smonta automaticamente il componente front al termine.
-
-Importali da `twenty-sdk/command`:
-
-* **`Command`** — Esegue una callback asincrona tramite la prop `execute`.
-* **`CommandLink`** — Naviga verso un percorso dell'app. Props: `to`, `params`, `queryParams`, `options`.
-* **`CommandModal`** — Apre una finestra modale di conferma. Se l'utente conferma, esegue la callback `execute`. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
-* **`CommandOpenSidePanelPage`** — Apre una specifica pagina del pannello laterale. Props: `page`, `pageTitle`, `pageIcon`.
-
-Ecco un esempio completo di componente front headless che usa `Command` per eseguire un'azione dal menu comandi:
-
-```typescript
-// src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk';
-import { Command } from 'twenty-sdk/command';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const RunAction = () => {
- const execute = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- createTask: {
- __args: { data: { title: 'Created by my app' } },
- id: true,
- },
- });
- };
-
- return My Custom Widget
-This is a custom front component for Twenty.
-
-
- );
-};
-```
-
-Il contesto è reattivo — se il record circostante cambia, gli hook restituiscono automaticamente i valori aggiornati.
-
-#### Funzioni dell'API host
-
-I componenti front vengono eseguiti in una sandbox isolata ma possono interagire con l'interfaccia di Twenty tramite un insieme di funzioni fornite dall'host. Importale direttamente da `twenty-sdk`:
-
-```typescript
-import {
- navigate,
- closeSidePanel,
- enqueueSnackbar,
- unmountFrontComponent,
- openSidePanelPage,
- openCommandConfirmationModal,
-} from 'twenty-sdk';
-```
-
-| Funzione | Firma | Descrizione |
-| ------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `naviga` | `(to, params?, queryParams?, options?) => PromiseRecord: {recordId ?? 'none'}
-User: {userId ?? 'anonymous'}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Abilità
-
-Skills define reusable instructions and capabilities that AI agents can use within your workspace. Use `defineSkill()` to define skills with built-in validation:
-
-```typescript
-// src/skills/example-skill.ts
-import { defineSkill } from 'twenty-sdk';
-
-export default defineSkill({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-outreach',
- label: 'Sales Outreach',
- description: 'Guides the AI agent through a structured sales outreach process',
- icon: 'IconBrain',
- content: `You are a sales outreach assistant. When reaching out to a prospect:
-1. Research the company and recent news
-2. Identify the prospect's role and likely pain points
-3. Draft a personalized message referencing specific details
-4. Keep the tone professional but conversational`,
-});
-```
-
-Punti chiave:
-
-* `name` is a unique identifier string for the skill (kebab-case recommended).
-* `label` is the human-readable display name shown in the UI.
-* `content` contains the skill instructions — this is the text the AI agent uses.
-* `icon` (optional) sets the icon displayed in the UI.
-* `description` (optional) provides additional context about the skill's purpose.
-
-You can create new skills in two ways:
-
-* **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new skill.
-* **Manual**: Create a new file and use `defineSkill()`, following the same pattern.
-
-### Agenti
-
-Gli Agenti definiscono agenti IA con prompt di sistema che possono operare all'interno del tuo spazio di lavoro. Usa `defineAgent()` per definire agenti con convalida integrata:
-
-```typescript
-// src/agents/example-agent.ts
-import { defineAgent } from 'twenty-sdk';
-
-export default defineAgent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-assistant',
- label: 'Sales Assistant',
- description: 'An AI agent that helps with sales tasks',
- icon: 'IconRobot',
- prompt: `You are a sales assistant. Help users with:
-1. Researching prospects and companies
-2. Drafting personalized outreach messages
-3. Tracking follow-ups and next steps
-4. Analyzing deal pipeline and suggesting actions`,
-});
-```
-
-Punti chiave:
-
-* `name` è una stringa identificativa univoca per l'agente (kebab-case consigliato).
-* `label` è il nome di visualizzazione leggibile mostrato nell'UI.
-* `prompt` contiene il prompt di sistema — è il testo di istruzioni che definisce il comportamento dell'agente.
-* `icon` (opzionale) imposta l'icona visualizzata nell'UI.
-* `description` (opzionale) fornisce contesto aggiuntivo sullo scopo dell'agente.
-
-Puoi creare nuovi agenti in due modi:
-
-* **Generata dallo scaffolder**: Esegui `yarn twenty entity:add` e scegli l'opzione per aggiungere un nuovo agente.
-* **Manuale**: Crea un nuovo file e usa `defineAgent()`, seguendo lo stesso schema.
-
-### Client tipizzati generati
-
-Due client tipizzati sono generati automaticamente da `yarn twenty dev` e salvati in `node_modules/twenty-sdk/clients` in base allo schema della tua area di lavoro:
-
-* **`CoreApiClient`** — interroga l'endpoint `/graphql` per i dati dell'area di lavoro
-* **`MetadataApiClient`** — interroga l'endpoint `/metadata` per la configurazione dello spazio di lavoro e il caricamento dei file
-
-```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-
-const client = new CoreApiClient();
-const { me } = await client.query({ me: { id: true, displayName: true } });
-
-const metadataClient = new MetadataApiClient();
-const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });},{
-```
-
-`CoreApiClient` viene rigenerato automaticamente da `yarn twenty dev` ogni volta che i tuoi oggetti o campi cambiano. `MetadataApiClient` è fornito pronto all'uso con l'SDK.
-
-#### Credenziali di runtime nelle funzioni logiche
-
-Quando la tua funzione viene eseguita su Twenty, la piattaforma inietta le credenziali come variabili d'ambiente prima dell'esecuzione del tuo codice:
-
-* `TWENTY_API_URL`: URL di base dell'API Twenty a cui punta la tua app.
-* `TWENTY_API_KEY`: Chiave a breve durata con ambito al ruolo funzione predefinito della tua applicazione.
-
-Note:
-
-* Non è necessario passare URL o chiave API al client generato. Legge `TWENTY_API_URL` e `TWENTY_API_KEY` da process.env in fase di esecuzione.
-* I permessi della chiave API sono determinati dal ruolo referenziato nel tuo `application-config.ts` tramite `defaultRoleUniversalIdentifier`. Questo è il ruolo predefinito utilizzato dalle funzioni logiche della tua applicazione.
-* Le applicazioni possono definire ruoli per seguire il principio del privilegio minimo. Concedi solo i permessi necessari alle tue funzioni, quindi punta `defaultRoleUniversalIdentifier` all'identificatore universale di quel ruolo.
-
-#### Caricamento dei file
-
-Il `MetadataApiClient` include un metodo `uploadFile` per allegare file ai campi di tipo file sugli oggetti del tuo spazio di lavoro. Poiché i client GraphQL standard non supportano nativamente il caricamento di file multipart, il client fornisce questo metodo dedicato che implementa la [specifica della richiesta GraphQL multipart](https://github.com/jaydenseric/graphql-multipart-request-spec) dietro le quinte.
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-import * as fs from 'fs';
-
-const metadataClient = new MetadataApiClient();
-
-const fileBuffer = fs.readFileSync('./invoice.pdf');
-
-const uploadedFile = await metadataClient.uploadFile(
- fileBuffer, // contenuto del file come Buffer
- 'invoice.pdf', // nome del file
- 'application/pdf', // Tipo MIME (predefinito: 'application/octet-stream')
- '58a0a314-d7ea-4865-9850-7fb84e72f30b', // identificatore universale del campo
-);
-
-console.log(uploadedFile);
-// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
-```
-
-La firma del metodo:
-
-```typescript
-uploadFile(
- fileBuffer: Buffer,
- filename: string,
- contentType: string,
- fieldMetadataUniversalIdentifier: string,
-): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
-```
-
-| Parametro | Tipo | Descrizione |
-| ---------------------------------- | -------- | ------------------------------------------------------------------------ |
-| `fileBuffer` | `Buffer` | Il contenuto grezzo del file |
-| `filename` | `string` | Il nome del file (utilizzato per l'archiviazione e la visualizzazione) |
-| `contentType` | `string` | Tipo MIME del file (predefinito su `application/octet-stream` se omesso) |
-| `fieldMetadataUniversalIdentifier` | `string` | L'`universalIdentifier` del campo di tipo file nel tuo oggetto |
-
-Punti chiave:
-
-* Il metodo `uploadFile` è disponibile su `MetadataApiClient` perché la mutazione di upload viene risolta dall'endpoint `/metadata`.
-* Usa l'`universalIdentifier` del campo (non il suo ID specifico dello spazio di lavoro), quindi il tuo codice di upload funziona in qualsiasi spazio di lavoro in cui la tua app è installata — coerentemente con il modo in cui le app fanno riferimento ai campi altrove.
-* L'`url` restituito è un URL firmato che puoi usare per accedere al file caricato.
-
-### Esempio Hello World
-
-Esplora un esempio minimale end-to-end che dimostra oggetti, funzioni logiche, componenti front-end e trigger multipli [qui](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
-
-## Compilazione della tua app
-
-Una volta che hai sviluppato la tua app con `app:dev`, usa `app:build` per compilarla in un pacchetto distribuibile.
-
-```bash filename="Terminal"
-# Compila l'app (l'output va in .twenty/output/)
-yarn twenty build
-
-# Compila e crea un tarball (.tgz) per la distribuzione
-yarn twenty build --tarball
-```
-
-Il processo di compilazione:
-
-1. **Analizza e convalida il manifest** — legge tutte le entità `defineX()` dai tuoi file sorgente e convalida la struttura del manifest.
-2. **Compila le funzioni di logica e i componenti front-end** — raggruppa i sorgenti TypeScript in file ESM `.mjs` usando esbuild.
-3. **Genera i checksum** — calcola gli hash MD5 per ogni file compilato, memorizzati nel manifest come `builtHandlerChecksum` / `builtComponentChecksum`.
-4. **Genera il client API tipizzato** — esegue l'analisi dello schema GraphQL e genera i client tipizzati `CoreApiClient` e `MetadataApiClient`.
-5. **Esegue un controllo dei tipi di TypeScript** — esegue `tsc --noEmit` per intercettare gli errori di tipo prima della pubblicazione.
-6. **Ricompila con il client generato** — esegue una seconda passata di compilazione in modo da includere i tipi del client generato.
-7. **Crea facoltativamente un tarball** — se viene passato `--tarball`, esegue `npm pack` per creare un file `.tgz` pronto per la distribuzione.
-
-L'output della build in `.twenty/output/` contiene:
-
-```text
-.twenty/output/
-├── manifest.json # Manifest con checksum per tutti i file compilati
-├── package.json # Copiato dalla radice dell'app
-├── yarn.lock # Copiato dalla radice dell'app
-├── src/
-│ ├── logic-functions/ # File .mjs compilati delle funzioni logiche
-│ └── front-components/ # File .mjs compilati dei componenti front-end
-├── public/ # Asset statici (se presenti)
-└── my-app-1.0.0.tgz # Solo con il flag --tarball
-```
-
-| Opzione | Descrizione |
-| ----------- | ------------------------------------------------------------------- |
-| `[appPath]` | Percorso della directory dell'app (predefinito: directory corrente) |
-| `--tarball` | Imballa anche l'output in un tarball `.tgz` |
-
-## Pubblicazione della tua app
-
-Usa `app:publish` per distribuire la tua app — al registro npm oppure direttamente a un server Twenty.
-
-### Pubblica su npm (predefinito)
-
-```bash filename="Terminal"
-# Pubblica su npm (richiede l'accesso a npm)
-yarn twenty publish
-
-# Pubblica con un dist-tag (ad es. beta, next)
-yarn twenty publish --tag beta
-```
-
-Questo compila l'app ed esegue `npm publish` dalla directory `.twenty/output/`. Il pacchetto pubblicato può quindi essere installato dal marketplace di Twenty da qualsiasi area di lavoro.
-
-### Pubblica su un server Twenty
-
-```bash filename="Terminal"
-# Pubblica direttamente su un server Twenty
-yarn twenty publish --server https://app.twenty.com
-```
-
-Questo compila l'app con un tarball, lo carica sul server tramite la mutation GraphQL `uploadAppTarball` e avvia l'installazione in un unico passaggio. Questo è utile per distribuzioni private o per effettuare test su un server specifico.
-
-| Opzione | Descrizione |
-| ----------------- | -------------------------------------------------------------------------- |
-| `[appPath]` | Percorso della directory dell'app (predefinito: directory corrente) |
-| `--server Archive this record?
- -
-
);
};
export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
+ universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+ name: 'hello-world',
+ description: 'A simple front component',
+ component: HelloWorld,
+ command: {
+ universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+ shortLabel: 'Hello',
+ label: 'Hello World',
+ icon: 'IconBolt',
+ isPinned: true,
+ availabilityType: 'GLOBAL',
+ },
});
```
-Pontos-chave:
+After syncing with `yarn twenty dev`, the quick action appears in the top-right corner of the page:
-* Componentes de front-end são componentes React que renderizam em contextos isolados dentro do Twenty.
-* O campo `component` faz referência ao seu componente React.
-* Os componentes são compilados e sincronizados automaticamente durante `yarn twenty dev`.
+My Custom Widget
-This is a custom front component for Twenty.
+Hello from my app!
+This component renders inside Twenty.
+
+
-Você pode criar novos componentes de front-end de duas formas:
+Click it to render the component inline.
-* **Gerado automaticamente**: Execute `yarn twenty entity:add` e escolha a opção para adicionar um novo componente de front-end.
-* **Manual**: Crie um novo arquivo `.tsx` e use `defineFrontComponent()`, seguindo o mesmo padrão.
+{/* TODO: add screenshot of the rendered front component */}
-### Habilidades
+#### Configuration fields
+
+| Campo | Obrigatório | Descrição |
+| --------------------- | ----------- | ----------------------------------------------------------------------------------- |
+| `universalIdentifier` | Sim | Stable unique ID for this component |
+| `component` | Sim | A React component function |
+| `name` | Não | Display name |
+| `description` | Não | Description of what the component does |
+| `isHeadless` | Não | Set to `true` if the component has no visible UI (see below) |
+| `command` | Não | Register the component as a command (see [command options](#command-options) below) |
+
+#### Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See the [definePageLayout](#definepagelayout) section for details.
+
+#### Headless components (`isHeadless: true`)
+
+Headless components render no visible UI but still run React logic. This is useful for **effect components** — components that perform side effects when mounted, such as syncing data, starting a timer, listening to events, or triggering a notification.
+
+```tsx src/front-components/sync-tracker.tsx
+import { defineFrontComponent, useRecordId, enqueueSnackbar } from 'twenty-sdk';
+import { useEffect } from 'react';
+
+const SyncTracker = () => {
+ const recordId = useRecordId();
+
+ useEffect(() => {
+ enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
+ }, [recordId]);
+
+ return null;
+};
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'sync-tracker',
+ description: 'Tracks record views silently',
+ isHeadless: true,
+ component: SyncTracker,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+#### Accessing runtime context
+
+Inside your component, use SDK hooks to access the current user, record, and component instance:
+
+```tsx src/front-components/record-info.tsx
+import {
+ defineFrontComponent,
+ useUserId,
+ useRecordId,
+ useFrontComponentId,
+} from 'twenty-sdk';
+
+const RecordInfo = () => {
+ const userId = useUserId();
+ const recordId = useRecordId();
+ const componentId = useFrontComponentId();
+
+ return (
+
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
+ name: 'record-info',
+ component: RecordInfo,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Descrição |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useRecordId()` | `string` or `null` | The current record's ID (when placed on a record page) |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | varia | Access the full execution context with a selector function |
+
+#### Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Função | Descrição |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Fecha o painel lateral |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+#### Command options
+
+Adding a `command` field to `defineFrontComponent` registers the component in the command menu (Cmd+K). If `isPinned` is `true`, it also appears as a quick-action button in the top-right corner of the page.
+
+| Campo | Obrigatório | Descrição |
+| --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `universalIdentifier` | Sim | Stable unique ID for the command |
+| `label` | Sim | Full label shown in the command menu (Cmd+K) |
+| `shortLabel` | Não | Shorter label displayed on the pinned quick-action button |
+| `icon` | Não | Icon name displayed next to the label (e.g. `'IconBolt'`, `'IconSend'`) |
+| `isPinned` | Não | When `true`, shows the command as a quick-action button in the top-right corner of the page |
+| `availabilityType` | Não | Controls where the command appears: `'GLOBAL'` (always available), `'RECORD_SELECTION'` (only when records are selected), or `'FALLBACK'` (shown when no other commands match) |
+| `availabilityObjectUniversalIdentifier` | Não | Restrict the command to pages of a specific object type (e.g. only on Company records) |
+| `conditionalAvailabilityExpression` | Não | A boolean expression to dynamically control whether the command is visible (see below) |
+
+#### Conditional availability expressions
+
+The `conditionalAvailabilityExpression` field lets you control when a command is visible based on the current page context. Import typed variables and operators from `twenty-sdk` to build expressions:
+
+```tsx
+import {
+ defineFrontComponent,
+ pageType,
+ numberOfSelectedRecords,
+ objectPermissions,
+ everyEquals,
+ isDefined,
+} from 'twenty-sdk';
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'bulk-action',
+ component: BulkAction,
+ command: {
+ universalIdentifier: '...',
+ label: 'Bulk Update',
+ availabilityType: 'RECORD_SELECTION',
+ conditionalAvailabilityExpression: everyEquals(
+ objectPermissions,
+ 'canUpdateObjectRecords',
+ true,
+ ),
+ },
+});
+```
+
+**Context variables** — these represent the current state of the page:
+
+| Variável | Tipo | Descrição |
+| ------------------------------ | --------- | ---------------------------------------------------------------- |
+| `pageType` | `string` | Current page type (e.g. `'RecordIndexPage'`, `'RecordShowPage'`) |
+| `isInSidePanel` | `boolean` | Whether the component is rendered in a side panel |
+| `numberOfSelectedRecords` | `number` | Number of currently selected records |
+| `isSelectAll` | `boolean` | Whether "select all" is active |
+| `selectedRecords` | `array` | The selected record objects |
+| `favoriteRecordIds` | `array` | IDs of favorited records |
+| `objectPermissions` | `object` | Permissions for the current object type |
+| `targetObjectReadPermissions` | `object` | Read permissions for the target object |
+| `targetObjectWritePermissions` | `object` | Write permissions for the target object |
+| `featureFlags` | `object` | Active feature flags |
+| `objectMetadataItem` | `object` | Metadata of the current object type |
+| `hasAnySoftDeleteFilterOnView` | `boolean` | Whether the current view has a soft-delete filter |
+
+**Operators** — combine variables into boolean expressions:
+
+| Operator | Descrição |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| `isDefined(value)` | `true` if the value is not null/undefined |
+| `isNonEmptyString(value)` | `true` if the value is a non-empty string |
+| `includes(array, value)` | `true` if the array contains the value |
+| `includesEvery(array, prop, value)` | `true` if every item's property includes the value |
+| `every(array, prop)` | `true` if the property is truthy on every item |
+| `everyDefined(array, prop)` | `true` if the property is defined on every item |
+| `everyEquals(array, prop, value)` | `true` if the property equals the value on every item |
+| `some(array, prop)` | `true` if the property is truthy on at least one item |
+| `someDefined(array, prop)` | `true` if the property is defined on at least one item |
+| `someEquals(array, prop, value)` | `true` if the property equals the value on at least one item |
+| `someNonEmptyString(array, prop)` | `true` if the property is a non-empty string on at least one item |
+| `none(array, prop)` | `true` if the property is falsy on every item |
+| `noneDefined(array, prop)` | `true` if the property is undefined on every item |
+| `noneEquals(array, prop, value)` | `true` if the property does not equal the value on any item |
+
+#### Public assets
+
+Front components can access files from the app's `public/` directory using `getPublicAssetUrl`:
+
+```tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk';
+
+const Logo = () => User: {userId}
+Record: {recordId ?? 'No record context'}
+Component: {componentId}
+;
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'logo',
+ component: Logo,
+});
+```
+
+See the [public assets section](#accessing-public-assets-with-getpublicasseturl) for details.
+
+#### Estilização
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { Button, Tag, Status } from 'twenty-sdk/ui';
+
+const StyledWidget = () => {
+ return (
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
+ name: 'styled-widget',
+ component: StyledWidget,
+});
+```
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step (`yarn twenty dev` or `yarn twenty build`) uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Scaffolding entities with `yarn twenty add` + +Instead of creating entity files by hand, you can use the interactive scaffolder: + +```bash filename="Terminal" +yarn twenty add +``` + +This prompts you to pick an entity type and walks you through the required fields. It generates a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call. + +You can also pass the entity type directly to skip the first prompt: + +```bash filename="Terminal" +yarn twenty add object +yarn twenty add logicFunction +yarn twenty add frontComponent +``` + +### Available entity types + +| Tipo de entidade | Comando | Generated file | +| -------------------- | ------------------------------------ | ------------------------------------- | +| Objeto | `yarn twenty add object` | `src/objects/
+
+
+
+## Step 3: Sign in to your workspace
+
+Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+## Step 4: Authorize the app
+
+After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
+
+Click **Authorize** to continue.
+
+
+
+
+
+
+Once authorized, your terminal will confirm that everything is set up.
+
+
+
+
+
+
+## Step 5: Start developing
+
+Go into your new app folder and start the development server:
+
+```bash filename="Terminal"
+cd my-twenty-app
yarn twenty dev
```
-O gerador de estrutura oferece suporte a dois modos para controlar quais arquivos de exemplo são incluídos:
+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.
+
+For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
```bash filename="Terminal"
-# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill, agent)
-npx create-twenty-app@latest my-app
-
-# Minimal: only core files (application-config.ts and default-role.ts)
-npx create-twenty-app@latest my-app --minimal
+yarn twenty dev --verbose
```
-A partir daqui você pode:
+
+
+
+
-# Watch your application's function logs
-yarn twenty function:logs
+## Step 6: See your app in Twenty
-# Execute a function by name
-yarn twenty function:execute -n my-function -p '{"name": "test"}'
+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**:
-# Execute the pre-install function
-yarn twenty function:execute --preInstall
+
+
+
+
-# Execute the post-install function
-yarn twenty function:execute --postInstall
+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.
-# Uninstall the application from the current workspace
-yarn twenty uninstall
+
+
+
+
-# Display commands' help
-yarn twenty help
-```
+Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
-Veja também: as páginas de referência da CLI para [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) e [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
+
+
+
+
-## Estrutura do projeto (com scaffold)
+Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
-Ao executar `npx create-twenty-app@latest my-twenty-app`, o gerador:
+
+
+
+
-* Copia um aplicativo base mínimo para `my-twenty-app/`
-* Adiciona uma dependência local `twenty-sdk` e a configuração do Yarn 4
-* Cria arquivos de configuração e scripts conectados à CLI `twenty`
-* Gera arquivos principais (configuração da aplicação, papel padrão para funções de lógica, funções de pré-instalação e pós-instalação) além de arquivos de exemplo com base no modo de geração de estrutura
+You are all set! Edit any file in `src/` and the changes will be picked up automatically.
-Um app recém-criado com o modo padrão `--exhaustive` fica assim:
+Head over to [Building Apps](/l/pt/developers/extend/apps/building) for a detailed guide on creating objects, logic functions, front components, skills, and more.
+
+---
+
+## Project structure
+
+The scaffolder generates the following file structure (shown with `--exhaustive` mode, which includes examples for every entity type):
```text filename="my-twenty-app/"
my-twenty-app/
@@ -94,124 +152,238 @@ my-twenty-app/
install-state.gz
.oxlintrc.json
tsconfig.json
+ tsconfig.spec.json # TypeScript config for tests
+ vitest.config.ts # Vitest test runner configuration
+ LLMS.md
README.md
- public/ # Public assets folder (images, fonts, etc.)
+ .github/
+ └── workflows/
+ └── ci.yml # GitHub Actions CI workflow
+ public/ # Public assets (images, fonts, etc.)
src/
- ├── application-config.ts # Required - main application configuration
+ ├── application-config.ts # Required — main application configuration
+ ├── __tests__/
+ │ ├── setup-test.ts # Test setup (server health check, config)
+ │ └── app-install.integration-test.ts # Example integration test
├── roles/
- │ └── default-role.ts # Default role for logic functions
+ │ └── default-role.ts # Default role for logic functions
├── objects/
- │ └── example-object.ts # Example custom object definition
+ │ └── example-object.ts # Example custom object definition
├── fields/
- │ └── example-field.ts # Example standalone field definition
+ │ └── example-field.ts # Example standalone field definition
├── logic-functions/
- │ ├── hello-world.ts # Example logic function
- │ ├── pre-install.ts # Pre-install logic function
- │ └── post-install.ts # Post-install logic function
+ │ ├── hello-world.ts # Example logic function
+ │ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
+ │ ├── pre-install.ts # Runs before installation
+ │ └── post-install.ts # Runs after installation
├── front-components/
- │ └── hello-world.tsx # Example front component
+ │ └── hello-world.tsx # Example front component
+ ├── page-layouts/
+ │ └── example-record-page-layout.ts # Example page layout with front component
├── views/
- │ └── example-view.ts # Example saved view definition
+ │ └── example-view.ts # Example saved view definition
├── navigation-menu-items/
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
- └── skills/
- └── example-skill.ts # Example AI agent skill definition
+ ├── skills/
+ │ └── example-skill.ts # Example AI agent skill definition
+ └── agents/
+ └── example-agent.ts # Example AI agent definition
```
-Com `--minimal`, apenas os arquivos principais são criados (`application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` e `logic-functions/post-install.ts`).
+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.
-Em alto nível:
+### Key files
-* **package.json**: Declara o nome do app, versão, engines (Node 24+, Yarn 4), e adiciona `twenty-sdk` além de um script `twenty` que delega para a CLI `twenty` local. Execute `yarn twenty help` para listar todos os comandos disponíveis.
-* **.gitignore**: Ignora artefatos comuns como `node_modules`, `.yarn`, `generated/` (cliente tipado), `dist/`, `build/`, pastas de cobertura, arquivos de log e arquivos `.env*`.
-* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Bloqueiam e configuram a ferramenta Yarn 4 usada pelo projeto.
-* **.nvmrc**: Fixa a versão do Node.js esperada pelo projeto.
-* **.oxlintrc.json** e **tsconfig.json**: Fornecem lint e configuração do TypeScript para os fontes TypeScript do seu aplicativo.
-* **README.md**: Um README curto na raiz do aplicativo com instruções básicas.
-* **public/**: Uma pasta para armazenar recursos públicos (imagens, fontes, arquivos estáticos) que serão servidos com sua aplicação. Os arquivos colocados aqui são enviados durante a sincronização e ficam acessíveis em tempo de execução.
-* **src/**: O local principal onde você define seu aplicativo como código
+| File / Folder | Finalidade |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `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/` | Habilidades que estendem os agentes de IA do 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. |
-### Detecção de entidades
+## Managing remotes
-O SDK detecta entidades analisando seus arquivos TypeScript em busca de chamadas **`export default define
+
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
-});
-
-```
-
-Pontos-chave:
-
-* Componentes de front-end são componentes React que renderizam em contextos isolados dentro do Twenty.
-* O campo `component` faz referência ao seu componente React.
-* Components are built and synced automatically during `yarn twenty dev`.
-
-Você pode criar novos componentes de front-end de duas formas:
-
-* **Gerado automaticamente**: Execute `yarn twenty entity:add` e escolha a opção para adicionar um novo componente de front-end.
-* **Manual**: Crie um novo ficheiro `.tsx` e use `defineFrontComponent()`, seguindo o mesmo padrão.
-
-#### Onde os componentes de front-end podem ser usados
-
-Os componentes de front-end podem ser renderizados em dois locais dentro do Twenty:
-
-* **Painel lateral** — Componentes de front-end não headless abrem no painel lateral direito. Este é o comportamento padrão quando um componente de front-end é acionado pelo menu de comandos.
-* **Widgets (painéis e páginas de registro)** — Componentes de front-end podem ser incorporados como widgets nos layouts de página. Ao configurar um painel ou o layout de uma página de registro, os usuários podem adicionar um widget de componente de front-end.
-
-#### Headless vs não headless
-
-Os componentes de front-end têm dois modos de renderização controlados pela opção `isHeadless`:
-
-**Não headless (padrão)** — O componente renderiza uma interface visível. Quando acionado pelo menu de comandos, ele é aberto no painel lateral. Este é o comportamento padrão quando `isHeadless` é `false` ou omitido.
-
-**Headless** — O componente é montado de forma invisível em segundo plano. Ele não abre o painel lateral. Componentes headless são projetados para ações que executam lógica e, em seguida, se desmontam — por exemplo, executar uma tarefa assíncrona, navegar para uma página ou exibir um modal de confirmação. Eles se combinam naturalmente com os componentes Command do SDK descritos abaixo.
-
-```typescript
-export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-action',
- description: 'Runs an action without opening the side panel',
- component: MyAction,
- isHeadless: true,
- command: {
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
- label: 'Run my action',
- },
-});
-```
-
-#### Adicionando itens ao menu de comandos
-
-Para que um componente de front-end apareça como um item no menu de comandos do Twenty, adicione a propriedade `command` a `defineFrontComponent()`. Quando os usuários abrem o menu de comandos (Cmd+K / Ctrl+K), o item aparece e aciona o componente de front-end ao clicar.
-
-O objeto `command` aceita os seguintes campos:
-
-| Campo | Tipo | Descrição |
-| --------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | `string` (obrigatório) | ID exclusivo para o item do menu de comandos |
-| `etiqueta` | `string` (obrigatório) | Rótulo exibido no menu de comandos |
-| `ícone` | `string` (opcional) | Nome do ícone (por exemplo, `'IconSparkles'`) |
-| `isPinned` | `boolean` (opcional) | Se o comando fica fixado no topo do menu |
-| `availabilityType` | `'GLOBAL' \| 'RECORD_SELECTION'` (opcional) | `GLOBAL` mostra o comando em todos os lugares; `RECORD_SELECTION` o mostra apenas em contextos de registro |
-| `availabilityObjectUniversalIdentifier` | `string` (opcional) | Restringe o comando a um tipo específico de objeto (por exemplo, Person) |
-
-Aqui está um exemplo do app de gravação de chamadas que adiciona um comando com escopo para registros de Person:
-
-```typescript
-import { defineFrontComponent } from 'twenty-sdk';
-
-export default defineFrontComponent({
- universalIdentifier: 'c3d4e5f6-a7b8-9012-cdef-123456789012',
- name: 'Summarize Person Call Recordings',
- description: 'Generates a summary of call recordings for a person',
- component: SummarizePersonRecordings,
- command: {
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-234567890123',
- label: 'Summarize call recordings',
- icon: 'IconSparkles',
- isPinned: false,
- availabilityType: 'RECORD_SELECTION',
- availabilityObjectUniversalIdentifier:
- '20202020-e674-48e5-a542-72570eee7213',
- },
-});
-```
-
-Quando o comando é sincronizado, ele aparece no menu de comandos. Se o componente de front-end não for headless, o painel lateral é aberto com o componente renderizado dentro. Se for headless, o componente é montado em segundo plano e executa sua lógica.
-
-#### Componentes Command do SDK
-
-O pacote `twenty-sdk` fornece quatro componentes auxiliares Command projetados para componentes de front-end headless. Cada componente executa uma ação ao montar, trata erros exibindo uma notificação de snackbar e desmonta automaticamente o componente de front-end ao concluir.
-
-Importe-os de `twenty-sdk/command`:
-
-* **`Command`** — Executa um callback assíncrono via a prop `execute`.
-* **`CommandLink`** — Navega para um caminho do app. Props: `to`, `params`, `queryParams`, `options`.
-* **`CommandModal`** — Abre um modal de confirmação. Se o usuário confirmar, executa o callback `execute`. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
-* **`CommandOpenSidePanelPage`** — Abre uma página específica do painel lateral. Props: `page`, `pageTitle`, `pageIcon`.
-
-Aqui está um exemplo completo de um componente de front-end headless usando `Command` para executar uma ação a partir do menu de comandos:
-
-```typescript
-// src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk';
-import { Command } from 'twenty-sdk/command';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const RunAction = () => {
- const execute = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- createTask: {
- __args: { data: { title: 'Created by my app' } },
- id: true,
- },
- });
- };
-
- return My Custom Widget
-This is a custom front component for Twenty.
-
-
- );
-};
-```
-
-O contexto é reativo — se o registro de contexto mudar, os hooks retornam automaticamente os valores atualizados.
-
-#### Funções da API do host
-
-Os componentes de front-end são executados em um sandbox isolado, mas podem interagir com a UI do Twenty por meio de um conjunto de funções fornecidas pelo host. Importe-as diretamente de `twenty-sdk`:
-
-```typescript
-import {
- navigate,
- closeSidePanel,
- enqueueSnackbar,
- unmountFrontComponent,
- openSidePanelPage,
- openCommandConfirmationModal,
-} from 'twenty-sdk';
-```
-
-| Função | Assinatura | Descrição |
-| ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `navegar` | `(to, params?, queryParams?, options?) => PromiseRecord: {recordId ?? 'none'}
-User: {userId ?? 'anonymous'}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Habilidades
-
-As habilidades definem instruções e capacidades reutilizáveis que os agentes de IA podem usar no seu espaço de trabalho. Use `defineSkill()` para definir habilidades com validação integrada:
-
-```typescript
-// src/skills/example-skill.ts
-import { defineSkill } from 'twenty-sdk';
-
-export default defineSkill({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-outreach',
- label: 'Sales Outreach',
- description: 'Guides the AI agent through a structured sales outreach process',
- icon: 'IconBrain',
- content: `You are a sales outreach assistant. When reaching out to a prospect:
-1. Research the company and recent news
-2. Identify the prospect's role and likely pain points
-3. Draft a personalized message referencing specific details
-4. Keep the tone professional but conversational`,
-});
-```
-
-Pontos-chave:
-
-* `name` é uma string de identificador exclusivo para a habilidade (recomenda-se kebab-case).
-* `label` é o nome de exibição legível por humanos mostrado na UI.
-* `content` contém as instruções da habilidade — este é o texto que o agente de IA usa.
-* `icon` (opcional) define o ícone exibido na UI.
-* `description` (opcional) fornece contexto adicional sobre a finalidade da habilidade.
-
-Você pode criar novas habilidades de duas formas:
-
-* **Gerado automaticamente**: Execute `yarn twenty entity:add` e escolha a opção para adicionar uma nova habilidade.
-* **Manual**: Crie um novo arquivo e use `defineSkill()`, seguindo o mesmo padrão.
-
-### Agentes
-
-Agentes definem agentes de IA com prompts do sistema que podem operar no seu espaço de trabalho. Use `defineAgent()` para definir agentes com validação integrada:
-
-```typescript
-// src/agents/example-agent.ts
-import { defineAgent } from 'twenty-sdk';
-
-export default defineAgent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'sales-assistant',
- label: 'Sales Assistant',
- description: 'An AI agent that helps with sales tasks',
- icon: 'IconRobot',
- prompt: `You are a sales assistant. Help users with:
-1. Researching prospects and companies
-2. Drafting personalized outreach messages
-3. Tracking follow-ups and next steps
-4. Analyzing deal pipeline and suggesting actions`,
-});
-```
-
-Pontos-chave:
-
-* `name` é uma string de identificador exclusivo para o agente (recomenda-se kebab-case).
-* `label` é o nome de exibição legível por humanos mostrado na UI.
-* `prompt` contém o prompt do sistema — este é o texto de instruções que define o comportamento do agente.
-* `icon` (opcional) define o ícone exibido na UI.
-* `description` (opcional) fornece contexto adicional sobre a finalidade do agente.
-
-Você pode criar novos agentes de duas formas:
-
-* **Gerado automaticamente**: Execute `yarn twenty entity:add` e escolha a opção para adicionar um novo agente.
-* **Manual**: Crie um novo arquivo e use `defineAgent()`, seguindo o mesmo padrão.
-
-### Clientes tipados gerados
-
-Two typed clients are auto-generated by `yarn twenty dev` and stored in `node_modules/twenty-sdk/clients` based on your workspace schema:
-
-* **`CoreApiClient`** — consulta o endpoint `/graphql` para dados do espaço de trabalho
-* **`MetadataApiClient`** — consulta o endpoint `/metadata` para obter a configuração do espaço de trabalho e o carregamento de ficheiros
-
-```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-
-const client = new CoreApiClient();
-const { me } = await client.query({ me: { id: true, displayName: true } });
-
-const metadataClient = new MetadataApiClient();
-const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
-```
-
-`CoreApiClient` is re-generated automatically by `yarn twenty dev` whenever your objects or fields change. `MetadataApiClient` é fornecido pré-compilado com o SDK.
-
-#### Credenciais em tempo de execução em funções de lógica
-
-Quando sua função é executada no Twenty, a plataforma injeta credenciais como variáveis de ambiente antes da execução do seu código:
-
-* `TWENTY_API_URL`: URL base da API do Twenty que seu aplicativo usa como alvo.
-* `TWENTY_API_KEY`: Chave de curta duração com escopo para o papel de função padrão do seu aplicativo.
-
-Notas:
-
-* Você não precisa passar a URL ou a chave de API para o cliente gerado. Ele lê `TWENTY_API_URL` e `TWENTY_API_KEY` de process.env em tempo de execução.
-* As permissões da chave de API são determinadas pelo papel referenciado no seu `application-config.ts` via `defaultRoleUniversalIdentifier`. Este é o papel padrão usado pelas funções de lógica do seu app.
-* Os aplicativos podem definir papéis para seguir o princípio do menor privilégio. Conceda apenas as permissões de que suas funções precisam e, em seguida, aponte `defaultRoleUniversalIdentifier` para o identificador universal desse papel.
-
-#### Carregamento de ficheiros
-
-`MetadataApiClient` inclui um método `uploadFile` para anexar ficheiros a campos do tipo ficheiro nos objetos do seu espaço de trabalho. Como os clientes GraphQL padrão não suportam nativamente o carregamento de ficheiros multipart, o cliente fornece este método dedicado que implementa, nos bastidores, a [especificação de pedidos multipart do GraphQL](https://github.com/jaydenseric/graphql-multipart-request-spec).
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-import * as fs from 'fs';
-
-const metadataClient = new MetadataApiClient();
-
-const fileBuffer = fs.readFileSync('./invoice.pdf');
-
-const uploadedFile = await metadataClient.uploadFile(
- fileBuffer, // file contents as a Buffer
- 'invoice.pdf', // filename
- 'application/pdf', // MIME type (defaults to 'application/octet-stream')
- '58a0a314-d7ea-4865-9850-7fb84e72f30b', // field universal identifier
-);
-
-console.log(uploadedFile);
-// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
-```
-
-A assinatura do método:
-
-```typescript
-uploadFile(
- fileBuffer: Buffer,
- filename: string,
- contentType: string,
- fieldMetadataUniversalIdentifier: string,
-): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
-```
-
-| Parâmetro | Tipo | Descrição |
-| ---------------------------------- | -------- | ------------------------------------------------------------------------ |
-| `fileBuffer` | `Buffer` | O conteúdo bruto do arquivo |
-| `filename` | `string` | O nome do arquivo (usado para armazenamento e exibição) |
-| `contentType` | `string` | Tipo MIME do arquivo (padrão para `application/octet-stream` se omitido) |
-| `fieldMetadataUniversalIdentifier` | `string` | O `universalIdentifier` do campo do tipo arquivo no seu objeto |
-
-Pontos-chave:
-
-* O método `uploadFile` está disponível no `MetadataApiClient` porque a mutação de upload é resolvida pelo endpoint `/metadata`.
-* Ele usa o `universalIdentifier` do campo (não o ID específico do espaço de trabalho), de modo que seu código de upload funcione em qualquer espaço de trabalho onde seu app esteja instalado — consistente com a forma como os apps referenciam campos em qualquer outro lugar.
-* A `url` retornada é um URL assinado que você pode usar para acessar o arquivo enviado.
-
-### Exemplo Hello World
-
-Explore um exemplo mínimo de ponta a ponta que demonstra objetos, funções de lógica, componentes de front-end e vários gatilhos [aqui](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
-
-## Compilando seu app
-
-Depois de desenvolver seu app com `app:dev`, use `app:build` para compilá-lo em um pacote distribuível.
-
-```bash filename="Terminal"
-# Build the app (output goes to .twenty/output/)
-yarn twenty build
-
-# Build and create a tarball (.tgz) for distribution
-yarn twenty build --tarball
-```
-
-O processo de build:
-
-1. **Analisa e valida o manifesto** — lê todas as entidades `defineX()` dos seus arquivos de código-fonte e valida a estrutura do manifesto.
-2. **Compila funções de lógica e componentes de front-end** — empacota o código-fonte TypeScript em arquivos ESM `.mjs` usando o esbuild.
-3. **Gera checksums** — calcula hashes MD5 para cada arquivo gerado, armazenados no manifesto como `builtHandlerChecksum` / `builtComponentChecksum`.
-4. **Gera o cliente de API tipado** — inspeciona o esquema GraphQL e gera clientes tipados `CoreApiClient` e `MetadataApiClient`.
-5. **Executa uma verificação de tipos do TypeScript** — executa `tsc --noEmit` para detectar erros de tipo antes da publicação.
-6. **Reconstrói com o cliente gerado** — realiza uma segunda passagem de compilação para que os tipos do cliente gerado sejam incluídos.
-7. **Opcionalmente cria um tarball** — se `--tarball` for passado, executa `npm pack` para criar um arquivo `.tgz` pronto para distribuição.
-
-A saída da compilação em `.twenty/output/` contém:
-
-```text
-.twenty/output/
-├── manifest.json # Manifesto com somas de verificação para todos os arquivos compilados
-├── package.json # Copiado da raiz do aplicativo
-├── yarn.lock # Copiado da raiz do aplicativo
-├── src/
-│ ├── logic-functions/ # Arquivos .mjs compilados de funções de lógica
-│ └── front-components/ # Arquivos .mjs compilados de componentes de front-end
-├── public/ # Recursos estáticos (se houver)
-└── my-app-1.0.0.tgz # Apenas com a opção --tarball
-```
-
-| Opção | Descrição |
-| ----------- | --------------------------------------------------------- |
-| `[appPath]` | Caminho para o diretório do app (padrão: diretório atual) |
-| `--tarball` | Também empacota a saída em um tarball `.tgz` |
-
-## Publicando seu app
-
-Use `app:publish` para distribuir seu app — ou para o registro do npm ou diretamente para um servidor Twenty.
-
-### Publicar no npm (padrão)
-
-```bash filename="Terminal"
-# Publish to npm (requires npm login)
-yarn twenty publish
-
-# Publish with a dist-tag (e.g. beta, next)
-yarn twenty publish --tag beta
-```
-
-Isso compila o app e executa `npm publish` a partir do diretório `.twenty/output/`. O pacote publicado pode então ser instalado no marketplace da Twenty por qualquer espaço de trabalho.
-
-### Publicar em um servidor Twenty
-
-```bash filename="Terminal"
-# Publish directly to a Twenty server
-yarn twenty publish --server https://app.twenty.com
-```
-
-Isso compila o app com um tarball, faz o upload para o servidor via a mutação GraphQL `uploadAppTarball` e aciona a instalação em uma única etapa. Isso é útil para implantações privadas ou para testar em um servidor específico.
-
-| Opção | Descrição |
-| ----------------- | --------------------------------------------------------------------- |
-| `[appPath]` | Caminho para o diretório do app (padrão: diretório atual) |
-| `--server Archive this record?
- -
-
);
};
export default defineFrontComponent({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- name: 'my-widget',
- description: 'A custom widget component',
- component: MyWidget,
+ universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+ name: 'hello-world',
+ description: 'A simple front component',
+ component: HelloWorld,
+ command: {
+ universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+ shortLabel: 'Hello',
+ label: 'Hello World',
+ icon: 'IconBolt',
+ isPinned: true,
+ availabilityType: 'GLOBAL',
+ },
});
```
-Puncte cheie:
+After syncing with `yarn twenty dev`, the quick action appears in the top-right corner of the page:
-* Componentele Front sunt componente React care sunt randate în contexte izolate în cadrul Twenty.
-* Câmpul `component` face referire la componenta React.
-* Componentele sunt construite și sincronizate automat în timpul `yarn twenty dev`.
+My Custom Widget
-This is a custom front component for Twenty.
+Hello from my app!
+This component renders inside Twenty.
+
+
-Puteți crea componente Front noi în două moduri:
+Click it to render the component inline.
-* **Generat**: Rulați `yarn twenty add` și alegeți opțiunea de a adăuga o componentă Front nouă.
-* **Manual**: Creați un fișier nou `.tsx` și folosiți `defineFrontComponent()`, urmând același model.
+{/* TODO: add screenshot of the rendered front component */}
-### Abilități
+#### Configuration fields
+
+| Câmp | Obligatoriu | Descriere |
+| --------------------- | ----------- | ----------------------------------------------------------------------------------- |
+| `universalIdentifier` | Da | Stable unique ID for this component |
+| `component` | Da | A React component function |
+| `name` | Nu | Display name |
+| `description` | Nu | Description of what the component does |
+| `isHeadless` | Nu | Set to `true` if the component has no visible UI (see below) |
+| `command` | Nu | Register the component as a command (see [command options](#command-options) below) |
+
+#### Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See the [definePageLayout](#definepagelayout) section for details.
+
+#### Headless components (`isHeadless: true`)
+
+Headless components render no visible UI but still run React logic. This is useful for **effect components** — components that perform side effects when mounted, such as syncing data, starting a timer, listening to events, or triggering a notification.
+
+```tsx src/front-components/sync-tracker.tsx
+import { defineFrontComponent, useRecordId, enqueueSnackbar } from 'twenty-sdk';
+import { useEffect } from 'react';
+
+const SyncTracker = () => {
+ const recordId = useRecordId();
+
+ useEffect(() => {
+ enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
+ }, [recordId]);
+
+ return null;
+};
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'sync-tracker',
+ description: 'Tracks record views silently',
+ isHeadless: true,
+ component: SyncTracker,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+#### Accessing runtime context
+
+Inside your component, use SDK hooks to access the current user, record, and component instance:
+
+```tsx src/front-components/record-info.tsx
+import {
+ defineFrontComponent,
+ useUserId,
+ useRecordId,
+ useFrontComponentId,
+} from 'twenty-sdk';
+
+const RecordInfo = () => {
+ const userId = useUserId();
+ const recordId = useRecordId();
+ const componentId = useFrontComponentId();
+
+ return (
+
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
+ name: 'record-info',
+ component: RecordInfo,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Descriere |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useRecordId()` | `string` or `null` | The current record's ID (when placed on a record page) |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | variază | Access the full execution context with a selector function |
+
+#### Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Funcție | Descriere |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Close the side panel |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+#### Command options
+
+Adding a `command` field to `defineFrontComponent` registers the component in the command menu (Cmd+K). If `isPinned` is `true`, it also appears as a quick-action button in the top-right corner of the page.
+
+| Câmp | Obligatoriu | Descriere |
+| --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `universalIdentifier` | Da | Stable unique ID for the command |
+| `label` | Da | Full label shown in the command menu (Cmd+K) |
+| `shortLabel` | Nu | Shorter label displayed on the pinned quick-action button |
+| `icon` | Nu | Icon name displayed next to the label (e.g. `'IconBolt'`, `'IconSend'`) |
+| `isPinned` | Nu | When `true`, shows the command as a quick-action button in the top-right corner of the page |
+| `availabilityType` | Nu | Controls where the command appears: `'GLOBAL'` (always available), `'RECORD_SELECTION'` (only when records are selected), or `'FALLBACK'` (shown when no other commands match) |
+| `availabilityObjectUniversalIdentifier` | Nu | Restrict the command to pages of a specific object type (e.g. only on Company records) |
+| `conditionalAvailabilityExpression` | Nu | A boolean expression to dynamically control whether the command is visible (see below) |
+
+#### Conditional availability expressions
+
+The `conditionalAvailabilityExpression` field lets you control when a command is visible based on the current page context. Import typed variables and operators from `twenty-sdk` to build expressions:
+
+```tsx
+import {
+ defineFrontComponent,
+ pageType,
+ numberOfSelectedRecords,
+ objectPermissions,
+ everyEquals,
+ isDefined,
+} from 'twenty-sdk';
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'bulk-action',
+ component: BulkAction,
+ command: {
+ universalIdentifier: '...',
+ label: 'Bulk Update',
+ availabilityType: 'RECORD_SELECTION',
+ conditionalAvailabilityExpression: everyEquals(
+ objectPermissions,
+ 'canUpdateObjectRecords',
+ true,
+ ),
+ },
+});
+```
+
+**Context variables** — these represent the current state of the page:
+
+| Variabilă | Tip | Descriere |
+| ------------------------------ | --------- | ---------------------------------------------------------------- |
+| `pageType` | `string` | Current page type (e.g. `'RecordIndexPage'`, `'RecordShowPage'`) |
+| `isInSidePanel` | `boolean` | Whether the component is rendered in a side panel |
+| `numberOfSelectedRecords` | `number` | Number of currently selected records |
+| `isSelectAll` | `boolean` | Whether "select all" is active |
+| `selectedRecords` | `array` | The selected record objects |
+| `favoriteRecordIds` | `array` | IDs of favorited records |
+| `objectPermissions` | `object` | Permissions for the current object type |
+| `targetObjectReadPermissions` | `object` | Read permissions for the target object |
+| `targetObjectWritePermissions` | `object` | Write permissions for the target object |
+| `featureFlags` | `object` | Active feature flags |
+| `objectMetadataItem` | `object` | Metadata of the current object type |
+| `hasAnySoftDeleteFilterOnView` | `boolean` | Whether the current view has a soft-delete filter |
+
+**Operators** — combine variables into boolean expressions:
+
+| Operator | Descriere |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| `isDefined(value)` | `true` if the value is not null/undefined |
+| `isNonEmptyString(value)` | `true` if the value is a non-empty string |
+| `includes(array, value)` | `true` if the array contains the value |
+| `includesEvery(array, prop, value)` | `true` if every item's property includes the value |
+| `every(array, prop)` | `true` if the property is truthy on every item |
+| `everyDefined(array, prop)` | `true` if the property is defined on every item |
+| `everyEquals(array, prop, value)` | `true` if the property equals the value on every item |
+| `some(array, prop)` | `true` if the property is truthy on at least one item |
+| `someDefined(array, prop)` | `true` if the property is defined on at least one item |
+| `someEquals(array, prop, value)` | `true` if the property equals the value on at least one item |
+| `someNonEmptyString(array, prop)` | `true` if the property is a non-empty string on at least one item |
+| `none(array, prop)` | `true` if the property is falsy on every item |
+| `noneDefined(array, prop)` | `true` if the property is undefined on every item |
+| `noneEquals(array, prop, value)` | `true` if the property does not equal the value on any item |
+
+#### Public assets
+
+Front components can access files from the app's `public/` directory using `getPublicAssetUrl`:
+
+```tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk';
+
+const Logo = () => User: {userId}
+Record: {recordId ?? 'No record context'}
+Component: {componentId}
+;
+
+export default defineFrontComponent({
+ universalIdentifier: '...',
+ name: 'logo',
+ component: Logo,
+});
+```
+
+See the [public assets section](#accessing-public-assets-with-getpublicasseturl) for details.
+
+#### Stilizare
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { Button, Tag, Status } from 'twenty-sdk/ui';
+
+const StyledWidget = () => {
+ return (
+
+
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
+ name: 'styled-widget',
+ component: StyledWidget,
+});
+```
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step (`yarn twenty dev` or `yarn twenty build`) uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Scaffolding entities with `yarn twenty add` + +Instead of creating entity files by hand, you can use the interactive scaffolder: + +```bash filename="Terminal" +yarn twenty add +``` + +This prompts you to pick an entity type and walks you through the required fields. It generates a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call. + +You can also pass the entity type directly to skip the first prompt: + +```bash filename="Terminal" +yarn twenty add object +yarn twenty add logicFunction +yarn twenty add frontComponent +``` + +### Available entity types + +| Tipul entității | Comandă | Generated file | +| -------------------- | ------------------------------------ | ------------------------------------- | +| Obiect | `yarn twenty add object` | `src/objects/
+
+
+
+## Step 3: Sign in to your workspace
+
+Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+## Step 4: Authorize the app
+
+After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
+
+Click **Authorize** to continue.
+
+
+
+
+
+
+Once authorized, your terminal will confirm that everything is set up.
+
+
+
+
+
+
+## Step 5: Start developing
+
+Go into your new app folder and start the development server:
```bash filename="Terminal"
-# Add a new entity to your application (guided)
-yarn twenty add
-
-# Watch your application's function logs
-yarn twenty function:logs
-
-# Execute a function by name
-yarn twenty function:execute -n my-function -p '{"name": "test"}'
-
-# Execute the pre-install function
-yarn twenty function:execute --preInstall
-
-# Execute the post-install function
-yarn twenty function:execute --postInstall
-
-# Uninstall the application from the current workspace
-yarn twenty uninstall
-
-# Display commands' help
-yarn twenty help
+cd my-twenty-app
+yarn twenty dev
```
-Consultați și: paginile de referință CLI pentru [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) și [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
+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.
-## Structura proiectului (generată)
+For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
-Când rulați `npx create-twenty-app@latest my-twenty-app`, generatorul:
+```bash filename="Terminal"
+yarn twenty dev --verbose
+```
-* Copiază o aplicație de bază minimală în `my-twenty-app/`
-* Adaugă o dependență locală `twenty-sdk` și configurația Yarn 4
-* Creează fișiere de configurare și scripturi conectate la CLI-ul `twenty`
-* Generează fișierele de bază (configurația aplicației, rolul implicit al funcțiilor, funcțiile de pre-instalare și post-instalare) plus fișiere de exemplu în funcție de modul de generare a scheletului.
+
+
+
+
+
+## Step 6: See your app in 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**:
+
+
+
+
+
+
+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.
+
+
+
+
+
+
+Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
+
+
+
+
+
+
+Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
+
+
+
+
+
+
+You are all set! Edit any file in `src/` and the changes will be picked up automatically.
+
+Head over to [Building Apps](/l/ro/developers/extend/apps/building) for a detailed guide on creating objects, logic functions, front components, skills, and more.
+
+---
+
+## Project structure
+
+The scaffolder generates the following file structure (shown with `--exhaustive` mode, which includes examples for every entity type):
```text filename="my-twenty-app/"
my-twenty-app/
@@ -83,124 +152,238 @@ my-twenty-app/
install-state.gz
.oxlintrc.json
tsconfig.json
+ tsconfig.spec.json # TypeScript config for tests
+ vitest.config.ts # Vitest test runner configuration
+ LLMS.md
README.md
- public/ # Public assets folder (images, fonts, etc.)
+ .github/
+ └── workflows/
+ └── ci.yml # GitHub Actions CI workflow
+ public/ # Public assets (images, fonts, etc.)
src/
- ├── application-config.ts # Required - main application configuration
+ ├── application-config.ts # Required — main application configuration
+ ├── __tests__/
+ │ ├── setup-test.ts # Test setup (server health check, config)
+ │ └── app-install.integration-test.ts # Example integration test
├── roles/
- │ └── default-role.ts # Default role for logic functions
+ │ └── default-role.ts # Default role for logic functions
├── objects/
- │ └── example-object.ts # Example custom object definition
+ │ └── example-object.ts # Example custom object definition
├── fields/
- │ └── example-field.ts # Example standalone field definition
+ │ └── example-field.ts # Example standalone field definition
├── logic-functions/
- │ ├── hello-world.ts # Example logic function
- │ ├── pre-install.ts # Pre-install logic function
- │ └── post-install.ts # Post-install logic function
+ │ ├── hello-world.ts # Example logic function
+ │ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
+ │ ├── pre-install.ts # Runs before installation
+ │ └── post-install.ts # Runs after installation
├── front-components/
- │ └── hello-world.tsx # Example front component
+ │ └── hello-world.tsx # Example front component
+ ├── page-layouts/
+ │ └── example-record-page-layout.ts # Example page layout with front component
├── views/
- │ └── example-view.ts # Example saved view definition
+ │ └── example-view.ts # Example saved view definition
├── navigation-menu-items/
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
- └── skills/
- └── example-skill.ts # Example AI agent skill definition
+ ├── skills/
+ │ └── example-skill.ts # Example AI agent skill definition
+ └── agents/
+ └── example-agent.ts # Example AI agent definition
```
-Cu `--minimal`, sunt create doar fișierele de bază (`application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` și `logic-functions/post-install.ts`).
+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.
-Pe scurt:
+### Key files
-* **package.json**: Declară numele aplicației, versiunea, motoarele (Node 24+, Yarn 4) și adaugă `twenty-sdk` plus un script `twenty` care deleagă către CLI-ul local `twenty`. Rulați `yarn twenty help` pentru a lista toate comenzile disponibile.
-* **.gitignore**: Ignoră artefacte comune precum `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, foldere de coverage, fișiere jurnal și fișiere `.env*`.
-* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Blochează și configurează lanțul de instrumente Yarn 4 folosit de proiect.
-* **.nvmrc**: Fixează versiunea Node.js așteptată de proiect.
-* **.oxlintrc.json** și **tsconfig.json**: Oferă linting și configurație TypeScript pentru fișierele TypeScript ale aplicației.
-* **README.md**: Un README scurt în rădăcina aplicației, cu instrucțiuni de bază.
-* **public/**: Un folder pentru stocarea resurselor publice (imagini, fonturi, fișiere statice) care vor fi servite împreună cu aplicația dvs. Fișierele plasate aici sunt încărcate în timpul sincronizării și sunt accesibile la rulare.
-* **src/**: Locul principal unde vă definiți aplicația sub formă de cod
+| File / Folder | Scop |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `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/` | Abilități care extind capabilitățile agenților AI ai 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. |
-### Detectarea entităților
+## Managing remotes
-SDK-ul detectează entitățile analizând fișierele TypeScript pentru apeluri **`export default define
+
-