Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### كيف يعمل التجميع - -تستخدم خطوة البناء أداة esbuild لإنتاج ملف واحد مستقل لكل دالة منطقية ولكل مكوّن أمامي. تُضمَّن جميع الحزم المستوردة داخل الحزمة. - -**الدوال المنطقية** تعمل في بيئة Node.js. الوحدات المدمجة في Node (`fs` و`path` و`crypto` و`http` وغيرها) متاحة ولا تحتاج إلى تثبيت. - -**المكوّنات الأمامية** تعمل ضمن Web Worker. وحدات Node المدمجة غير متاحة — المتاح فقط واجهات برمجة المتصفّح وحِزَم npm التي تعمل في بيئة المتصفّح. - -كلتا البيئتين تحتويان على `twenty-client-sdk/core` و`twenty-client-sdk/metadata` كوحدات متاحة مُسبقًا — لا تُضمَّن هذه ضمن الحزم بل تُحلّ وقت التشغيل بواسطة الخادم. - -## اختبار تطبيقك - -يوفّر SDK واجهات برمجة قابلة للتنفيذ برمجيًا تمكّنك من بناء تطبيقك ونشره وتثبيته وإلغاء تثبيته من شيفرة الاختبار. بالاقتران مع [Vitest](https://vitest.dev/) وعملاء واجهة البرمجة مضبوطي الأنواع، يمكنك كتابة اختبارات تكامل تتحقّق من أن تطبيقك يعمل من البداية إلى النهاية مقابل خادم Twenty حقيقي. - -### إعداد - -يتضمّن التطبيق المُولَّد بالقالب بالفعل Vitest. إذا أعددته يدويًا، فثبّت التبعيات: - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -أنشئ `vitest.config.ts` في جذر تطبيقك: - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -أنشئ ملف إعداد يتحقّق من إمكانية الوصول إلى الخادم قبل تشغيل الاختبارات: - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### واجهات SDK البرمجية - -يُصدِّر المسار الفرعي `twenty-sdk/cli` دوالًا يمكنك استدعاؤها مباشرةً من شيفرة الاختبار: - -| دالة | الوصف | -| -------------- | ----------------------------------------- | -| `appBuild` | بناء التطبيق واختياريًا حزم ملف tarball | -| `appDeploy` | رفع ملف tarball إلى الخادم | -| `appInstall` | تثبيت التطبيق على مساحة العمل النشطة | -| `appUninstall` | إلغاء تثبيت التطبيق من مساحة العمل النشطة | - -تُرجع كل دالة كائن نتيجة يحتوي على `success: boolean` وعلى إمّا `data` أو `error`. - -### كتابة اختبار تكامل - -إليك مثالًا كاملًا يبني التطبيق وينشره ويثبّته، ثم يتحقّق من ظهوره في مساحة العمل: - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### تشغيل الاختبارات - -تأكّد من تشغيل خادم Twenty المحلي لديك، ثم: - -```bash filename="Terminal" -yarn test -``` - -أو في وضع المراقبة أثناء التطوير: - -```bash filename="Terminal" -yarn test:watch -``` - -### التحقق من الأنواع - -يمكنك أيضًا تشغيل التحقق من الأنواع على تطبيقك دون تشغيل الاختبارات: - -```bash filename="Terminal" -yarn twenty typecheck -``` - -يشغِّل هذا الأمر `tsc --noEmit` ويبلغ عن أي أخطاء في الأنواع. - -## مرجع CLI - -بالإضافة إلى `dev` و`build` و`add` و`typecheck`، يوفّر CLI أوامر لتنفيذ الدوال وعرض السجلات وإدارة تثبيتات التطبيقات. - -### تنفيذ الدوال (`yarn twenty exec`) - -تشغيل دالة منطقية يدويًا دون تشغيلها عبر HTTP أو cron أو حدث قاعدة بيانات: - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### عرض سجلات الدوال (`yarn twenty logs`) - -بثّ سجلات التنفيذ لدوال تطبيقك المنطقية: - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- 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` (أو تشغيل الأمر لمرة واحدة `yarn twenty dev --once`)، يظهر الإجراء السريع في الزاوية العلوية اليمنى من الصفحة:
-
-Hello from my app!
-This component renders inside Twenty.
-
- 
-
-
-انقره لعرض المكوّن مضمنًا داخل الصفحة.
-
-## حقول التكوين
-
-| الحقل | مطلوب | الوصف |
-| --------------------- | ----- | ----------------------------------------------------------------- |
-| `universalIdentifier` | نعم | معرّف فريد ثابت لهذا المكوّن |
-| `component` | نعم | دالة مكوّن React |
-| `name` | لا | اسم العرض |
-| `description` | لا | وصف لما يفعله المكوّن |
-| `isHeadless` | لا | عيِّنه إلى `true` إذا كان المكوّن بلا واجهة مرئية (انظر أدناه) |
-| `command` | لا | سجّل المكوّن كأمر (انظر [خيارات الأوامر](#command-options) أدناه) |
-
-## وضع مكوّن أمامي على صفحة
-
-إضافةً إلى الأوامر، يمكنك تضمين مكوّن أمامي مباشرةً في صفحة سجل عبر إضافته كودجت في **تخطيط صفحة**. راجع قسم [definePageLayout](/l/ar/developers/extend/apps/skills-and-agents#definepagelayout) للتفاصيل.
-
-## عديم الرأس مقابل غير عديم الرأس
-
-تأتي مكوّنات الواجهة الأمامية بوضعَي عرض يتحكّم بهما الخيار `isHeadless`:
-
-**غير عديم الرأس (افتراضي)** — يعرض المكوّن واجهة مستخدم مرئية. عند تشغيله من قائمة الأوامر يفتح في اللوحة الجانبية. هذا هو السلوك الافتراضي عندما تكون `isHeadless` تساوي `false` أو يتم تجاهلها.
-
-**عديم الرأس (`isHeadless: true`)** — يتم تركيب المكوّن بشكل غير مرئي في الخلفية. لا يفتح اللوحة الجانبية. تم تصميم المكوّنات عديمة الرأس لإجراءات تنفّذ منطقًا ثم تُزيل تركيبها ذاتيًا — على سبيل المثال، تشغيل مهمة غير متزامنة، أو الانتقال إلى صفحة، أو إظهار نافذة تأكيد منبثقة. تتوافق بشكل طبيعي مع مكوّنات Command في SDK الموصوفة أدناه.
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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 يتخطّى عرض حاوية له — ولن تظهر مساحة فارغة في التخطيط. لا يزال لدى المكوّن إمكانية الوصول إلى جميع الخطافات وواجهة برمجة الاتصال مع المضيف.
-
-## مكوّنات 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` لتشغيل إجراء من قائمة الأوامر:
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-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)` | تحديث مؤشّر التقدّم |
-
-فيما يلي مثال يستخدم واجهة برمجة تطبيقات المضيف لعرض Snackbar وإغلاق اللوحة الجانبية بعد اكتمال الإجراء:
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-## خيارات الأوامر
-
-إضافة حقل `command` إلى `defineFrontComponent` تُسجِّل المكوّن في قائمة الأوامر (Cmd+K). إذا كانت قيمة `isPinned` هي `true`، فسيظهر أيضًا كزر إجراء سريع في الزاوية العلوية اليمنى من الصفحة.
-
-| الحقل | مطلوب | الوصف |
-| --------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `universalIdentifier` | نعم | معرّف فريد ثابت للأمر |
-| `label` | نعم | التسمية الكاملة المعروضة في قائمة الأوامر (Cmd+K) |
-| `shortLabel` | لا | تسمية أقصر تُعرَض على زر الإجراء السريع المثبّت |
-| `icon` | لا | اسم الأيقونة المعروض بجانب التسمية (مثل `'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/define';
-
-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` | `boolean` | ما إذا كان المكوّن معروضًا في لوحة جانبية |
-| `numberOfSelectedRecords` | `number` | عدد السجلات المحدّدة حاليًا |
-| `isSelectAll` | `boolean` | ما إذا كان "تحديد الكل" مفعّلًا |
-| `selectedRecords` | `array` | كائنات السجلات المحدّدة |
-| `favoriteRecordIds` | `array` | معرّفات السجلات المفضّلة |
-| `objectPermissions` | `object` | الأذونات الخاصة بنوع الكائن الحالي |
-| `targetObjectReadPermissions` | `object` | أذونات القراءة للكائن الهدف |
-| `targetObjectWritePermissions` | `object` | أذونات الكتابة للكائن الهدف |
-| `featureFlags` | `object` | أعلام الميزات المفعَّلة |
-| `objectMetadataItem` | `object` | بيانات التعريف لنوع الكائن الحالي |
-| `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/define';
-
-const Logo = () => Archive this record?
- -})
;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-راجع [قسم الأصول العامة](/l/ar/developers/extend/apps/cli-and-testing#public-assets-public-folder) للتفاصيل.
-
-## التنسيق
-
-تدعم المكوّنات الأمامية عدة أساليب للتنسيق. يمكنك استخدام:
-
-* **أنماط مضمنة** — `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/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index dbd5c15296..0000000000
--- a/packages/twenty-docs/l/ar/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,282 +0,0 @@
----
-title: البدء
-icon: rocket
-description: أنشئ أول تطبيق Twenty خلال دقائق.
----
-
-## ما هي التطبيقات؟
-
-تتيح لك التطبيقات توسيع Twenty باستخدام كائنات وحقول مخصّصة ووظائف منطقية ومكوّنات الواجهة الأمامية ومهارات الذكاء الاصطناعي وغير ذلك — جميعها تُدار ككود. بدلًا من تكوين كل شيء عبر واجهة المستخدم، تعرّف نموذج بياناتك ومنطقك في TypeScript وتقوم بنشره إلى مساحة عمل واحدة أو أكثر.
-
-## المتطلبات الأساسية
-
-قبل أن تبدأ، تأكّد من تثبيت ما يلي على جهازك:
-
-* **Node.js 24+** — [نزّل من هنا](https://nodejs.org/)
-* **Yarn 4** — يأتي مع Node.js عبر Corepack. قم بتمكينه عبر تشغيل `corepack enable`
-* **Docker** — [نزّل من هنا](https://www.docker.com/products/docker-desktop/). مطلوب لتشغيل مثيل محلي من Twenty. غير مطلوب إذا كان لديك خادم Twenty قيد التشغيل بالفعل.
-
-## قم بإنشاء تطبيقك الأول
-
-### أنشئ هيكل تطبيقك
-
-افتح الطرفية وشغّل:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-سيُطلب منك إدخال اسم ووصف لتطبيقك. اضغط **Enter** لقبول الإعدادات الافتراضية.
-
-سيؤدي ذلك إلى إنشاء مجلد جديد باسم `my-twenty-app` يحتوي على كل ما تحتاجه.
-
-### إعداد مثيل محلي من Twenty
-
-ستسأل أداة إنشاء الهيكل:
-
-> **هل ترغب في إعداد مثيل محلي من Twenty؟**
-
-* **اكتب `yes`** (موصى به) — سيؤدي ذلك إلى سحب صورة Docker `twenty-app-dev` وبدء تشغيل خادم Twenty محلي على المنفذ `2020`. تأكّد من أن Docker قيد التشغيل قبل المتابعة.
-* **اكتب `no`** — اختر هذا إذا كان لديك خادم Twenty يعمل محليًا بالفعل.
-
-
- 
-
-
-### سجّل الدخول إلى مساحة العمل الخاصة بك
-
-بعد ذلك، ستُفتح نافذة متصفح تعرض صفحة تسجيل الدخول الخاصة بـ Twenty. سجّل الدخول باستخدام حساب العرض التوضيحي المُجهَّز مسبقًا:
-
-* **البريد الإلكتروني:** `tim@apple.dev`
-* **كلمة المرور:** `tim@apple.dev`
-
-
-
- 
-
-
-### قم بتفويض التطبيق
-
-بعد تسجيل الدخول، ستظهر لك شاشة تفويض. يتيح هذا لتطبيقك التفاعل مع مساحة العمل الخاصة بك.
-
-انقر **Authorize** للمتابعة.
-
-
-
- 
-
-
-بمجرد منح التفويض، ستؤكّد الطرفية أن كل شيء قد تم إعداده.
-
-
-
- 
-
-
-### ابدأ التطوير
-
-انتقل إلى مجلد تطبيقك الجديد وابدأ خادم التطوير:
-
-```bash filename="Terminal"
-cd my-twenty-app
-yarn twenty dev
-```
-
-يقوم هذا بمراقبة ملفات المصدر لديك، وإعادة البناء عند كل تغيير، ومزامنة تطبيقك تلقائيًا مع خادم Twenty المحلي. يفترض أن ترى لوحة حالة مباشرة في الطرفية.
-
-للحصول على مخرجات أكثر تفصيلاً (سجلات البناء، طلبات المزامنة، تتبعات الأخطاء)، استخدم العلم `--verbose`:
-
-```bash filename="Terminal"
-yarn twenty dev --verbose
-```
-
-
-
- 
-
-
-#### مزامنة لمرة واحدة باستخدام `yarn twenty dev --once`
-
-إذا كنت لا تريد تشغيل مراقب في الخلفية (مثلًا في خط أنابيب CI، أو خطاف Git، أو سير عمل مُؤتمت عبر سكربت)، فمرِّر الخيار `--once`. يُشغِّل خط الأنابيب نفسه مثل `yarn twenty dev` — إنشاء بيان البناء، تجميع الملفات، الرفع، المزامنة، إعادة توليد عميل API مضبوط الأنواع — ولكنه **ينهي التنفيذ فور اكتمال المزامنة**:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| أمر | السلوك | متى يُستخدم |
-| ------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `yarn twenty dev` | يراقب ملفات المصدر ويعيد المزامنة عند كل تغيير. يستمر بالتشغيل حتى توقفه. | تطوير محلي تفاعلي — تريد لوحة حالة مباشرة وحلقة تغذية راجعة فورية. |
-| `yarn twenty dev --once` | يجري عملية بناء واحدة + مزامنة واحدة، ثم ينهي التنفيذ برمز `0` عند النجاح أو `1` عند الفشل. | البرامج النصية، وCI، وخطافات ما قبل الالتزام، ووكلاء الذكاء الاصطناعي، وأي سير عمل غير تفاعلي. |
-
-كلا الوضعين يتطلبان خادم Twenty يعمل في وضع التطوير وجهة بعيدة موثَّقة — تنطبق المتطلبات المسبقة نفسها.
-
-### اعرض تطبيقك في Twenty
-
-افتح [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) في متصفحك. انتقل إلى **Settings > Apps** واختر علامة التبويب **Developer**. يُفترض أن ترى تطبيقك مُدرجًا تحت **Your Apps**:
-
-
-
- 
-
-
-انقر على **My twenty app** لفتح **تسجيل التطبيق** الخاص به. التسجيل عبارة عن سجل على مستوى الخادم يصف تطبيقك — اسمه، والمعرّف الفريد، وبيانات اعتماد OAuth، والمصدر (محلي، npm، أو tarball). يُخزَّن على الخادم، وليس داخل أي مساحة عمل محددة. عند تثبيت تطبيق في مساحة عمل، ينشئ Twenty **تطبيقًا** بنطاق مساحة العمل يُشير مرة أخرى إلى هذا التسجيل. يمكن تثبيت تسجيل واحد عبر عدة مساحات عمل على الخادم نفسه.
-
-
-
- 
-
-
-انقر **View installed app** لعرض التطبيق المثبّت. تعرض علامة التبويب **About** الإصدار الحالي وخيارات الإدارة:
-
-
-
- 
-
-
-انتقل إلى علامة التبويب **Content** لمشاهدة كل ما يقدمه تطبيقك — الكائنات، والحقول، ودوال المنطق، والوكلاء:
-
-
-
- 
-
-
-أنت جاهز تمامًا! حرّر أي ملف في `src/` وسيتم التقاط التغييرات تلقائيًا.
-
----
-
-## ما الذي يمكنك بناؤه
-
-تتكون التطبيقات من **كيانات** — يُعرَّف كل منها كملف TypeScript يحتوي على `export default` واحد:
-
-| كيان | ماذا يفعل |
-| ---------------------- | ------------------------------------------------------------------------------------------------- |
-| **الكائنات والحقول** | عرّف نماذج بيانات مخصّصة (مثل Post Card، Invoice) مع حقول محددة النوع |
-| **الوظائف المنطقية** | دوال TypeScript على جانب الخادم يتم تشغيلها عبر مسارات HTTP، وجداول cron، أو أحداث قاعدة البيانات |
-| **المكوّنات الأمامية** | مكوّنات React تُعرَض داخل واجهة مستخدم Twenty (اللوحة الجانبية، الودجات، قائمة الأوامر) |
-| **المهارات والوكلاء** | قدرات الذكاء الاصطناعي — تعليمات قابلة لإعادة الاستخدام ومساعدون مستقلون ذاتيًا |
-| **طرق العرض والتنقّل** | طرق عرض القوائم مُعدّة مسبقًا وعناصر قائمة الشريط الجانبي لكائناتك |
-| **تخطيطات الصفحات** | صفحات تفاصيل سجلات مخصصة تتضمن علامات تبويب وعناصر واجهة |
-
-انتقل إلى [بناء التطبيقات](/l/ar/developers/extend/apps/building) للاطلاع على دليل مفصّل لكل نوع من الكيانات.
-
----
-
-## هيكل المشروع
-
-تولّد أداة إنشاء الهيكل بنية الملفات التالية:
-
-```text filename="my-twenty-app/"
-my-twenty-app/
- package.json
- yarn.lock
- .gitignore
- .nvmrc
- .yarnrc.yml
- .oxlintrc.json
- tsconfig.json
- tsconfig.spec.json # TypeScript config for tests
- vitest.config.ts # Vitest test runner configuration
- LLMS.md
- README.md
- .github/
- └── workflows/
- └── ci.yml # GitHub Actions CI workflow
- public/ # Public assets (images, fonts, etc.)
- src/
- ├── application-config.ts # Required — main application configuration
- ├── default-role.ts # Default role for logic functions
- ├── constants/
- │ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
- └── __tests__/
- ├── setup-test.ts # Test setup (server health check, config)
- └── app-install.integration-test.ts # Integration test
-```
-
-### البدء من مثال
-
-للبدء من مثال أكثر اكتمالًا يضم كائنات وحقولًا مخصّصة، ودوال المنطق، ومكوّنات الواجهة الأمامية، وغير ذلك، استخدم الخيار `--example`:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app --example postcard
-```
-
-تُستمد الأمثلة من الدليل [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) على GitHub. يمكنك أيضًا إنشاء هيكل لكيانات فردية داخل مشروع قائم باستخدام `yarn twenty add` (انظر [بناء التطبيقات](/l/ar/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
-
-### الملفات الرئيسية
-
-| ملف / مجلد | الغرض |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `package.json` | يصرّح باسم تطبيقك وإصداره واعتماداته. يتضمن نصًا برمجيًا باسم `twenty` بحيث يمكنك تشغيل `yarn twenty help` للاطلاع على جميع الأوامر. |
-| `src/application-config.ts` | **مطلوب.** ملف الإعداد الرئيسي لتطبيقك. |
-| `src/default-role.ts` | الدور الافتراضي الذي يتحكم بما يمكن لدوال المنطق الوصول إليه. |
-| `src/constants/universal-identifiers.ts` | معرّفات UUID وبيانات التعريف للتطبيق، والمولَّدة تلقائيًا (اسم العرض، الوصف). |
-| `src/__tests__/` | اختبارات تكامل (إعداد + اختبار مثال). |
-| `public/` | أصول ثابتة (صور، خطوط) تُقدَّم مع تطبيقك. |
-
-## خادم التطوير المحلي
-
-لقد قامت أداة إنشاء الهيكل بالفعل بتشغيل خادم Twenty محليًا لك. لإدارته لاحقًا، استخدم `yarn twenty server`:
-
-| أمر | الوصف |
-| -------------------------------------- | --------------------------------------------- |
-| `yarn twenty server start` | بدء الخادم المحلي (يسحب الصورة إذا لزم الأمر) |
-| `yarn twenty server start --port 3030` | ابدأ على منفذ مخصّص |
-| `yarn twenty server start --test` | ابدأ مثيل اختبار منفصل على المنفذ 2021 |
-| `yarn twenty server stop` | إيقاف الخادم (مع الحفاظ على البيانات) |
-| `yarn twenty server status` | عرض حالة الخادم، وعنوان URL، وبيانات الاعتماد |
-| `yarn twenty server logs` | بث سجلات الخادم |
-| `yarn twenty server logs --lines 100` | عرض آخر 100 سطر من السجلات |
-| `yarn twenty server reset` | حذف جميع البيانات والبدء من جديد |
-
-يتم الاحتفاظ بالبيانات عبر عمليات إعادة التشغيل في وحدتي تخزين Docker (`twenty-app-dev-data` لـ PostgreSQL، و`twenty-app-dev-storage` للملفات). استخدم `reset` لمسح كل شيء والبدء من جديد.
-
-### تشغيل مثيل الاختبار
-
-مرر `--test` إلى أي أمر `server` لإدارة مثيل ثانٍ معزول تمامًا — مفيد لتشغيل اختبارات التكامل أو للتجربة من دون لمس بيانات التطوير الرئيسية لديك.
-
-| أمر | الوصف |
-| ---------------------------------- | ---------------------------------------------------- |
-| `yarn twenty server start --test` | بدء مثيل الاختبار (المنفذ الافتراضي 2021) |
-| `yarn twenty server stop --test` | إيقاف مثيل الاختبار |
-| `yarn twenty server status --test` | عرض حالة مثيل الاختبار، وعنوان URL، وبيانات الاعتماد |
-| `yarn twenty server logs --test` | بث سجلات مثيل الاختبار |
-| `yarn twenty server reset --test` | محو بيانات الاختبار والبدء من جديد |
-
-يعمل مثيل الاختبار في حاوية Docker خاصة به (`twenty-app-dev-test`) مع وحدات تخزين مخصصة (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) وتهيئة مستقلة، بحيث يمكنه العمل بالتوازي مع مثيلك الرئيسي من دون تعارضات. اجمع `--test` مع `--port` لتجاوز القيمة الافتراضية 2021.
-
-
-Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### Jak funguje bundlování - -Krok sestavení 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á. - -## Testování vaší aplikace - -SDK poskytuje programová rozhraní, která vám umožní z testovacího kódu aplikaci sestavit, nasadit, nainstalovat a odinstalovat. V kombinaci s [Vitest](https://vitest.dev/) a typovanými klienty API můžete psát integrační testy, které ověří, že vaše aplikace funguje end-to-end proti reálnému serveru Twenty. - -### Nastavení - -Vygenerovaná aplikace již obsahuje Vitest. Pokud to nastavujete ručně, nainstalujte závislosti: - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -Vytvořte `vitest.config.ts` v kořeni vaší aplikace: - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -Vytvořte soubor nastavení, který před spuštěním testů ověří dostupnost serveru: - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### Programová rozhraní SDK - -Subcesta `twenty-sdk/cli` exportuje funkce, které můžete volat přímo z testovacího kódu: - -| Funkce | Popis | -| -------------- | ----------------------------------------------------- | -| `appBuild` | Sestaví aplikaci a volitelně zabalí tarball | -| `appDeploy` | Nahraje tarball na server | -| `appInstall` | Nainstaluje aplikaci do aktivního pracovního prostoru | -| `appUninstall` | Odinstaluje aplikaci z aktivního pracovního prostoru | - -Každá funkce vrací objekt výsledku se `success: boolean` a buď `data`, nebo `error`. - -### Psání integračního testu - -Zde je kompletní příklad, který aplikaci sestaví, nasadí a nainstaluje a poté ověří, že se objeví v pracovním prostoru: - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### Spuštění testů - -Ujistěte se, že běží váš lokální server Twenty, a poté: - -```bash filename="Terminal" -yarn test -``` - -Nebo v režimu watch během vývoje: - -```bash filename="Terminal" -yarn test:watch -``` - -### Kontrola typů - -Kontrolu typů můžete spustit i na vaší aplikaci bez spuštění testů: - -```bash filename="Terminal" -yarn twenty typecheck -``` - -Spustí se `tsc --noEmit` a nahlásí se případné chyby typů. - -## Referenční dokumentace CLI - -Kromě `dev`, `build`, `add` a `typecheck` poskytuje CLI příkazy pro spouštění funkcí, zobrazení logů a správu instalací aplikací. - -### Spouštění funkcí (`yarn twenty exec`) - -Spusťte logickou funkci ručně bez vyvolání přes HTTP, cron nebo databázovou událost: - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### Zobrazení logů funkcí (`yarn twenty logs`) - -Streamujte výstupní logy běhu logických funkcí vaší aplikace: - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- 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',
- },
-});
-```
-
-Po synchronizaci pomocí `yarn twenty dev` (nebo po jednorázovém spuštění `yarn twenty dev --once`) se rychlá akce zobrazí v pravém horním rohu stránky:
-
-Hello from my app!
-This component renders inside Twenty.
-
-
-
-
-Kliknutím na něj vykreslíte komponentu přímo ve stránce.
-
-## 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](/l/cs/developers/extend/apps/skills-and-agents#definepagelayout).
-
-## Headless vs. ne-headless
-
-Front-endové 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 (`isHeadless: true`)** — 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.
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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.
-
-## Komponenty SDK Command
-
-Balíček `twenty-sdk` poskytuje čtyři pomocné komponenty Command navržené pro headless front-endové 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-endovou 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-endové komponenty, která pomocí `Command` spouští akci z menu příkazů:
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-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řít postranní panel |
-| `openCommandConfirmationModal(params)` | Zobrazit potvrzovací dialog |
-| `enqueueSnackbar(params)` | Zobrazit oznámení typu toast |
-| `unmountFrontComponent()` | Odpojit komponentu |
-| `updateProgress(progress)` | Aktualizovat indikátor průběhu |
-
-Zde je příklad, který používá hostitelské API k zobrazení snackbaru a zavření postranního panelu po dokončení akce:
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-## 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/define';
-
-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 má vlastnost alespoň u jedné položky hodnotu neprázdného řetězce |
-| `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é soubory
-
-Frontendové komponenty mohou přistupovat k souborům ze složky aplikace `public/` pomocí `getPublicAssetUrl`:
-
-```tsx
-import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
-
-const Logo = () => Archive this record?
- -;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-Podrobnosti viz [sekci veřejných souborů](/l/cs/developers/extend/apps/cli-and-testing#public-assets-public-folder).
-
-## 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/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index b513fd1a24..0000000000
--- a/packages/twenty-docs/l/cs/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,282 +0,0 @@
----
-title: Začínáme
-icon: rocket
-description: Vytvořte svou první aplikaci Twenty během několika minut.
----
-
-## Co jsou aplikace?
-
-Aplikace vám umožňují rozšířit Twenty o vlastní objekty, pole, logické funkce, frontendové komponenty, AI schopnosti a další — vše je spravováno jako kód. Místo konfigurace všeho přes uživatelské rozhraní definujete v TypeScriptu svůj datový model a logiku a nasadíte je do jednoho nebo více pracovních prostorů.
-
-## Předpoklady
-
-Než začnete, ujistěte se, že máte ve svém počítači nainstalováno následující:
-
-* **Node.js 24+** — [Stáhnout zde](https://nodejs.org/)
-* **Yarn 4** — Dodává se s Node.js prostřednictvím Corepacku. Povolte jej spuštěním `corepack enable`
-* **Docker** — [Stáhnout zde](https://www.docker.com/products/docker-desktop/). Nutné pro spuštění lokální instance Twenty. Není potřeba, pokud už máte spuštěný server Twenty.
-
-## Vytvořte svou první aplikaci
-
-### Vytvořte kostru své aplikace
-
-Otevřete terminál a spusťte:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-Budete vyzváni k zadání názvu a popisu své aplikace. Stisknutím **Enter** přijmete výchozí hodnoty.
-
-Tím se vytvoří nová složka s názvem `my-twenty-app` se vším potřebným.
-
-### Nastavte lokální instanci Twenty
-
-Generátor kostry se zeptá:
-
-> **Chcete nastavit lokální instanci Twenty?**
-
-* **Zadejte `yes`** (doporučeno) — Stáhne image Dockeru `twenty-app-dev` a spustí lokální server Twenty na portu `2020`. Než budete pokračovat, ujistěte se, že Docker běží.
-* **Zadejte `no`** — Zvolte, pokud už máte lokálně spuštěný server Twenty.
-
-
-
-
-
-### Přihlaste se do svého pracovního prostoru
-
-Poté se otevře okno prohlížeče se stránkou přihlášení do Twenty. Přihlaste se předpřipraveným demo účtem:
-
-* **E-mail:** `tim@apple.dev`
-* **Heslo:** `tim@apple.dev`
-
-
-
-
-
-
-### Autorizujte aplikaci
-
-Po přihlášení uvidíte autorizační obrazovku. Tím umožníte vaší aplikaci pracovat s vaším pracovním prostorem.
-
-Pokračujte kliknutím na **Authorize**.
-
-
-
-
-
-
-Po autorizaci váš terminál potvrdí, že je vše nastaveno.
-
-
-
-
-
-
-### Začněte vyvíjet
-
-Přejděte do nové složky aplikace a spusťte vývojový server:
-
-```bash filename="Terminal"
-cd my-twenty-app
-yarn twenty dev
-```
-
-Sleduje zdrojové soubory, při každé změně znovu sestaví a automaticky synchronizuje vaši aplikaci s lokálním serverem Twenty. V terminálu byste měli vidět panel se stavem v reálném čase.
-
-Pro podrobnější výstup (protokoly sestavení, požadavky na synchronizaci, stopy chyb) použijte přepínač `--verbose`:
-
-```bash filename="Terminal"
-yarn twenty dev --verbose
-```
-
-
-
-
-
-
-#### Jednorázová synchronizace pomocí `yarn twenty dev --once`
-
-Pokud nechcete, aby na pozadí běžel watcher (například v CI pipeline, git hooku nebo skriptovaném workflow), použijte příznak `--once`. Spouští stejnou pipeline jako `yarn twenty dev` — sestaví manifest, zabalí soubory, nahraje, synchronizuje, znovu vygeneruje typovaného klienta API — ale **ukončí se, jakmile se synchronizace dokončí**:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Příkaz | Chování | Kdy použít |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `yarn twenty dev` | Sleduje vaše zdrojové soubory a při každé změně znovu spustí synchronizaci. Zůstává spuštěný, dokud jej nezastavíte. | Interaktivní lokální vývoj — chcete živý panel stavu a okamžitou zpětnovazebnou smyčku. |
-| `yarn twenty dev --once` | Provede jedno sestavení + synchronizaci, poté ukončí běh s kódem `0` při úspěchu nebo `1` při neúspěchu. | Skripty, CI, pre-commit hooky, AI agenti a jakýkoli neinteraktivní pracovní postup. |
-
-Oba režimy vyžadují server Twenty běžící v režimu vývoje a autentizovaný remote — platí stejné požadavky.
-
-### Zobrazte svou aplikaci v Twenty
-
-Otevřete ve svém prohlížeči [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Přejděte do **Settings > Apps** a vyberte kartu **Developer**. Vaše aplikace by měla být uvedena v části **Your Apps**:
-
-
-
-
-
-
-Klikněte na **My twenty app** a otevřete její **registraci aplikace**. Registrace je záznam na úrovni serveru, který popisuje vaši aplikaci — její název, jedinečný identifikátor, přihlašovací údaje OAuth a zdroj (lokální, npm nebo tarball). Existuje na serveru, ne uvnitř žádného konkrétního pracovního prostoru. Když nainstalujete aplikaci do pracovního prostoru, Twenty vytvoří **aplikaci** v rozsahu pracovního prostoru, která odkazuje zpět na tuto registraci. Jedna registrace může být nainstalována ve více pracovních prostorech na stejném serveru.
-
-
-
-
-
-
-Klikněte na **View installed app**, abyste zobrazili nainstalovanou aplikaci. Karta **About** zobrazuje aktuální verzi a možnosti správy:
-
-
-
-
-
-
-Přepněte na kartu **Content**, abyste viděli vše, co vaše aplikace poskytuje — objekty, pole, logické funkce a agenty:
-
-
-
-
-
-
-Vše je připraveno! Upravte libovolný soubor v `src/` a změny se automaticky projeví.
-
----
-
-## Co můžete vytvořit
-
-Aplikace se skládají z **entit** — každá je definována jako soubor TypeScriptu s jediným `export default`:
-
-| Entita | K čemu slouží |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| **Objekty a pole** | Definujte vlastní datové modely (např. Post Card, Invoice) s typovanými poli |
-| **Logické funkce** | Serverové funkce v TypeScriptu spouštěné HTTP trasami, plánovačem cron nebo událostmi databáze |
-| **Frontendové komponenty** | Komponenty Reactu, které se vykreslují v uživatelském rozhraní Twenty (postranní panel, widgety, příkazová nabídka) |
-| **Dovednosti a agenti** | Schopnosti AI — opakovaně použitelné pokyny a autonomní asistenti |
-| **Pohledy a navigace** | Předkonfigurované seznamové pohledy a položky postranní nabídky pro vaše objekty |
-| **Rozvržení stránek** | Vlastní stránky detailu záznamu s kartami a widgety |
-
-Přejděte na [Tvorba aplikací](/l/cs/developers/extend/apps/building) pro podrobný průvodce každým typem entity.
-
----
-
-## Struktura projektu
-
-Nástroj pro vytvoření kostry vygeneruje následující strukturu souborů:
-
-```text filename="my-twenty-app/"
-my-twenty-app/
- package.json
- yarn.lock
- .gitignore
- .nvmrc
- .yarnrc.yml
- .oxlintrc.json
- tsconfig.json
- tsconfig.spec.json # TypeScript config for tests
- vitest.config.ts # Vitest test runner configuration
- LLMS.md
- README.md
- .github/
- └── workflows/
- └── ci.yml # GitHub Actions CI workflow
- public/ # Public assets (images, fonts, etc.)
- src/
- ├── application-config.ts # Required — main application configuration
- ├── default-role.ts # Default role for logic functions
- ├── constants/
- │ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
- └── __tests__/
- ├── setup-test.ts # Test setup (server health check, config)
- └── app-install.integration-test.ts # Integration test
-```
-
-### Začínáme s příkladem
-
-Chcete-li začít s úplnějším příkladem s vlastními objekty, poli, logickými funkcemi, frontendovými komponentami a dalšími, použijte přepínač `--example`:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app --example postcard
-```
-
-Příklady pocházejí z adresáře [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) na GitHubu. Můžete také vytvořit kostru jednotlivých entit v existujícím projektu pomocí `yarn twenty add` (viz [Tvorba aplikací](/l/cs/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
-
-### Klíčové soubory
-
-| Soubor / Složka | Účel |
-| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `package.json` | Definuje název, verzi a závislosti vaší aplikace. Obsahuje skript `twenty`, takže můžete spustit `yarn twenty help` a zobrazit všechny příkazy. |
-| `src/application-config.ts` | **Povinné.** Hlavní konfigurační soubor vaší aplikace. |
-| `src/default-role.ts` | Výchozí role, která určuje, k čemu mají vaše logické funkce přístup. |
-| `src/constants/universal-identifiers.ts` | Automaticky generovaná UUID a metadata aplikace (zobrazovaný název, popis). |
-| `src/__tests__/` | Integrační testy (nastavení + ukázkový test). |
-| `public/` | Statická aktiva (obrázky, písma) poskytovaná s vaší aplikací. |
-
-## Lokální vývojový server
-
-Nástroj pro vytvoření kostry vám již spustil lokální server Twenty. Pro jeho správu později použijte `yarn twenty server`:
-
-| Příkaz | Popis |
-| -------------------------------------- | ------------------------------------------------------ |
-| `yarn twenty server start` | Spustí lokální server (v případě potřeby stáhne image) |
-| `yarn twenty server start --port 3030` | Spustí na vlastním portu |
-| `yarn twenty server start --test` | Spusťte samostatnou testovací instanci na portu 2021 |
-| `yarn twenty server stop` | Zastaví server (zachová data) |
-| `yarn twenty server status` | Zobrazí stav serveru, URL a přihlašovací údaje |
-| `yarn twenty server logs` | Streamuje protokoly serveru |
-| `yarn twenty server logs --lines 100` | Zobrazí posledních 100 řádků logu |
-| `yarn twenty server reset` | Smaže všechna data a začne znovu |
-
-Data přetrvávají při restartech ve dvou svazcích Dockeru (`twenty-app-dev-data` pro PostgreSQL, `twenty-app-dev-storage` pro soubory). Pomocí `reset` vymažte vše a začněte znovu.
-
-### Spuštění testovací instance
-
-Předejte volbu `--test` libovolnému příkazu `server` pro správu druhé, plně izolované instance — užitečné pro spouštění integračních testů nebo experimentování, aniž byste se dotkli svých hlavních vývojových dat.
-
-| Příkaz | Popis |
-| ---------------------------------- | --------------------------------------------------------- |
-| `yarn twenty server start --test` | Spustí testovací instanci (výchozí port je 2021) |
-| `yarn twenty server stop --test` | Zastaví testovací instanci |
-| `yarn twenty server status --test` | Zobrazí stav testovací instance, URL a přihlašovací údaje |
-| `yarn twenty server logs --test` | Streamuje protokoly testovací instance |
-| `yarn twenty server reset --test` | Vymaže testovací data a začne znovu |
-
-Testovací instance běží ve vlastním kontejneru Docker (`twenty-app-dev-test`) s vyhrazenými svazky (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) a konfigurací, takže může běžet paralelně s vaší hlavní instancí bez konfliktů. Zkombinujte `--test` s `--port` pro změnu výchozího portu 2021.
-
-
-Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### Wie das Bundling funktioniert - -Der Build-Schritt verwendet esbuild, um pro Logikfunktion und pro Frontend-Komponente eine einzelne, in sich geschlossene Datei zu erzeugen. Alle importierten Pakete werden in das Bundle eingebettet. - -**Logikfunktionen** laufen in einer Node.js-Umgebung. Eingebaute Node.js-Module (`fs`, `path`, `crypto`, `http` usw.) stehen zur Verfügung und müssen nicht installiert werden. - -**Frontend-Komponenten** laufen in einem Web Worker. Eingebaute Node.js-Module sind **nicht** verfügbar — nur Browser-APIs und npm-Pakete, die in einer Browserumgebung funktionieren. - -In beiden Umgebungen stehen `twenty-client-sdk/core` und `twenty-client-sdk/metadata` als vorab bereitgestellte Module zur Verfügung — sie werden nicht gebündelt, sondern zur Laufzeit vom Server aufgelöst. - -## Ihre App testen - -Das SDK stellt programmgesteuerte APIs bereit, mit denen Sie Ihre App aus Testcode heraus bauen, bereitstellen, installieren und deinstallieren können. In Kombination mit [Vitest](https://vitest.dev/) und den typisierten API-Clients können Sie Integrationstests schreiben, die prüfen, dass Ihre App End-to-End gegen einen echten Twenty-Server funktioniert. - -### Einrichtung - -Die erzeugte App enthält bereits Vitest. Wenn Sie es manuell einrichten, installieren Sie die Abhängigkeiten: - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -Erstellen Sie eine `vitest.config.ts` im Stammverzeichnis Ihrer App: - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -Erstellen Sie eine Setup-Datei, die vor dem Testlauf überprüft, dass der Server erreichbar ist: - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### Programmgesteuerte SDK-APIs - -Der Subpfad `twenty-sdk/cli` exportiert Funktionen, die Sie direkt aus Testcode aufrufen können: - -| Funktion | Beschreibung | -| -------------- | ----------------------------------------------------- | -| `appBuild` | Die App bauen und optional ein Tarball packen | -| `appDeploy` | Ein Tarball auf den Server hochladen | -| `appInstall` | Die App im aktiven Arbeitsbereich installieren | -| `appUninstall` | Die App aus dem aktiven Arbeitsbereich deinstallieren | - -Jede Funktion gibt ein Ergebnisobjekt mit `success: boolean` und entweder `data` oder `error` zurück. - -### Einen Integrationstest schreiben - -Hier ist ein vollständiges Beispiel, das die App baut, bereitstellt und installiert und anschließend prüft, dass sie im Arbeitsbereich erscheint: - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### Tests ausführen - -Stellen Sie sicher, dass Ihr lokaler Twenty-Server läuft, und führen Sie dann Folgendes aus: - -```bash filename="Terminal" -yarn test -``` - -Oder im Watch-Modus während der Entwicklung: - -```bash filename="Terminal" -yarn test:watch -``` - -### Typprüfung - -Sie können die Typprüfung Ihrer App auch ohne Tests ausführen: - -```bash filename="Terminal" -yarn twenty typecheck -``` - -Dies führt `tsc --noEmit` aus und meldet etwaige Typfehler. - -## CLI-Referenz - -Zusätzlich zu `dev`, `build`, `add` und `typecheck` bietet die CLI Befehle zum Ausführen von Funktionen, Anzeigen von Logs und Verwalten von App-Installationen. - -### Funktionen ausführen (`yarn twenty exec`) - -Eine Logikfunktion manuell ausführen, ohne sie über HTTP, Cron oder ein Datenbankereignis auszulösen: - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### Funktionsprotokolle ansehen (`yarn twenty logs`) - -Ausführungsprotokolle für die Logikfunktionen Ihrer App streamen: - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
- name: 'hello-world',
- description: 'A simple front component',
- component: HelloWorld,
-});
-```
-
-```ts src/command-menu-items/hello-world.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
- shortLabel: 'Hello',
- label: 'Hello World',
- icon: 'IconBolt',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-Nach dem Synchronisieren mit `yarn twenty dev` (oder durch einmaliges Ausführen von `yarn twenty dev --once`) erscheint die Schnellaktion oben rechts auf der Seite:
-
-Hello from my app!
-This component renders inside Twenty.
-
-
-
-
-Klicken Sie darauf, um die Komponente inline zu rendern.
-
-## Konfigurationsfelder
-
-| Feld | Erforderlich | Beschreibung |
-| --------------------- | ------------ | --------------------------------------------------------------------------- |
-| `universalIdentifier` | Ja | Stabile eindeutige ID für diese Komponente |
-| `component` | Ja | Eine React-Komponentenfunktion |
-| `name` | Nein | Anzeigename |
-| `description` | Nein | Beschreibung dessen, was die Komponente macht |
-| `isHeadless` | Nein | Auf `true` setzen, wenn die Komponente keine sichtbare UI hat (siehe unten) |
-
-## Eine Front-Komponente auf einer Seite platzieren
-
-Über Befehle hinaus können Sie eine Front-Komponente direkt in eine Datensatzseite einbetten, indem Sie sie als Widget in einem **Seitenlayout** hinzufügen. Details finden Sie im Abschnitt [definePageLayout](/l/de/developers/extend/apps/skills-and-agents#definepagelayout).
-
-## 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 (`isHeadless: true`)** — 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.
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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,
-});
-```
-
-Da die Komponente `null` zurückgibt, überspringt Twenty das Rendern eines Containers dafür — im Layout entsteht kein Leerraum. Die Komponente hat dennoch Zugriff auf alle Hooks und die Host-Kommunikations-API.
-
-## 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:
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
- name: 'record-info',
- component: RecordInfo,
-});
-```
-
-Verfügbare Hooks:
-
-| Hook | Gibt zurück | Beschreibung |
-| --------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
-| `useUserId()` | `string` oder `null` | Die ID des aktuellen Benutzers |
-| `useSelectedRecordIds()` | `Zeichenkette[]` | Alle ausgewählten Datensatz-IDs (leeres Array, wenn keine ausgewählt sind) |
-| `useRecordId()` | `string` oder `null` | **Veraltet.** Verwenden Sie stattdessen `useSelectedRecordIds()` |
-| `useFrontComponentId()` | `string` | Die ID dieser Komponenteninstanz |
-| `useFrontComponentExecutionContext(selector)` | variiert | Zugriff auf den vollständigen Ausführungskontext mit einer Selektorfunktion |
-
-## Host-Kommunikations-API
-
-Front-Komponenten können Navigation, Modals und Benachrichtigungen mittels Funktionen aus `twenty-sdk` auslösen:
-
-| Funktion | Beschreibung |
-| ----------------------------------------------- | ----------------------------------------- |
-| `navigate(to, params?, queryParams?, options?)` | Zu einer Seite in der App navigieren |
-| `openSidePanelPage(params)` | Ein Seitenpanel öffnen |
-| `closeSidePanel()` | Seitenpanel schließen |
-| `openCommandConfirmationModal(params)` | Einen Bestätigungsdialog anzeigen |
-| `enqueueSnackbar(params)` | Eine Toast-Benachrichtigung anzeigen |
-| `unmountFrontComponent()` | Die Komponente entfernen |
-| `updateProgress(progress)` | Einen Fortschrittsindikator aktualisieren |
-
-Hier ist ein Beispiel, das die Host-API verwendet, um nach Abschluss einer Aktion eine Snackbar anzuzeigen und das Seitenpanel zu schließen:
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Mit mehreren Datensätzen arbeiten
-
-Verwenden Sie `useSelectedRecordIds()`, um mehrere ausgewählte Datensätze zu verwalten. Dies ist nützlich für Stapelvorgänge:
-
-```tsx src/front-components/bulk-export.tsx
-import { defineFrontComponent, numberOfSelectedRecords } from 'twenty-sdk/define';
-import { useSelectedRecordIds } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const BulkExport = () => {
- const selectedRecordIds = useSelectedRecordIds();
-
- const handleExport = async () => {
- const client = new CoreApiClient();
-
- for (const recordId of selectedRecordIds) {
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { exported: true } },
- id: true,
- },
- });
- }
-
- await enqueueSnackbar({
- message: `Exported ${selectedRecordIds.length} records`,
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- Archive this record?
- -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
- name: 'bulk-export',
- description: 'Export selected records',
- component: BulkExport,
- command: {
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
- label: 'Bulk Export',
- availabilityType: 'RECORD_SELECTION',
- conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
- },
-});
-```
-
-## defineCommandMenuItem
-
-Verwende `defineCommandMenuItem`, um eine Front-Komponente im Befehlsmenü (Cmd+K) zu registrieren. Wenn `isPinned` `true` ist, erscheint sie außerdem als Schnellaktionsschaltfläche oben rechts auf der Seite.
-
-```ts src/command-menu-items/open-dashboard.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- label: 'Open Dashboard',
- shortLabel: 'Dashboard',
- icon: 'IconLayoutDashboard',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-| Feld | Erforderlich | Beschreibung |
-| --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `universalIdentifier` | Ja | Stabile eindeutige ID für den Befehl |
-| `label` | Ja | Vollständiges Label, das im Befehlsmenü (Cmd+K) angezeigt wird |
-| `frontComponentUniversalIdentifier` | Ja | Der `universalIdentifier` der Front-Komponente, die dieser Befehl öffnet |
-| `shortLabel` | Nein | Kürzeres Label, das auf der angehefteten Schnellaktionsschaltfläche angezeigt wird |
-| `icon` | Nein | Neben dem Label angezeigter Icon-Name (z. B. 'IconBolt', 'IconSend') |
-| `isPinned` | Nein | Bei `true` wird der Befehl als Schnellaktionsschaltfläche oben rechts auf der Seite angezeigt |
-| `availabilityType` | Nein | Steuert, wo der Befehl erscheint: 'GLOBAL' (immer verfügbar), 'RECORD_SELECTION' (nur wenn Datensätze ausgewählt sind) oder 'FALLBACK' (wird angezeigt, wenn keine anderen Befehle passen) |
-| `availabilityObjectUniversalIdentifier` | Nein | Beschränken Sie den Befehl auf Seiten eines bestimmten Objekttyps (z. B. nur bei Company-Datensätzen) |
-| `conditionalAvailabilityExpression` | Nein | Ein boolescher Ausdruck, um dynamisch zu steuern, ob der Befehl sichtbar ist (siehe unten) |
-
-## Bedingte Verfügbarkeitsausdrücke
-
-Mit dem Feld `conditionalAvailabilityExpression` können Sie basierend auf dem aktuellen Seitenkontext steuern, wann ein Befehl sichtbar ist. Importieren Sie typisierte Variablen und Operatoren aus `twenty-sdk`, um Ausdrücke zu erstellen:
-
-```ts src/command-menu-items/bulk-update.command-menu-item.ts
-import {
- defineCommandMenuItem,
- objectPermissions,
- everyEquals,
-} from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: '...',
- label: 'Bulk Update',
- availabilityType: 'RECORD_SELECTION',
- frontComponentUniversalIdentifier: '...',
- conditionalAvailabilityExpression: everyEquals(
- objectPermissions,
- 'canUpdateObjectRecords',
- true,
- ),
-});
-```
-
-**Kontextvariablen** — sie repräsentieren den aktuellen Zustand der Seite:
-
-| Variable | Typ | Beschreibung |
-| ------------------------------ | --------- | --------------------------------------------------------------- |
-| `pageType` | `string` | Aktueller Seitentyp (z. B. 'RecordIndexPage', 'RecordShowPage') |
-| `isInSidePanel` | `boolean` | Ob die Komponente in einem Seitenpanel gerendert wird |
-| `numberOfSelectedRecords` | `number` | Anzahl der aktuell ausgewählten Datensätze |
-| `isSelectAll` | `boolean` | Ob „Alle auswählen“ aktiv ist |
-| `selectedRecords` | `array` | Die ausgewählten Datensatzobjekte |
-| `favoriteRecordIds` | `array` | IDs der favorisierten Datensätze |
-| `objectPermissions` | `object` | Berechtigungen für den aktuellen Objekttyp |
-| `targetObjectReadPermissions` | `object` | Leseberechtigungen für das Zielobjekt |
-| `targetObjectWritePermissions` | `object` | Schreibberechtigungen für das Zielobjekt |
-| `featureFlags` | `object` | Aktive Feature-Flags |
-| `objectMetadataItem` | `object` | Metadaten des aktuellen Objekttyps |
-| `hasAnySoftDeleteFilterOnView` | `boolean` | Ob die aktuelle Ansicht einen Soft-Delete-Filter hat |
-
-**Operatoren** — Variablen zu booleschen Ausdrücken kombinieren:
-
-| Operator | Beschreibung |
-| ----------------------------------- | ------------------------------------------------------------------------------------------- |
-| `isDefined(value)` | `true`, wenn der Wert nicht null/undefined ist |
-| `isNonEmptyString(value)` | `true`, wenn der Wert eine nicht leere Zeichenfolge ist |
-| `includes(array, value)` | `true`, wenn das Array den Wert enthält |
-| `includesEvery(array, prop, value)` | `true`, wenn die Eigenschaft jedes Elements den Wert enthält |
-| `every(array, prop)` | `true`, wenn die Eigenschaft bei jedem Element truthy ist |
-| `everyDefined(array, prop)` | `true`, wenn die Eigenschaft bei jedem Element definiert ist |
-| `everyEquals(array, prop, value)` | `true`, wenn die Eigenschaft bei jedem Element dem Wert entspricht |
-| `some(array, prop)` | `true`, wenn die Eigenschaft bei mindestens einem Element truthy ist |
-| `someDefined(array, prop)` | `true`, wenn die Eigenschaft bei mindestens einem Element definiert ist |
-| `someEquals(array, prop, value)` | `true`, wenn die Eigenschaft bei mindestens einem Element dem Wert entspricht |
-| `someNonEmptyString(array, prop)` | `true`, wenn die Eigenschaft bei mindestens einem Element eine nicht leere Zeichenfolge ist |
-| `none(array, prop)` | `true`, wenn die Eigenschaft bei jedem Element falsy ist |
-| `noneDefined(array, prop)` | `true`, wenn die Eigenschaft bei jedem Element undefined ist |
-| `noneEquals(array, prop, value)` | `true`, wenn die Eigenschaft bei keinem Element dem Wert entspricht |
-
-## Öffentliche Assets
-
-Front-Komponenten können mit `getPublicAssetUrl` auf Dateien aus dem `public/`-Verzeichnis der App zugreifen:
-
-```tsx
-import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
-
-const Logo = () => Export {selectedRecordIds.length} selected record(s)?
- -;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-Details finden Sie im Abschnitt [Öffentliche Assets](/l/de/developers/extend/apps/cli-and-testing#public-assets-public-folder).
-
-## Styling
-
-Front-Komponenten unterstützen mehrere Styling-Ansätze. Sie können verwenden:
-
-* **Inline-Styles** — `style={{ color: 'red' }}`
-* **Twenty-UI-Komponenten** — Import aus `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar und mehr)
-* **Emotion** — CSS-in-JS mit `@emotion/react`
-* **Styled-components** — `styled.div`-Muster
-* **Tailwind CSS** — Utility-Klassen
-* **Beliebige CSS-in-JS-Bibliothek**, die mit React kompatibel ist
-
-```tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/de/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/de/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index dd2b70bb9a..0000000000
--- a/packages/twenty-docs/l/de/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,273 +0,0 @@
----
-title: Erste Schritte
-icon: rocket
-description: Erstellen Sie in wenigen Minuten Ihre erste Twenty-App.
----
-
-## Voraussetzungen
-
-* **Node.js 24+** — [Hier herunterladen](https://nodejs.org/)
-* **Yarn 4** — Wird mit Node.js über Corepack mitgeliefert. Aktivieren Sie es: `corepack enable`
-* **Docker** — [Hier herunterladen](https://www.docker.com/products/docker-desktop/). Erforderlich, um einen lokalen Twenty-Server auszuführen. Überspringen Sie dies, wenn Twenty bereits anderswo läuft.
-
-Das Erstellen einer Twenty-App umfasst drei Phasen. Das Scaffolding-Tool fasst sie zu einem einzigen Happy-Path-Befehl zusammen, aber jede Phase ist ein eigenes Konzept — wenn etwas fehlschlägt, hilft Ihnen das Wissen, in welcher Phase Sie sich befinden, zu erkennen, was zu beheben ist.
-
-| Phase | Was Sie tun | Tool | Ergebnis |
-| ----------------------- | ------------------------------------------------------- | ----------------------------- | ---------------------------------------------------- |
-| **1. Gerüst erstellen** | Den Quellcode der App erzeugen | `npx create-twenty-app` | Ein TypeScript-Projekt auf der Festplatte |
-| **2. Server starten** | Einen Twenty-Server starten, in den synchronisiert wird | Docker + `yarn twenty server` | Eine laufende Twenty-Instanz |
-| **3. Synchronisieren** | Ihren Code live mit dem Server synchronisieren | `yarn twenty dev` | Ihre Änderungen erscheinen in der Benutzeroberfläche |
-
----
-
-## Phase 1 — Projektgerüst erstellen
-
-Erstellen Sie eine neue App aus der Vorlage:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-Sie werden nach einem Namen und einer Beschreibung gefragt — drücken Sie **Enter** für die Standardwerte. Dadurch wird ein TypeScript-Projekt in `my-twenty-app/` erzeugt, mit einer Startdatei `application-config.ts`, einer Standardrolle, einem CI-Workflow und einem Integrationstest.
-
-**Nach dieser Phase:** Sie haben den Quellcode einer App auf Ihrem Rechner. Es läuft noch nicht — das ist Phase 2.
-
----
-
-## Phase 2 — Einen lokalen Twenty-Server starten
-
-Ihre App benötigt einen Twenty-Server, in den sie synchronisieren kann. Der Server ist eine vollständige Twenty-Instanz — UI, GraphQL-API, PostgreSQL — die lokal in Docker läuft. Ihr lokaler Code lädt seine Definitionen auf diesen Server hoch, wodurch sie in der Benutzeroberfläche erscheinen.
-
-Das Scaffolding-Tool bietet an, einen für Sie zu starten:
-
-> **Möchten Sie eine lokale Twenty-Instanz einrichten?**
-
-* **Ja (empfohlen)** — lädt das Docker-Image `twentycrm/twenty-app-dev` herunter und startet es auf Port `2020`. Stellen Sie sicher, dass Docker läuft.
-* **Nein** — wählen Sie dies, wenn Sie bereits einen Twenty-Server haben, mit dem Sie sich verbinden möchten. Sie können die Verbindung später mit `yarn twenty remote add` herstellen.
-
-
-
-
-
-Sobald der Server läuft, öffnet sich ein Browser zur Anmeldung. Verwenden Sie das vorab eingerichtete Demo-Konto:
-
-* **E-Mail:** `tim@apple.dev`
-* **Passwort:** `tim@apple.dev`
-
-
-
-
-
-
-Klicken Sie auf dem nächsten Bildschirm auf **Authorize** — dadurch erhält die CLI Zugriff auf Ihren Arbeitsbereich.
-
-
-
-
-
-
-Ihr Terminal bestätigt, dass alles eingerichtet ist.
-
-
-
-
-
-
-**Nach dieser Phase:** Sie haben einen laufenden Twenty-Server unter [http://localhost:2020](http://localhost:2020), und Ihre CLI ist autorisiert, mit ihm zu synchronisieren.
-
-
-
- 
-
-
-Öffnen Sie [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Unter **Your Apps** sollte Ihre App angezeigt werden.
-
-
-
-
-
-
-Klicken Sie auf **My twenty app**, um die **Anwendungsregistrierung** anzuzeigen — ein serverseitiger Datensatz, der Ihre App beschreibt (Name, Bezeichner, OAuth-Anmeldedaten, Quelle). Eine Registrierung kann in mehreren Arbeitsbereichen auf demselben Server installiert werden.
-
-
-
-
-
-
-Klicken Sie auf **View installed app**, um die Installation im Arbeitsbereich anzuzeigen. Die Registerkarte **About** zeigt die Version und Verwaltungsoptionen.
-
-
-
-
-
-
-**Nach dieser Phase:** Sie haben eine Live-Entwicklungsschleife. Bearbeiten Sie eine beliebige Datei in `src/`, und sie erscheint in der Benutzeroberfläche.
-
-### Einmalige Synchronisierung für CI und Skripte
-
-Verwenden Sie `--once`, um einen einzelnen Build + Sync auszuführen und zu beenden — gleiche Pipeline, kein Watcher:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Befehl | Verhalten | Wann verwenden |
-| ------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `yarn twenty dev` | Überwacht und synchronisiert bei jeder Änderung erneut. Läuft, bis Sie es stoppen. | Interaktive lokale Entwicklung. |
-| `yarn twenty dev --once` | Einmaliger Build + Sync, beendet sich mit `0` bei Erfolg, mit `1` bei Fehler. | CI, Pre-Commit-Hooks, KI-Agenten, skriptgesteuerte Workflows. |
-
-Beide Modi benötigen einen Server im Entwicklungsmodus und eine authentifizierte Remote-Verbindung.
-
-
-Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### Come funziona il bundling - -La fase di build usa esbuild per produrre un singolo file autonomo per ogni funzione logica e per ogni componente front-end. Tutti i pacchetti importati sono incorporati nel bundle. - -**Le funzioni logiche** vengono eseguite in un ambiente Node.js. I moduli integrati di Node (`fs`, `path`, `crypto`, `http`, ecc.) sono disponibili e non necessitano di essere installati. - -**I componenti front-end** vengono eseguiti in un Web Worker. I moduli integrati di Node non sono disponibili — solo le API del browser e i pacchetti npm che funzionano in un ambiente browser. - -Entrambi gli ambienti hanno `twenty-client-sdk/core` e `twenty-client-sdk/metadata` disponibili come moduli preforniti — questi non vengono inclusi nel bundle ma vengono risolti a runtime dal server. - -## Testare la tua app - -L'SDK fornisce API programmatiche che ti consentono di compilare, distribuire, installare e disinstallare la tua app dal codice di test. In combinazione con [Vitest](https://vitest.dev/) e i client API tipizzati, puoi scrivere test di integrazione che verificano che la tua app funzioni end-to-end contro un server Twenty reale. - -### Impostazione - -L'app generata tramite scaffolding include già Vitest. Se la configuri manualmente, installa le dipendenze: - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -Crea un `vitest.config.ts` alla radice della tua app: - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -Crea un file di setup che verifichi che il server sia raggiungibile prima dell'esecuzione dei test: - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### API programmatiche dell'SDK - -Il sottopercorso `twenty-sdk/cli` esporta funzioni che puoi chiamare direttamente dal codice di test: - -| Funzione | Descrizione | -| -------------- | ----------------------------------------------- | -| `appBuild` | Compila l'app e, opzionalmente, crea un tarball | -| `appDeploy` | Carica un tarball sul server | -| `appInstall` | Installa l'app nello spazio di lavoro attivo | -| `appUninstall` | Disinstalla l'app dallo spazio di lavoro attivo | - -Ogni funzione restituisce un oggetto risultato con `success: boolean` e `data` oppure `error`. - -### Scrivere un test di integrazione - -Ecco un esempio completo che compila, distribuisce e installa l'app, quindi verifica che compaia nello spazio di lavoro: - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### Esecuzione dei test - -Assicurati che il tuo server Twenty locale sia in esecuzione, quindi: - -```bash filename="Terminal" -yarn test -``` - -Oppure in modalità watch durante lo sviluppo: - -```bash filename="Terminal" -yarn test:watch -``` - -### Controllo dei tipi - -Puoi anche eseguire il controllo dei tipi sulla tua app senza eseguire i test: - -```bash filename="Terminal" -yarn twenty typecheck -``` - -Questo esegue `tsc --noEmit` e riporta eventuali errori di tipo. - -## Riferimento CLI - -Oltre a `dev`, `build`, `add` e `typecheck`, la CLI fornisce comandi per eseguire funzioni, visualizzare i log e gestire le installazioni delle app. - -### Esecuzione delle funzioni (`yarn twenty exec`) - -Esegui manualmente una funzione logica senza attivarla tramite HTTP, cron o evento del database: - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### Visualizzazione dei log delle funzioni (`yarn twenty logs`) - -Esegui lo streaming dei log di esecuzione per le funzioni logiche della tua app: - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- 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',
- },
-});
-```
-
-Dopo la sincronizzazione con `yarn twenty dev` (o eseguendo una volta sola `yarn twenty dev --once`), l'azione rapida appare nell'angolo in alto a destra della pagina:
-
-Hello from my app!
-This component renders inside Twenty.
-
-
-
-
-Fai clic per renderizzare il componente in linea.
-
-## Campi di configurazione
-
-| Campo | Obbligatorio | Descrizione |
-| --------------------- | ------------ | ---------------------------------------------------------------------------------------- |
-| `universalIdentifier` | Sì | ID univoco stabile per questo componente |
-| `component` | Sì | Una funzione di componente React |
-| `name` | No | Nome visualizzato |
-| `description` | No | Descrizione di ciò che fa il componente |
-| `isHeadless` | No | Imposta su `true` se il componente non ha una UI visibile (vedi sotto) |
-| `command` | No | Registra il componente come comando (vedi [opzioni del comando](#command-options) sotto) |
-
-## Posizionare un componente front-end su una pagina
-
-Oltre ai comandi, puoi incorporare un componente front-end direttamente in una pagina di record aggiungendolo come widget in un **layout di pagina**. Vedi la sezione [definePageLayout](/l/it/developers/extend/apps/skills-and-agents#definepagelayout) per i dettagli.
-
-## 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 (`isHeadless: true`)** — 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.
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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,
-});
-```
-
-Poiché il componente restituisce `null`, Twenty evita di renderizzare un contenitore per esso — non appare alcuno spazio vuoto nel layout. Il componente ha comunque accesso a tutti gli hook e all'API di comunicazione con l'host.
-
-## 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:
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
- name: 'record-info',
- component: RecordInfo,
-});
-```
-
-Hook disponibili:
-
-| Hook | Restituisce | Descrizione |
-| --------------------------------------------- | ----------------- | --------------------------------------------------------------------- |
-| `useUserId()` | `string` o `null` | L'ID dell'utente corrente |
-| `useRecordId()` | `string` o `null` | L'ID del record corrente (quando posizionato su una pagina di record) |
-| `useFrontComponentId()` | `string` | L'ID di questa istanza di componente |
-| `useFrontComponentExecutionContext(selector)` | varia | Accedi all'intero contesto di esecuzione con una funzione selettore |
-
-## API di comunicazione con l'host
-
-I componenti front-end possono attivare navigazione, modali e notifiche utilizzando funzioni da `twenty-sdk`:
-
-| Funzione | Descrizione |
-| ----------------------------------------------- | ------------------------------------- |
-| `navigate(to, params?, queryParams?, options?)` | Naviga a una pagina dell'app |
-| `openSidePanelPage(params)` | Apri un pannello laterale |
-| `closeSidePanel()` | Chiudi il pannello laterale |
-| `openCommandConfirmationModal(params)` | Mostra una finestra di conferma |
-| `enqueueSnackbar(params)` | Mostra una notifica toast |
-| `unmountFrontComponent()` | Smonta il componente |
-| `updateProgress(progress)` | Aggiorna un indicatore di avanzamento |
-
-Ecco un esempio che usa l'API host per mostrare una snackbar e chiudere il pannello laterale dopo il completamento di un'azione:
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-## Opzioni del comando
-
-Aggiungere un campo `command` a `defineFrontComponent` registra il componente nel menu comandi (Cmd+K). Se `isPinned` è `true`, compare anche come pulsante di azione rapida nell'angolo in alto a destra della pagina.
-
-| Campo | Obbligatorio | Descrizione |
-| --------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | Sì | ID univoco stabile per il comando |
-| `label` | Sì | Etichetta completa mostrata nel menu comandi (Cmd+K) |
-| `shortLabel` | No | Etichetta breve visualizzata sul pulsante di azione rapida fissato |
-| `icon` | No | Nome dell'icona visualizzato accanto all'etichetta (ad es. `'IconBolt'`, `'IconSend'`) |
-| `isPinned` | No | Quando `true`, mostra il comando come pulsante di azione rapida nell'angolo in alto a destra della pagina |
-| `availabilityType` | No | Controlla dove compare il comando: `'GLOBAL'` (sempre disponibile), `'RECORD_SELECTION'` (solo quando sono selezionati dei record) o `'FALLBACK'` (mostrato quando nessun altro comando corrisponde) |
-| `availabilityObjectUniversalIdentifier` | No | Limita il comando alle pagine di uno specifico tipo di oggetto (ad es. solo sui record Company) |
-| `conditionalAvailabilityExpression` | No | Un'espressione booleana per controllare dinamicamente se il comando è visibile (vedi sotto) |
-
-## Espressioni di disponibilità condizionale
-
-Il campo `conditionalAvailabilityExpression` consente di controllare quando un comando è visibile in base al contesto della pagina corrente. Importa variabili tipizzate e operatori da `twenty-sdk` per costruire espressioni:
-
-```tsx
-import {
- defineFrontComponent,
- pageType,
- numberOfSelectedRecords,
- objectPermissions,
- everyEquals,
- isDefined,
-} from 'twenty-sdk/define';
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'bulk-action',
- component: BulkAction,
- command: {
- universalIdentifier: '...',
- label: 'Bulk Update',
- availabilityType: 'RECORD_SELECTION',
- conditionalAvailabilityExpression: everyEquals(
- objectPermissions,
- 'canUpdateObjectRecords',
- true,
- ),
- },
-});
-```
-
-**Variabili di contesto** — rappresentano lo stato corrente della pagina:
-
-| Variabile | Tipo | Descrizione |
-| ------------------------------ | --------- | ------------------------------------------------------------------------ |
-| `pageType` | `string` | Tipo di pagina corrente (ad es. `'RecordIndexPage'`, `'RecordShowPage'`) |
-| `isInSidePanel` | `boolean` | Indica se il componente è renderizzato in un pannello laterale |
-| `numberOfSelectedRecords` | `number` | Numero di record attualmente selezionati |
-| `isSelectAll` | `boolean` | Indica se "seleziona tutto" è attivo |
-| `selectedRecords` | `array` | Gli oggetti dei record selezionati |
-| `favoriteRecordIds` | `array` | ID dei record aggiunti ai preferiti |
-| `objectPermissions` | `object` | Autorizzazioni per il tipo di oggetto corrente |
-| `targetObjectReadPermissions` | `object` | Autorizzazioni di lettura per l'oggetto di destinazione |
-| `targetObjectWritePermissions` | `object` | Autorizzazioni di scrittura per l'oggetto di destinazione |
-| `featureFlags` | `object` | Flag delle funzionalità attivi |
-| `objectMetadataItem` | `object` | Metadati del tipo di oggetto corrente |
-| `hasAnySoftDeleteFilterOnView` | `boolean` | Indica se la vista corrente ha un filtro di soft-delete |
-
-**Operatori** — combinano variabili in espressioni booleane:
-
-| Operatore | Descrizione |
-| ----------------------------------- | -------------------------------------------------------------------- |
-| `isDefined(value)` | `true` se il valore non è null/undefined |
-| `isNonEmptyString(value)` | `true` se il valore è una stringa non vuota |
-| `includes(array, value)` | `true` se l'array contiene il valore |
-| `includesEvery(array, prop, value)` | `true` se la proprietà di ogni elemento include il valore |
-| `every(array, prop)` | `true` se la proprietà è truthy su ogni elemento |
-| `everyDefined(array, prop)` | `true` se la proprietà è definita su ogni elemento |
-| `everyEquals(array, prop, value)` | `true` se la proprietà è uguale al valore su ogni elemento |
-| `some(array, prop)` | `true` se la proprietà è truthy su almeno un elemento |
-| `someDefined(array, prop)` | `true` se la proprietà è definita su almeno un elemento |
-| `someEquals(array, prop, value)` | `true` se la proprietà è uguale al valore su almeno un elemento |
-| `someNonEmptyString(array, prop)` | `true` se la proprietà è una stringa non vuota su almeno un elemento |
-| `none(array, prop)` | `true` se la proprietà è falsy su ogni elemento |
-| `noneDefined(array, prop)` | `true` se la proprietà è undefined su ogni elemento |
-| `noneEquals(array, prop, value)` | `true` se la proprietà non è uguale al valore su alcun elemento |
-
-## Asset pubblici
-
-I componenti front-end possono accedere ai file dalla directory `public/` dell'app utilizzando `getPublicAssetUrl`:
-
-```tsx
-import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
-
-const Logo = () => Archive this record?
- -;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-Vedi la [sezione sugli asset pubblici](/l/it/developers/extend/apps/cli-and-testing#public-assets-public-folder) per i dettagli.
-
-## Stile
-
-I componenti front-end supportano diversi approcci di styling. Puoi usare:
-
-* **Stili inline** — `style={{ color: 'red' }}`
-* **Componenti Twenty UI** — importali da `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar e altro)
-* **Emotion** — CSS-in-JS con `@emotion/react`
-* **Styled-components** — pattern `styled.div`
-* **Tailwind CSS** — classi di utilità
-* **Qualsiasi libreria CSS-in-JS** compatibile con React
-
-```tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/it/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/it/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index 6a18d413cf..0000000000
--- a/packages/twenty-docs/l/it/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,282 +0,0 @@
----
-title: Per iniziare
-icon: rocket
-description: Crea la tua prima app Twenty in pochi minuti.
----
-
-## Cosa sono le app?
-
-Le app ti consentono di estendere Twenty con oggetti, campi, funzioni logiche, componenti front-end, competenze IA e altro ancora — il tutto gestito come codice. Invece di configurare tutto tramite l'interfaccia utente, definisci in TypeScript il modello dati e la logica e li distribuisci in uno o più spazi di lavoro.
-
-## Prerequisiti
-
-Prima di iniziare, assicurati che quanto segue sia installato sul tuo computer:
-
-* **Node.js 24+** — [Scarica qui](https://nodejs.org/)
-* **Yarn 4** — Incluso con Node.js tramite Corepack. Abilitalo eseguendo `corepack enable`
-* **Docker** — [Scarica qui](https://www.docker.com/products/docker-desktop/). Necessario per eseguire un'istanza locale di Twenty. Non necessario se hai già un server Twenty in esecuzione.
-
-## Crea la tua prima app
-
-### Crea lo scheletro della tua app
-
-Apri un terminale ed esegui:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-Ti verrà chiesto di inserire un nome e una descrizione per la tua app. Premi **Invio** per accettare i valori predefiniti.
-
-Questo crea una nuova cartella chiamata `my-twenty-app` con tutto il necessario.
-
-### Configura un'istanza locale di Twenty
-
-Lo strumento di scaffolding chiederà:
-
-> **Vuoi configurare un'istanza locale di Twenty?**
-
-* **Digita `yes`** (consigliato) — Questo scarica l'immagine Docker `twenty-app-dev` e avvia un server Twenty locale sulla porta `2020`. Assicurati che Docker sia in esecuzione prima di continuare.
-* **Digita `no`** — Sceglilo se hai già un server Twenty in esecuzione in locale.
-
-
-
-
-
-### Accedi al tuo spazio di lavoro
-
-Successivamente si aprirà una finestra del browser con la pagina di accesso di Twenty. Accedi con l'account demo preconfigurato:
-
-* **Email:** `tim@apple.dev`
-* **Password:** `tim@apple.dev`
-
-
-
-
-
-
-### Autorizza l'app
-
-Dopo l'accesso, vedrai una schermata di autorizzazione. Questo consente alla tua app di interagire con il tuo spazio di lavoro.
-
-Fai clic su **Authorize** per continuare.
-
-
-
-
-
-
-Una volta autorizzato, il terminale confermerà che tutto è configurato.
-
-
-
-
-
-
-### Inizia a sviluppare
-
-Entra nella nuova cartella della tua app e avvia il server di sviluppo:
-
-```bash filename="Terminal"
-cd my-twenty-app
-yarn twenty dev
-```
-
-Questo controlla i file sorgente, ricompila a ogni modifica e sincronizza automaticamente la tua app con il server Twenty locale. Dovresti vedere un pannello di stato in tempo reale nel terminale.
-
-Per un output più dettagliato (log di build, richieste di sincronizzazione, tracce di errore), usa il flag `--verbose`:
-
-```bash filename="Terminal"
-yarn twenty dev --verbose
-```
-
-
-
-
-
-
-#### Sincronizzazione una tantum con `yarn twenty dev --once`
-
-Se non vuoi un watcher in esecuzione in background (ad esempio in una pipeline CI, un hook di Git o un flusso di lavoro scriptato), passa il flag `--once`. Esegue la stessa pipeline di `yarn twenty dev` — genera il manifest, effettua il bundling dei file, carica, sincronizza, rigenera il client API tipizzato — ma **termina non appena la sincronizzazione è completata**:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Comando | Comportamento | Quando usarlo |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `yarn twenty dev` | Monitora i file sorgente e risincronizza a ogni modifica. Rimane in esecuzione finché non lo interrompi. | Sviluppo locale interattivo — vuoi il pannello di stato in tempo reale e un ciclo di feedback immediato. |
-| `yarn twenty dev --once` | Esegue una singola build + sincronizzazione, quindi termina con codice `0` in caso di successo o `1` in caso di errore. | Script, CI, hook pre-commit, agenti IA e qualsiasi flusso di lavoro non interattivo. |
-
-Entrambe le modalità richiedono un server Twenty in esecuzione in modalità di sviluppo e un remote autenticato — si applicano gli stessi prerequisiti.
-
-### Visualizza la tua app in Twenty
-
-Apri [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) nel browser. Vai su **Settings > Apps** e seleziona la scheda **Developer**. Dovresti vedere la tua app elencata in **Your Apps**:
-
-
-
-
-
-
-Fai clic su **My twenty app** per aprire la sua **registrazione dell'applicazione**. Una registrazione è un record a livello di server che descrive la tua app — il suo nome, identificatore univoco, credenziali OAuth e origine (locale, npm o tarball). Risiede sul server, non all'interno di uno spazio di lavoro specifico. Quando installi un'app in uno spazio di lavoro, Twenty crea un'**applicazione** con ambito dello spazio di lavoro che rimanda a questa registrazione. Una registrazione può essere installata in più spazi di lavoro sullo stesso server.
-
-
-
-
-
-
-Fai clic su **View installed app** per vedere l'app installata. La scheda **About** mostra la versione corrente e le opzioni di gestione:
-
-
-
-
-
-
-Passa alla scheda **Content** per vedere tutto ciò che la tua app fornisce — oggetti, campi, funzioni logiche e agenti:
-
-
-
-
-
-
-È tutto pronto! Modifica qualsiasi file in `src/` e le modifiche verranno rilevate automaticamente.
-
----
-
-## Cosa puoi creare
-
-Le app sono composte da **entità** — ciascuna definita come un file TypeScript con un singolo `export default`:
-
-| Entità | Cosa fa |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| **Oggetti e campi** | Definisci modelli di dati personalizzati (come Post Card, Invoice) con campi tipizzati |
-| **Funzioni logiche** | Funzioni TypeScript lato server attivate da route HTTP, pianificazioni cron o eventi del database |
-| **Componenti front-end** | Componenti React che vengono renderizzati all'interno dell'UI di Twenty (pannello laterale, widget, menu comandi) |
-| **Skill e agenti** | Funzionalità di IA — istruzioni riutilizzabili e assistenti autonomi |
-| **Viste e navigazione** | Viste elenco preconfigurate e voci di menu della barra laterale per i tuoi oggetti |
-| **Layout di pagina** | Pagine di dettaglio dei record personalizzate con schede e widget |
-
-Vai a [Creare app](/l/it/developers/extend/apps/building) per una guida dettagliata su ogni tipo di entità.
-
----
-
-## Struttura del progetto
-
-Lo scaffolder genera la seguente struttura dei file:
-
-```text filename="my-twenty-app/"
-my-twenty-app/
- package.json
- yarn.lock
- .gitignore
- .nvmrc
- .yarnrc.yml
- .oxlintrc.json
- tsconfig.json
- tsconfig.spec.json # TypeScript config for tests
- vitest.config.ts # Vitest test runner configuration
- LLMS.md
- README.md
- .github/
- └── workflows/
- └── ci.yml # GitHub Actions CI workflow
- public/ # Public assets (images, fonts, etc.)
- src/
- ├── application-config.ts # Required — main application configuration
- ├── default-role.ts # Default role for logic functions
- ├── constants/
- │ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
- └── __tests__/
- ├── setup-test.ts # Test setup (server health check, config)
- └── app-install.integration-test.ts # Integration test
-```
-
-### Partire da un esempio
-
-Per iniziare da un esempio più completo con oggetti personalizzati, campi, funzioni logiche, componenti front-end e altro, usa il flag `--example`:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app --example postcard
-```
-
-Gli esempi provengono dalla directory [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) su GitHub. Puoi anche aggiungere singole entità a un progetto esistente con `yarn twenty add` (vedi [Creare app](/l/it/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
-
-### File principali
-
-| File / Cartella | Scopo |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `package.json` | Dichiara il nome, la versione e le dipendenze della tua app. Include uno script `twenty` così puoi eseguire `yarn twenty help` per vedere tutti i comandi. |
-| `src/application-config.ts` | **Obbligatorio.** Il file di configurazione principale della tua app. |
-| `src/default-role.ts` | Ruolo predefinito che controlla a cosa possono accedere le tue funzioni logiche. |
-| `src/constants/universal-identifiers.ts` | UUID generati automaticamente e metadati dell'app (nome visualizzato, descrizione). |
-| `src/__tests__/` | Test di integrazione (setup + test di esempio). |
-| `public/` | Asset statici (immagini, font) serviti insieme alla tua app. |
-
-## Server di sviluppo locale
-
-Lo scaffolder ha già avviato per te un server Twenty locale. Per gestirlo in seguito, usa `yarn twenty server`:
-
-| Comando | Descrizione |
-| -------------------------------------- | --------------------------------------------------------- |
-| `yarn twenty server start` | Avvia il server locale (scarica l'immagine se necessario) |
-| `yarn twenty server start --port 3030` | Avvia su una porta personalizzata |
-| `yarn twenty server start --test` | Avvia un'istanza di test separata sulla porta 2021 |
-| `yarn twenty server stop` | Arresta il server (conserva i dati) |
-| `yarn twenty server status` | Mostra stato del server, URL e credenziali |
-| `yarn twenty server logs` | Trasmetti in streaming i log del server |
-| `yarn twenty server logs --lines 100` | Mostra le ultime 100 righe di log |
-| `yarn twenty server reset` | Elimina tutti i dati e riparti da zero |
-
-I dati vengono mantenuti tra i riavvii in due volumi Docker (`twenty-app-dev-data` per PostgreSQL, `twenty-app-dev-storage` per i file). Usa `reset` per cancellare tutto e ripartire da zero.
-
-### Esecuzione di un'istanza di test
-
-Passa `--test` a qualsiasi comando `server` per gestire una seconda istanza completamente isolata — utile per eseguire test di integrazione o per sperimentare senza toccare i tuoi dati di sviluppo principali.
-
-| Comando | Descrizione |
-| ---------------------------------- | ------------------------------------------------------------------------ |
-| `yarn twenty server start --test` | Avvia l'istanza di test (per impostazione predefinita usa la porta 2021) |
-| `yarn twenty server stop --test` | Arresta l'istanza di test |
-| `yarn twenty server status --test` | Mostra stato, URL e credenziali dell'istanza di test |
-| `yarn twenty server logs --test` | Trasmetti in streaming i log dell'istanza di test |
-| `yarn twenty server reset --test` | Cancella i dati di test e riparti da zero |
-
-L'istanza di test viene eseguita nel proprio container Docker (`twenty-app-dev-test`) con volumi dedicati (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) e configurazione dedicata, così può essere eseguita in parallelo con la tua istanza principale senza conflitti. Combina `--test` con `--port` per sovrascrivere il valore predefinito 2021.
-
-
-Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### Como o empacotamento funciona - -A etapa de build usa o esbuild para produzir um único arquivo independente por função lógica e por componente de front-end. Todos os pacotes importados são incorporados ao bundle. - -**Funções lógicas** são executadas em um ambiente Node.js. Módulos nativos do Node (`fs`, `path`, `crypto`, `http`, etc.) estão disponíveis e não precisam ser instalados. - -**Componentes de front-end** são executados em um Web Worker. Módulos nativos do Node **não** estão disponíveis — apenas APIs do navegador e pacotes npm que funcionam em um ambiente de navegador. - -Ambos os ambientes têm `twenty-client-sdk/core` e `twenty-client-sdk/metadata` disponíveis como módulos pré-fornecidos — eles não são empacotados, mas resolvidos em tempo de execução pelo servidor. - -## Testando seu aplicativo - -O SDK fornece APIs programáticas que permitem compilar, implantar, instalar e desinstalar seu aplicativo a partir de código de teste. Em conjunto com [Vitest](https://vitest.dev/) e os clientes de API tipados, você pode escrever testes de integração que verificam que seu aplicativo funciona de ponta a ponta em um servidor Twenty real. - -### Configuração - -O aplicativo gerado pelo scaffolder já inclui o Vitest. Se você configurá-lo manualmente, instale as dependências: - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -Crie um `vitest.config.ts` na raiz do seu aplicativo: - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -Crie um arquivo de configuração que verifique se o servidor está acessível antes da execução dos testes: - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### APIs programáticas do SDK - -O subcaminho `twenty-sdk/cli` exporta funções que você pode chamar diretamente a partir do código de teste: - -| Função | Descrição | -| -------------- | ------------------------------------------------------------ | -| `appBuild` | Compilar o aplicativo e, opcionalmente, empacotar um tarball | -| `appDeploy` | Enviar um tarball para o servidor | -| `appInstall` | Instalar o aplicativo no espaço de trabalho ativo | -| `appUninstall` | Desinstalar o aplicativo do espaço de trabalho ativo | - -Cada função retorna um objeto de resultado com `success: boolean` e `data` ou `error`. - -### Escrevendo um teste de integração - -Aqui está um exemplo completo que compila, implanta e instala o aplicativo e, em seguida, verifica se ele aparece no espaço de trabalho: - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### Executando testes - -Certifique-se de que seu servidor Twenty local esteja em execução e, em seguida: - -```bash filename="Terminal" -yarn test -``` - -Ou no modo watch durante o desenvolvimento: - -```bash filename="Terminal" -yarn test:watch -``` - -### Verificação de tipos - -Você também pode executar a verificação de tipos no seu aplicativo sem executar os testes: - -```bash filename="Terminal" -yarn twenty typecheck -``` - -Isso executa `tsc --noEmit` e informa quaisquer erros de tipo. - -## Referência da CLI - -Além de `dev`, `build`, `add` e `typecheck`, a CLI fornece comandos para executar funções, visualizar logs e gerenciar instalações de aplicativos. - -### Executando funções (`yarn twenty exec`) - -Execute manualmente uma função de lógica sem acioná-la via HTTP, cron ou evento de banco de dados: - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### Visualizando logs de funções (`yarn twenty logs`) - -Transmita os logs de execução das funções de lógica do seu aplicativo: - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
- name: 'hello-world',
- description: 'A simple front component',
- component: HelloWorld,
-});
-```
-
-```ts src/command-menu-items/hello-world.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
- shortLabel: 'Hello',
- label: 'Hello World',
- icon: 'IconBolt',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-Após sincronizar com `yarn twenty dev` (ou executando uma única vez o `yarn twenty dev --once`), a ação rápida aparece no canto superior direito da página:
-
-Hello from my app!
-This component renders inside Twenty.
-
-
-
-
-Clique nele para renderizar o componente inline.
-
-## Campos de configuração
-
-| Campo | Obrigatório | Descrição |
-| --------------------- | ----------- | ---------------------------------------------------------------------------- |
-| `universalIdentifier` | Sim | ID único e estável para este componente |
-| `component` | Sim | Uma função de componente React |
-| `name` | Não | Nome de Exibição |
-| `description` | Não | Descrição do que o componente faz |
-| `isHeadless` | Não | Defina como `true` se o componente não tiver interface visível (veja abaixo) |
-
-## Colocando um componente de front-end em uma página
-
-Além de comandos, você pode incorporar um componente de front-end diretamente em uma página de registro adicionando-o como um widget em um **layout de página**. Veja a seção [definePageLayout](/l/pt/developers/extend/apps/skills-and-agents#definepagelayout) para obter detalhes.
-
-## 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 (`isHeadless: true`)** — 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.
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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,
-});
-```
-
-Como o componente retorna `null`, o Twenty ignora renderizar um contêiner para ele — nenhum espaço vazio aparece no layout. O componente ainda tem acesso a todos os hooks e à API de comunicação do host.
-
-## 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:
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
- name: 'record-info',
- component: RecordInfo,
-});
-```
-
-Hooks disponíveis:
-
-| Hook | Retorna | Descrição |
-| --------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
-| `useUserId()` | `string` ou `null` | O ID do usuário atual |
-| `useSelectedRecordIds()` | `string[]` | Todos os IDs dos registros selecionados (array vazio se nenhum estiver selecionado) |
-| `useRecordId()` | `string` ou `null` | **Obsoleto.** Use `useSelectedRecordIds()` em vez disso |
-| `useFrontComponentId()` | `string` | O ID desta instância do componente |
-| `useFrontComponentExecutionContext(selector)` | varia | Acesse o contexto de execução completo com uma função seletora |
-
-## API de comunicação do host
-
-Componentes de front-end podem acionar navegação, modais e notificações usando funções de `twenty-sdk`:
-
-| Função | Descrição |
-| ----------------------------------------------- | ------------------------------------- |
-| `navigate(to, params?, queryParams?, options?)` | Navegar para uma página no app |
-| `openSidePanelPage(params)` | Abrir um painel lateral |
-| `closeSidePanel()` | Fechar o painel lateral |
-| `openCommandConfirmationModal(params)` | Mostrar um diálogo de confirmação |
-| `enqueueSnackbar(params)` | Mostrar uma notificação do tipo toast |
-| `unmountFrontComponent()` | Desmontar o componente |
-| `updateProgress(progress)` | Atualizar um indicador de progresso |
-
-Aqui está um exemplo que usa a API do host para exibir um snackbar e fechar o painel lateral após a conclusão de uma ação:
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Trabalhando com vários registros
-
-Use `useSelectedRecordIds()` para lidar com vários registros selecionados. Isso é útil para operações em lote:
-
-```tsx src/front-components/bulk-export.tsx
-import { defineFrontComponent, numberOfSelectedRecords } from 'twenty-sdk/define';
-import { useSelectedRecordIds } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const BulkExport = () => {
- const selectedRecordIds = useSelectedRecordIds();
-
- const handleExport = async () => {
- const client = new CoreApiClient();
-
- for (const recordId of selectedRecordIds) {
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { exported: true } },
- id: true,
- },
- });
- }
-
- await enqueueSnackbar({
- message: `Exported ${selectedRecordIds.length} records`,
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- Archive this record?
- -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
- name: 'bulk-export',
- description: 'Export selected records',
- component: BulkExport,
- command: {
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
- label: 'Bulk Export',
- availabilityType: 'RECORD_SELECTION',
- conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
- },
-});
-```
-
-## defineCommandMenuItem
-
-Use `defineCommandMenuItem` para registrar um componente de front-end no menu de comando (Cmd+K). Se `isPinned` for `true`, ele também aparece como um botão de ação rápida no canto superior direito da página.
-
-```ts src/command-menu-items/open-dashboard.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- label: 'Open Dashboard',
- shortLabel: 'Dashboard',
- icon: 'IconLayoutDashboard',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-| Campo | Obrigatório | Descrição |
-| --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | Sim | ID exclusivo e estável para o comando |
-| `label` | Sim | Rótulo completo exibido no menu de comandos (Cmd+K) |
-| `frontComponentUniversalIdentifier` | Sim | O `universalIdentifier` do componente de front-end que este comando abre |
-| `shortLabel` | Não | Rótulo mais curto exibido no botão fixado de ação rápida |
-| `icon` | Não | Nome do ícone exibido ao lado do rótulo (por exemplo, `'IconBolt'`, `'IconSend'`) |
-| `isPinned` | Não | Quando `true`, mostra o comando como um botão de ação rápida no canto superior direito da página |
-| `availabilityType` | Não | Controla onde o comando aparece: `'GLOBAL'` (sempre disponível), `'RECORD_SELECTION'` (apenas quando registros estão selecionados) ou `'FALLBACK'` (exibido quando nenhum outro comando corresponde) |
-| `availabilityObjectUniversalIdentifier` | Não | Restringe o comando a páginas de um tipo específico de objeto (por exemplo, somente em registros de Company) |
-| `conditionalAvailabilityExpression` | Não | Uma expressão booleana para controlar dinamicamente se o comando é visível (veja abaixo) |
-
-## Expressões de disponibilidade condicional
-
-O campo `conditionalAvailabilityExpression` permite controlar quando um comando é visível com base no contexto da página atual. Importe variáveis tipadas e operadores de `twenty-sdk` para construir expressões:
-
-```ts src/command-menu-items/bulk-update.command-menu-item.ts
-import {
- defineCommandMenuItem,
- objectPermissions,
- everyEquals,
-} from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: '...',
- label: 'Bulk Update',
- availabilityType: 'RECORD_SELECTION',
- frontComponentUniversalIdentifier: '...',
- conditionalAvailabilityExpression: everyEquals(
- objectPermissions,
- 'canUpdateObjectRecords',
- true,
- ),
-});
-```
-
-**Variáveis de contexto** — representam o estado atual da página:
-
-| Variável | Tipo | Descrição |
-| ------------------------------ | --------- | --------------------------------------------------------------------------- |
-| `pageType` | `string` | Tipo de página atual (por exemplo, `'RecordIndexPage'`, `'RecordShowPage'`) |
-| `isInSidePanel` | `boolean` | Se o componente é renderizado em um painel lateral |
-| `numberOfSelectedRecords` | `number` | Número de registros atualmente selecionados |
-| `isSelectAll` | `boolean` | Se "selecionar tudo" está ativo |
-| `selectedRecords` | `array` | Os objetos de registro selecionados |
-| `favoriteRecordIds` | `array` | IDs dos registros marcados como favoritos |
-| `objectPermissions` | `object` | Permissões para o tipo de objeto atual |
-| `targetObjectReadPermissions` | `object` | Permissões de leitura para o objeto alvo |
-| `targetObjectWritePermissions` | `object` | Permissões de escrita para o objeto alvo |
-| `featureFlags` | `object` | Flags de recurso ativas |
-| `objectMetadataItem` | `object` | Metadados do tipo de objeto atual |
-| `hasAnySoftDeleteFilterOnView` | `boolean` | Se a visualização atual tem um filtro de soft-delete |
-
-**Operadores** — combine variáveis em expressões booleanas:
-
-| Operador | Descrição |
-| ----------------------------------- | ---------------------------------------------------------------------- |
-| `isDefined(value)` | `true` se o valor não for null/undefined |
-| `isNonEmptyString(value)` | `true` se o valor for uma string não vazia |
-| `includes(array, value)` | `true` se o array contiver o valor |
-| `includesEvery(array, prop, value)` | `true` se a propriedade de cada item incluir o valor |
-| `every(array, prop)` | `true` se a propriedade for truthy em cada item |
-| `everyDefined(array, prop)` | `true` se a propriedade estiver definida em cada item |
-| `everyEquals(array, prop, value)` | `true` se a propriedade for igual ao valor em cada item |
-| `some(array, prop)` | `true` se a propriedade for truthy em pelo menos um item |
-| `someDefined(array, prop)` | `true` se a propriedade estiver definida em pelo menos um item |
-| `someEquals(array, prop, value)` | `true` se a propriedade for igual ao valor em pelo menos um item |
-| `someNonEmptyString(array, prop)` | `true` se a propriedade for uma string não vazia em pelo menos um item |
-| `none(array, prop)` | `true` se a propriedade for falsy em cada item |
-| `noneDefined(array, prop)` | `true` se a propriedade for undefined em cada item |
-| `noneEquals(array, prop, value)` | `true` se a propriedade não for igual ao valor em nenhum item |
-
-## Recursos públicos
-
-Componentes de front-end podem acessar arquivos do diretório `public/` do app usando `getPublicAssetUrl`:
-
-```tsx
-import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
-
-const Logo = () => Export {selectedRecordIds.length} selected record(s)?
- -;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-Veja a [seção de recursos públicos](/l/pt/developers/extend/apps/cli-and-testing#public-assets-public-folder) para obter detalhes.
-
-## Estilização
-
-Componentes de front-end suportam várias abordagens de estilização. Você pode usar:
-
-* **Estilos inline** — `style={{ color: 'red' }}`
-* **Componentes de UI do Twenty** — importe de `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar e mais)
-* **Emotion** — CSS-in-JS com `@emotion/react`
-* **Styled-components** — padrões `styled.div`
-* **Tailwind CSS** — classes utilitárias
-* **Qualquer biblioteca CSS-in-JS** compatível com React
-
-```tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index 7649045ee2..0000000000
--- a/packages/twenty-docs/l/pt/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,273 +0,0 @@
----
-title: Primeiros passos
-icon: rocket
-description: Crie seu primeiro app do Twenty em minutos.
----
-
-## Pré-requisitos
-
-* **Node.js 24+** — [Baixar](https://nodejs.org/)
-* **Yarn 4** — Vem com o Node.js via Corepack. Ative-o: `corepack enable`
-* **Docker** — [Baixar](https://www.docker.com/products/docker-desktop/). Necessário para executar um servidor Twenty local. Ignore se você já tiver o Twenty em execução em outro lugar.
-
-A criação de um aplicativo Twenty tem três fases. A ferramenta de scaffolding as reúne em um único comando do fluxo ideal, mas cada fase é um conceito separado — quando algo falha, saber em que fase você está indica o que corrigir.
-
-| Fase | O que você faz | Ferramenta | Resultado |
-| --------------------------- | -------------------------------------------------- | ----------------------------- | ------------------------------------- |
-| **1. Criar scaffolding** | Gerar o código-fonte do aplicativo | `npx create-twenty-app` | Um projeto TypeScript em disco |
-| **2. Executar um servidor** | Iniciar um servidor Twenty para o qual sincronizar | Docker + `yarn twenty server` | Uma instância Twenty em execução |
-| **3. Sincronizar** | Sincronize seu código em tempo real com o servidor | `yarn twenty dev` | Suas alterações aparecem na interface |
-
----
-
-## Fase 1 — Fazer scaffolding do seu projeto
-
-Crie um novo aplicativo a partir do modelo:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-Você será solicitado a informar um nome e uma descrição — pressione **Enter** para aceitar os valores padrão. Isso gera um projeto TypeScript em `my-twenty-app/` com um `application-config.ts` inicial, um papel padrão, um fluxo de trabalho de CI e um teste de integração.
-
-**Após esta fase:** você tem o código-fonte de um aplicativo na sua máquina. Ele ainda não está em execução — isso é a Fase 2.
-
----
-
-## Fase 2 — Executar um servidor Twenty local
-
-Seu aplicativo precisa de um servidor Twenty para o qual sincronizar. O servidor é uma instância completa do Twenty — interface, API GraphQL, PostgreSQL — executando localmente no Docker. Seu código local envia suas definições para esse servidor, o que faz com que elas apareçam na interface.
-
-A ferramenta de scaffolding oferece iniciar um para você:
-
-> **Você gostaria de configurar uma instância local do Twenty?**
-
-* **Sim (recomendado)** — baixa a imagem Docker `twentycrm/twenty-app-dev` e a inicia na porta `2020`. Certifique-se de que o Docker esteja em execução primeiro.
-* **Não** — escolha isto se você já tiver um servidor Twenty ao qual deseja se conectar. Você pode conectá-lo depois com `yarn twenty remote add`.
-
-
-
-
-
-Quando o servidor estiver ativo, um navegador será aberto para login. Use a conta de demonstração pré-configurada:
-
-* **E-mail:** `tim@apple.dev`
-* **Senha:** `tim@apple.dev`
-
-
-
-
-
-
-Clique em **Authorize** na próxima tela — isso dá à CLI acesso ao seu espaço de trabalho.
-
-
-
-
-
-
-Seu terminal confirmará que tudo está configurado.
-
-
-
-
-
-
-**Após esta fase:** você tem um servidor Twenty em execução em [http://localhost:2020](http://localhost:2020) com sua CLI autorizada a sincronizar com ele.
-
-
-
-
-
-
-Abra [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Você deverá ver seu aplicativo em **Your Apps**.
-
-
-
-
-
-
-Clique em **My twenty app** para ver seu **registro do aplicativo** — um registro em nível de servidor que descreve seu aplicativo (nome, identificador, credenciais OAuth, origem). Um registro pode ser instalado em vários espaços de trabalho no mesmo servidor.
-
-
-
-
-
-
-Clique em **View installed app** para ver a instalação no espaço de trabalho. A aba **About** mostra a versão e as opções de gerenciamento.
-
-
-
-
-
-
-**Após esta fase:** você tem um ciclo de desenvolvimento em tempo real. Edite qualquer arquivo em `src/` e ele aparecerá na interface.
-
-### Sincronização única para CI e scripts
-
-Passe `--once` para executar uma única compilação + sincronização e sair — mesmo pipeline, sem watcher:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Comando | Comportamento | Quando usar |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `yarn twenty dev` | Monitora e ressincroniza a cada alteração. Fica em execução até você interrompê-lo. | Desenvolvimento local interativo. |
-| `yarn twenty dev --once` | Executa uma única compilação + sincronização e, em seguida, encerra com o código `0` em caso de sucesso ou `1` em caso de falha. | Scripts, CI, hooks de pre-commit, agentes de IA e fluxos de trabalho com script. |
-
-Ambos os modos precisam de um servidor em modo de desenvolvimento e de um remoto autenticado.
-
-
-Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### Cum funcționează împachetarea - -Pasul de build folosește esbuild pentru a produce un singur fișier autonom pentru fiecare funcție logică și pentru fiecare componentă frontend. Toate pachetele importate sunt integrate în bundle. - -**Funcțiile logice** rulează într-un mediu Node.js. Modulele built-in Node (`fs`, `path`, `crypto`, `http` etc.) sunt disponibile și nu trebuie instalate. - -**Componentele frontend** rulează într-un Web Worker. Modulele built-in Node nu sunt disponibile — doar API-urile de browser și pachetele npm care funcționează într-un mediu de browser. - -Ambele medii au `twenty-client-sdk/core` și `twenty-client-sdk/metadata` disponibile ca module pre-furnizate — acestea nu sunt incluse în bundle, ci sunt rezolvate la rulare de către server. - -## Testarea aplicației - -SDK-ul oferă API-uri programatice care vă permit să construiți, să distribuiți, să instalați și să dezinstalați aplicația din codul de test. Combinat cu [Vitest](https://vitest.dev/) și clienții API tipizați, puteți scrie teste de integrare care verifică faptul că aplicația funcționează cap-coadă împotriva unui server Twenty real. - -### Configurare - -Aplicația generată (scaffolded) include deja Vitest. Dacă o configurați manual, instalați dependențele: - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -Creați un `vitest.config.ts` în rădăcina aplicației: - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -Creați un fișier de configurare care verifică faptul că serverul este accesibil înainte de rularea testelor: - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### API-uri SDK programatice - -Subruta `twenty-sdk/cli` exportă funcții pe care le puteți apela direct din codul de test: - -| Funcție | Descriere | -| -------------- | --------------------------------------------------------- | -| `appBuild` | Construiți aplicația și, opțional, împachetați un tarball | -| `appDeploy` | Încărcați un tarball pe server | -| `appInstall` | Instalați aplicația în spațiul de lucru activ | -| `appUninstall` | Dezinstalați aplicația din spațiul de lucru activ | - -Fiecare funcție returnează un obiect rezultat cu `success: boolean` și fie `data`, fie `error`. - -### Scrierea unui test de integrare - -Iată un exemplu complet care construiește, distribuie și instalează aplicația, apoi verifică faptul că aceasta apare în spațiul de lucru: - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### Rularea testelor - -Asigurați-vă că serverul Twenty local rulează, apoi: - -```bash filename="Terminal" -yarn test -``` - -Sau în modul watch în timpul dezvoltării: - -```bash filename="Terminal" -yarn test:watch -``` - -### Verificarea tipurilor - -Puteți rula și verificarea tipurilor pe aplicație fără a rula testele: - -```bash filename="Terminal" -yarn twenty typecheck -``` - -Aceasta rulează `tsc --noEmit` și raportează orice erori de tip. - -## Referință CLI - -Dincolo de `dev`, `build`, `add` și `typecheck`, CLI oferă comenzi pentru executarea funcțiilor, vizualizarea jurnalelor și gestionarea instalărilor de aplicații. - -### Executarea funcțiilor (`yarn twenty exec`) - -Rulați manual o funcție logică fără a o declanșa prin HTTP, cron sau eveniment de bază de date: - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### Vizualizarea jurnalelor funcțiilor (`yarn twenty logs`) - -Transmiteți în flux jurnalele de execuție pentru funcțiile logice ale aplicației: - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
- name: 'hello-world',
- description: 'A simple front component',
- component: HelloWorld,
-});
-```
-
-```ts src/command-menu-items/hello-world.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
- shortLabel: 'Hello',
- label: 'Hello World',
- icon: 'IconBolt',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-După sincronizarea cu `yarn twenty dev` (sau prin rularea comenzii `yarn twenty dev --once` o singură dată), acțiunea rapidă apare în colțul din dreapta sus al paginii:
-
-Hello from my app!
-This component renders inside Twenty.
-
-
-
-
-Faceți clic pe el pentru a afișa componenta inline.
-
-## Câmpuri de configurare
-
-| Câmp | Obligatoriu | Descriere |
-| --------------------- | ----------- | --------------------------------------------------------------------------- |
-| `universalIdentifier` | Da | ID unic stabil pentru această componentă |
-| `component` | Da | O funcție de componentă React |
-| `name` | Nu | Nume afișat |
-| `description` | Nu | Descriere a ceea ce face componenta |
-| `isHeadless` | Nu | Setați la `true` dacă componenta nu are interfață vizibilă (vedeți mai jos) |
-
-## Plasarea unei componente front-end pe o pagină
-
-Dincolo de comenzi, puteți încorpora o componentă front-end direct într-o pagină de înregistrare adăugând-o ca widget într-un **layout de pagină**. Consultați secțiunea [definePageLayout](/l/ro/developers/extend/apps/skills-and-agents#definepagelayout) pentru detalii.
-
-## Headless vs non-headless
-
-Componentele frontale au două moduri de randare controlate de opțiunea `isHeadless`:
-
-**Non-headless (implicit)** — Componenta afișează o interfață vizibilă. Când este declanșat din meniul de comenzi, se deschide în panoul lateral. Acesta este comportamentul implicit când `isHeadless` este `false` sau omis.
-
-**Headless (`isHeadless: true`)** — Componenta se montează invizibil în fundal. Nu deschide panoul lateral. Componentele headless sunt concepute pentru acțiuni care execută logică și apoi se demontează — de exemplu, rularea unei sarcini asincrone, navigarea la o pagină sau afișarea unui modal de confirmare. Se potrivesc în mod natural cu componentele Command din SDK descrise mai jos.
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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,
-});
-```
-
-Deoarece componenta returnează `null`, Twenty omite redarea unui container pentru ea — nu apare spațiu gol în layout. Componenta are în continuare acces la toate hook-urile și la API-ul de comunicare cu gazda.
-
-## Componentele Command din SDK
-
-Pachetul `twenty-sdk` oferă patru componente ajutătoare Command, concepute pentru componente front-end headless. Fiecare componentă execută o acțiune la montare, gestionează erorile afișând o notificare snackbar și demontează automat componenta de interfață la final.
-
-Importă-le din `twenty-sdk/command`:
-
-* **`Command`** — Rulează un callback asincron prin prop-ul `execute`.
-* **`CommandLink`** — Navighează către o rută a aplicației. Props: `to`, `params`, `queryParams`, `options`.
-* **`CommandModal`** — Deschide un modal de confirmare. Dacă utilizatorul confirmă, execută callback-ul `execute`. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
-* **`CommandOpenSidePanelPage`** — Deschide o anumită pagină din panoul lateral. Props: `page`, `pageTitle`, `pageIcon`.
-
-Iată un exemplu complet de componentă front-end headless care folosește `Command` pentru a rula o acțiune din meniul de comenzi:
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
- name: 'record-info',
- component: RecordInfo,
-});
-```
-
-Hook-uri disponibile:
-
-| Hook | Returnează | Descriere |
-| --------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------- |
-| `useUserId()` | `string` sau `null` | ID-ul utilizatorului curent |
-| `useSelectedRecordIds()` | `string[]` | Toate ID-urile înregistrărilor selectate (array gol dacă nu este selectată niciuna) |
-| `useRecordId()` | `string` sau `null` | **Învechit.** Folosiți `useSelectedRecordIds()` în schimb |
-| `useFrontComponentId()` | `string` | ID-ul acestei instanțe de componentă |
-| `useFrontComponentExecutionContext(selector)` | variază | Accesați întregul context de execuție cu o funcție selector |
-
-## API-ul de comunicare cu gazda
-
-Componentele front-end pot declanșa navigare, ferestre modale și notificări folosind funcții din `twenty-sdk`:
-
-| Funcție | Descriere |
-| ----------------------------------------------- | ----------------------------------- |
-| `navigate(to, params?, queryParams?, options?)` | Navigați la o pagină din aplicație |
-| `openSidePanelPage(params)` | Deschideți un panou lateral |
-| `closeSidePanel()` | Închideți panoul lateral |
-| `openCommandConfirmationModal(params)` | Afișați un dialog de confirmare |
-| `enqueueSnackbar(params)` | Afișați o notificare tip toast |
-| `unmountFrontComponent()` | Demontați componenta |
-| `updateProgress(progress)` | Actualizați un indicator de progres |
-
-Iată un exemplu care folosește API-ul gazdă pentru a afișa un snackbar și a închide panoul lateral după finalizarea unei acțiuni:
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Lucrul cu mai multe înregistrări
-
-Folosiți `useSelectedRecordIds()` pentru a gestiona mai multe înregistrări selectate. Acest lucru este util pentru operațiuni în masă:
-
-```tsx src/front-components/bulk-export.tsx
-import { defineFrontComponent, numberOfSelectedRecords } from 'twenty-sdk/define';
-import { useSelectedRecordIds } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const BulkExport = () => {
- const selectedRecordIds = useSelectedRecordIds();
-
- const handleExport = async () => {
- const client = new CoreApiClient();
-
- for (const recordId of selectedRecordIds) {
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { exported: true } },
- id: true,
- },
- });
- }
-
- await enqueueSnackbar({
- message: `Exported ${selectedRecordIds.length} records`,
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- Archive this record?
- -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
- name: 'bulk-export',
- description: 'Export selected records',
- component: BulkExport,
- command: {
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
- label: 'Bulk Export',
- availabilityType: 'RECORD_SELECTION',
- conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
- },
-});
-```
-
-## defineCommandMenuItem
-
-Folosiți `defineCommandMenuItem` pentru a înregistra o componentă front-end în meniul de comenzi (Cmd+K). Dacă `isPinned` este `true`, apare și ca buton de acțiune rapidă în colțul din dreapta sus al paginii.
-
-```ts src/command-menu-items/open-dashboard.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- label: 'Open Dashboard',
- shortLabel: 'Dashboard',
- icon: 'IconLayoutDashboard',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-| Câmp | Obligatoriu | Descriere |
-| --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `universalIdentifier` | Da | ID unic stabil pentru comandă |
-| `label` | Da | Etichetă completă afișată în meniul de comenzi (Cmd+K) |
-| `frontComponentUniversalIdentifier` | Da | `universalIdentifier` al componentei front-end pe care această comandă o deschide |
-| `shortLabel` | Nu | Etichetă mai scurtă afișată pe butonul de acțiune rapidă fixat |
-| `icon` | Nu | Numele pictogramei afișat lângă etichetă (de ex. `'IconBolt'`, `'IconSend'`) |
-| `isPinned` | Nu | Când este `true`, afișează comanda ca buton de acțiune rapidă în colțul din dreapta sus al paginii |
-| `availabilityType` | Nu | Controlează unde apare comanda: `'GLOBAL'` (mereu disponibilă), `'RECORD_SELECTION'` (doar când sunt selectate înregistrări) sau `'FALLBACK'` (afișată când nicio altă comandă nu se potrivește) |
-| `availabilityObjectUniversalIdentifier` | Nu | Restricționați comanda la paginile unui anumit tip de obiect (de ex., doar pe înregistrările Company) |
-| `conditionalAvailabilityExpression` | Nu | O expresie booleană pentru a controla dinamic dacă comanda este vizibilă (vezi mai jos) |
-
-## Expresii de disponibilitate condițională
-
-Câmpul `conditionalAvailabilityExpression` vă permite să controlați când este vizibilă o comandă în funcție de contextul paginii curente. Importați variabile tipizate și operatori din `twenty-sdk` pentru a construi expresii:
-
-```ts src/command-menu-items/bulk-update.command-menu-item.ts
-import {
- defineCommandMenuItem,
- objectPermissions,
- everyEquals,
-} from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: '...',
- label: 'Bulk Update',
- availabilityType: 'RECORD_SELECTION',
- frontComponentUniversalIdentifier: '...',
- conditionalAvailabilityExpression: everyEquals(
- objectPermissions,
- 'canUpdateObjectRecords',
- true,
- ),
-});
-```
-
-**Variabile de context** — acestea reprezintă starea curentă a paginii:
-
-| Variabilă | Tip | Descriere |
-| ------------------------------ | --------- | ---------------------------------------------------------------------- |
-| `pageType` | `string` | Tipul paginii curente (de ex. `'RecordIndexPage'`, `'RecordShowPage'`) |
-| `isInSidePanel` | `boolean` | Dacă componenta este redată într-un panou lateral |
-| `numberOfSelectedRecords` | `number` | Numărul de înregistrări selectate în prezent |
-| `isSelectAll` | `boolean` | Dacă "select all" este activ |
-| `selectedRecords` | `array` | Obiectele înregistrărilor selectate |
-| `favoriteRecordIds` | `array` | ID-urile înregistrărilor marcate ca favorite |
-| `objectPermissions` | `object` | Permisiuni pentru tipul de obiect curent |
-| `targetObjectReadPermissions` | `object` | Permisiuni de citire pentru obiectul țintă |
-| `targetObjectWritePermissions` | `object` | Permisiuni de scriere pentru obiectul țintă |
-| `featureFlags` | `object` | Steaguri de caracteristici active |
-| `objectMetadataItem` | `object` | Metadatele tipului de obiect curent |
-| `hasAnySoftDeleteFilterOnView` | `boolean` | Dacă vizualizarea curentă are un filtru soft-delete |
-
-**Operatori** — combinați variabilele în expresii booleene:
-
-| Operator | Descriere |
-| ----------------------------------- | ----------------------------------------------------------------------- |
-| `isDefined(value)` | `true` dacă valoarea nu este null/undefined |
-| `isNonEmptyString(value)` | `true` dacă valoarea este un șir nevid |
-| `includes(array, value)` | `true` dacă array-ul conține valoarea |
-| `includesEvery(array, prop, value)` | `true` dacă proprietatea fiecărui element include valoarea |
-| `every(array, prop)` | `true` dacă proprietatea este truthy pentru fiecare element |
-| `everyDefined(array, prop)` | `true` dacă proprietatea este definită pentru fiecare element |
-| `everyEquals(array, prop, value)` | `true` dacă proprietatea este egală cu valoarea pentru fiecare element |
-| `some(array, prop)` | `true` dacă proprietatea este truthy pe cel puțin un element |
-| `someDefined(array, prop)` | `true` dacă proprietatea este definită pe cel puțin un element |
-| `someEquals(array, prop, value)` | `true` dacă proprietatea este egală cu valoarea pe cel puțin un element |
-| `someNonEmptyString(array, prop)` | `true` dacă proprietatea este un șir nevid pe cel puțin un element |
-| `none(array, prop)` | `true` dacă proprietatea este falsy pentru fiecare element |
-| `noneDefined(array, prop)` | `true` dacă proprietatea este nedefinită pentru fiecare element |
-| `noneEquals(array, prop, value)` | `true` dacă proprietatea nu este egală cu valoarea pe niciun element |
-
-## Resurse publice
-
-Componentele front-end pot accesa fișiere din directorul `public/` al aplicației folosind `getPublicAssetUrl`:
-
-```tsx
-import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
-
-const Logo = () => Export {selectedRecordIds.length} selected record(s)?
- -;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-Consultați [secțiunea despre resurse publice](/l/ro/developers/extend/apps/cli-and-testing#public-assets-public-folder) pentru detalii.
-
-## Stilizare
-
-Componentele front-end acceptă mai multe abordări de stilizare. Puteți folosi:
-
-* **Stiluri inline** — `style={{ color: 'red' }}`
-* **Componente Twenty UI** — import din `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar și altele)
-* **Emotion** — CSS-in-JS cu `@emotion/react`
-* **Styled-components** — pattern-uri `styled.div`
-* **Tailwind CSS** — clase utilitare
-* **Orice bibliotecă CSS-in-JS** compatibilă cu React
-
-```tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index cae329e476..0000000000
--- a/packages/twenty-docs/l/ro/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,273 +0,0 @@
----
-title: Începeți
-icon: rocket
-description: Creați prima dvs. aplicație Twenty în câteva minute.
----
-
-## Cerințe
-
-* **Node.js 24+** — [Descărcați](https://nodejs.org/)
-* **Yarn 4** — vine împreună cu Node prin Corepack. Activați-l: `corepack enable`
-* **Docker** — [Descărcați](https://www.docker.com/products/docker-desktop/). Necesar pentru a rula un server Twenty local. Omiteți dacă rulați deja Twenty în altă parte.
-
-Crearea unei aplicații Twenty are trei faze. Generatorul de schelet le reduce la o singură comandă pe happy path, dar fiecare fază este un concept separat — când ceva eșuează, dacă știți în ce fază sunteți, știți ce trebuie să corectați.
-
-| Fază | Ce faceți | Instrument | Rezultat |
-| ----------------------- | ------------------------------------------------ | ----------------------------- | ------------------------------ |
-| **1. Creați scheletul** | Generați codul sursă al aplicației | `npx create-twenty-app` | Un proiect TypeScript pe disc |
-| **2. Rulați un server** | Porniți un server Twenty cu care să sincronizați | Docker + `yarn twenty server` | O instanță Twenty care rulează |
-| **3. Sincronizați** | Sincronizați în timp real codul cu serverul | `yarn twenty dev` | Modificările apar în UI |
-
----
-
-## Faza 1 — Creați scheletul proiectului
-
-Creați o nouă aplicație din șablon:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-Vi se va cere un nume și o descriere — apăsați **Enter** pentru valorile implicite. Aceasta generează un proiect TypeScript în `my-twenty-app/` cu un fișier inițial `application-config.ts`, un rol implicit, un flux de lucru CI și un test de integrare.
-
-**După această fază:** aveți codul sursă al aplicației pe mașina dvs. Încă nu rulează — aceasta este Faza 2.
-
----
-
-## Faza 2 — Rulați un server Twenty local
-
-Aplicația are nevoie de un server Twenty cu care să se sincronizeze. Serverul este o instanță Twenty completă — UI, API GraphQL, PostgreSQL — care rulează local în Docker. Codul local încarcă definițiile pe acel server, făcându-le să apară în UI.
-
-Generatorul de schelet vă propune să pornească unul pentru dvs.:
-
-> **Doriți să configurați o instanță Twenty locală?**
-
-* **Yes (recomandat)** — descarcă imaginea Docker `twentycrm/twenty-app-dev` și o pornește pe portul `2020`. Asigurați-vă mai întâi că Docker rulează.
-* **No** — alegeți această opțiune dacă aveți deja un server Twenty la care doriți să vă conectați. Îl puteți conecta ulterior cu `yarn twenty remote add`.
-
-
-
-
-
-După ce serverul pornește, se deschide un browser pentru autentificare. Folosiți contul demo preconfigurat:
-
-* **E-mail:** `tim@apple.dev`
-* **Parolă:** `tim@apple.dev`
-
-
-
-
-
-
-Faceți clic pe **Authorize** pe ecranul următor — aceasta oferă CLI-ului acces la spațiul dvs. de lucru.
-
-
-
-
-
-
-Terminalul va confirma că totul este configurat.
-
-
-
-
-
-
-**După această fază:** aveți un server Twenty care rulează la [http://localhost:2020](http://localhost:2020), iar CLI-ul dvs. este autorizat să sincronizeze cu acesta.
-
-
-
-
-
-
-Deschideți [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Ar trebui să vedeți aplicația dvs. listată la **Your Apps**.
-
-
-
-
-
-
-Faceți clic pe **My twenty app** pentru a vedea **înregistrarea aplicației** — o înregistrare la nivel de server care descrie aplicația dvs. (nume, identificator, credențiale OAuth, sursă). O singură înregistrare poate fi instalată în mai multe spații de lucru pe același server.
-
-
-
-
-
-
-Faceți clic pe **View installed app** pentru a vedea instalarea în spațiul de lucru. Fila **About** afișează versiunea și opțiunile de administrare.
-
-
-
-
-
-
-**După această fază:** aveți o buclă de dezvoltare în timp real. Editați orice fișier în `src/` și acesta apare în UI.
-
-### Sincronizare unică pentru CI și scripturi
-
-Adăugați `--once` pentru a rula un singur build + sync și a ieși — același flux, fără watcher:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Comandă | Comportament | Când se folosește |
-| ------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
-| `yarn twenty dev` | Monitorizează și resincronizează la fiecare modificare. Rulează până când îl opriți. | Dezvoltare locală interactivă. |
-| `yarn twenty dev --once` | Un singur build + sync, iese cu `0` la succes, `1` la eșec. | CI, hook-uri pre-commit, agenți AI, fluxuri de lucru scriptate. |
-
-Ambele moduri necesită un server în modul de dezvoltare și un remote autentificat.
-
-
-Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### Как работает бандлинг - -Этап сборки использует esbuild для создания одного самодостаточного файла на каждую логическую функцию и на каждый компонент фронтенда. Все импортированные пакеты встроены в бандл. - -**Логические функции** выполняются в среде Node.js. Встроенные модули Node (`fs`, `path`, `crypto`, `http` и т. д.) доступны и не требуют установки. - -**Компоненты фронтенда** выполняются в Web Worker. Встроенные модули Node недоступны — доступны только браузерные API и пакеты npm, работающие в браузерной среде. - -В обеих средах доступны как предварительно предоставленные модули `twenty-client-sdk/core` и `twenty-client-sdk/metadata` — они не включаются в бандл, а подставляются сервером во время выполнения. - -## Тестирование вашего приложения - -SDK предоставляет программные API, которые позволяют собирать, разворачивать, устанавливать и удалять ваше приложение из тестового кода. В сочетании с [Vitest](https://vitest.dev/) и типизированными клиентами API вы можете писать интеграционные тесты, которые проверяют, что ваше приложение работает сквозным образом на реальном сервере Twenty. - -### Настройка - -Приложение, созданное скэффолдером, уже включает Vitest. Если вы настраиваете его вручную, установите зависимости: - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -Создайте `vitest.config.ts` в корне вашего приложения: - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -Создайте файл инициализации, который проверяет доступность сервера перед запуском тестов: - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### Программные API SDK - -Подпуть `twenty-sdk/cli` экспортирует функции, которые можно вызывать напрямую из тестового кода: - -| Функция | Описание | -| -------------- | ---------------------------------------------------------- | -| `appBuild` | Собрать приложение и при необходимости упаковать tar-архив | -| `appDeploy` | Загрузить tar-архив на сервер | -| `appInstall` | Установить приложение в активное рабочее пространство | -| `appUninstall` | Удалить приложение из активного рабочего пространства | - -Каждая функция возвращает объект результата с `success: boolean` и либо `data`, либо `error`. - -### Написание интеграционного теста - -Полный пример, который собирает, разворачивает и устанавливает приложение, а затем проверяет, что оно появляется в рабочем пространстве: - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### Запуск тестов - -Убедитесь, что ваш локальный сервер Twenty запущен, затем: - -```bash filename="Terminal" -yarn test -``` - -Или в режиме наблюдения во время разработки: - -```bash filename="Terminal" -yarn test:watch -``` - -### Проверка типов - -Вы также можете запустить проверку типов для своего приложения без запуска тестов: - -```bash filename="Terminal" -yarn twenty typecheck -``` - -Это запускает `tsc --noEmit` и сообщает о любых ошибках типов. - -## Справочник по CLI - -Помимо `dev`, `build`, `add` и `typecheck`, CLI предоставляет команды для выполнения функций, просмотра логов и управления установками приложений. - -### Выполнение функций (`yarn twenty exec`) - -Запустите логическую функцию вручную, не вызывая её через HTTP, cron или событие базы данных: - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### Просмотр логов функций (`yarn twenty logs`) - -Потоковая передача журналов выполнения логических функций вашего приложения: - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
- name: 'hello-world',
- description: 'A simple front component',
- component: HelloWorld,
-});
-```
-
-```ts src/command-menu-items/hello-world.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
- shortLabel: 'Hello',
- label: 'Hello World',
- icon: 'IconBolt',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-После синхронизации с помощью `yarn twenty dev` (или однократного запуска `yarn twenty dev --once`) быстрое действие появится в правом верхнем углу страницы:
-
-Hello from my app!
-This component renders inside Twenty.
-
-
-
-
-Нажмите её, чтобы отобразить компонент инлайн.
-
-## Поля конфигурации
-
-| Поле | Обязательно | Описание |
-| --------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | Да | Стабильный уникальный идентификатор для этого компонента |
-| `component` | Да | Функция компонента React |
-| `name` | Нет | Отображаемое имя |
-| `description` | Нет | Описание того, что делает компонент |
-| `isHeadless` | Нет | Установите значение `true`, если у компонента нет видимого пользовательского интерфейса (см. ниже) |
-
-## Размещение фронт-компонента на странице
-
-Помимо команд, вы можете встроить фронт-компонент непосредственно на страницу записи, добавив его как виджет в **макет страницы**. См. раздел [definePageLayout](/l/ru/developers/extend/apps/skills-and-agents#definepagelayout) для подробностей.
-
-## Headless и non-headless
-
-Фронт-компоненты поддерживают два режима отображения, управляемых опцией `isHeadless`:
-
-**Non-headless (по умолчанию)** — компонент отображает видимый интерфейс. При запуске из меню команд он открывается в боковой панели. Это поведение по умолчанию, когда `isHeadless` имеет значение `false` или опущен.
-
-**Headless (`isHeadless: true`)** — компонент монтируется невидимо в фоновом режиме. Он не открывает боковую панель. Компоненты headless предназначены для действий, которые выполняют логику и затем размонтируются — например, запуск асинхронной задачи, переход на страницу или показ модального окна подтверждения. Они естественно сочетаются с компонентами SDK Command, описанными ниже.
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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 пропускает рендеринг контейнера для него — в макете не появляется пустое место. Компонент по-прежнему имеет доступ ко всем хукам и API взаимодействия с хостом.
-
-## Компоненты SDK Command
-
-Пакет `twenty-sdk` предоставляет четыре вспомогательных компонента Command, предназначенных для headless фронт-компонентов. Каждый компонент выполняет действие при монтировании, обрабатывает ошибки, показывая уведомление snackbar, и автоматически размонтирует фронт-компонент по завершении.
-
-Импортируйте их из `twenty-sdk/command`:
-
-* **`Command`** — запускает асинхронный колбэк через проп `execute`.
-* **`CommandLink`** — переходит по пути внутри приложения. Пропы: `to`, `params`, `queryParams`, `options`.
-* **`CommandModal`** — открывает модальное окно подтверждения. Если пользователь подтвердит, выполняет колбэк `execute`. Пропы: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
-* **`CommandOpenSidePanelPage`** — открывает конкретную страницу боковой панели. Пропы: `page`, `pageTitle`, `pageIcon`.
-
-Полный пример headless фронт-компонента, использующего `Command` для запуска действия из меню команд:
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
- name: 'record-info',
- component: RecordInfo,
-});
-```
-
-Доступные хуки:
-
-| Хук | Возвращает | Описание |
-| --------------------------------------------- | ------------------- | ---------------------------------------------------------------------------- |
-| `useUserId()` | `string` или `null` | ID текущего пользователя |
-| `useSelectedRecordIds()` | `string[]` | Все выбранные идентификаторы записей (пустой массив, если ничего не выбрано) |
-| `useRecordId()` | `string` или `null` | **Устарело.** Используйте `useSelectedRecordIds()` вместо этого |
-| `useFrontComponentId()` | `string` | ID этого экземпляра компонента |
-| `useFrontComponentExecutionContext(selector)` | различается | Доступ к полному контексту выполнения с помощью функции-селектора |
-
-## API взаимодействия с хостом
-
-Компоненты фронтенда могут вызывать навигацию, модальные окна и уведомления с помощью функций из `twenty-sdk`:
-
-| Функция | Описание |
-| ----------------------------------------------- | -------------------------------- |
-| `navigate(to, params?, queryParams?, options?)` | Перейти на страницу в приложении |
-| `openSidePanelPage(params)` | Открыть боковую панель |
-| `closeSidePanel()` | Закрыть боковую панель |
-| `openCommandConfirmationModal(params)` | Показать диалог подтверждения |
-| `enqueueSnackbar(params)` | Показать всплывающее уведомление |
-| `unmountFrontComponent()` | Размонтировать компонент |
-| `updateProgress(progress)` | Обновить индикатор прогресса |
-
-Пример, который использует API хоста для показа snackbar и закрытия боковой панели после завершения действия:
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Работа с несколькими записями
-
-Используйте `useSelectedRecordIds()` для обработки нескольких выбранных записей. Это полезно для массовых операций:
-
-```tsx src/front-components/bulk-export.tsx
-import { defineFrontComponent, numberOfSelectedRecords } from 'twenty-sdk/define';
-import { useSelectedRecordIds } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const BulkExport = () => {
- const selectedRecordIds = useSelectedRecordIds();
-
- const handleExport = async () => {
- const client = new CoreApiClient();
-
- for (const recordId of selectedRecordIds) {
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { exported: true } },
- id: true,
- },
- });
- }
-
- await enqueueSnackbar({
- message: `Exported ${selectedRecordIds.length} records`,
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- Archive this record?
- -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
- name: 'bulk-export',
- description: 'Export selected records',
- component: BulkExport,
- command: {
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
- label: 'Bulk Export',
- availabilityType: 'RECORD_SELECTION',
- conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
- },
-});
-```
-
-## defineCommandMenuItem
-
-Используйте `defineCommandMenuItem`, чтобы зарегистрировать фронтенд-компонент в меню команд (Cmd+K). Если `isPinned` имеет значение `true`, команда также отображается как кнопка быстрого действия в правом верхнем углу страницы.
-
-```ts src/command-menu-items/open-dashboard.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- label: 'Open Dashboard',
- shortLabel: 'Dashboard',
- icon: 'IconLayoutDashboard',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-| Поле | Обязательно | Описание |
-| --------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | Да | Стабильный уникальный идентификатор для команды |
-| `label` | Да | Полная метка, отображаемая в меню команд (Cmd+K) |
-| `frontComponentUniversalIdentifier` | Да | `universalIdentifier` фронтенд-компонента, который открывается этой командой |
-| `shortLabel` | Нет | Короткая метка, отображаемая на закреплённой кнопке быстрого действия |
-| `icon` | Нет | Имя значка, отображаемое рядом с меткой (например, `'IconBolt'`, `'IconSend'`) |
-| `isPinned` | Нет | При значении `true` показывает команду как кнопку быстрого действия в правом верхнем углу страницы |
-| `availabilityType` | Нет | Определяет, где отображается команда: `'GLOBAL'` (доступна всегда), `'RECORD_SELECTION'` (только при выборе записей) или `'FALLBACK'` (показывается, когда другие команды не подходят) |
-| `availabilityObjectUniversalIdentifier` | Нет | Ограничивает команду страницами определённого типа объектов (например, только для записей Company) |
-| `conditionalAvailabilityExpression` | Нет | Логическое выражение для динамического управления видимостью команды (см. ниже) |
-
-## Выражения условной доступности
-
-Поле `conditionalAvailabilityExpression` позволяет управлять видимостью команды в зависимости от текущего контекста страницы. Импортируйте типизированные переменные и операторы из `twenty-sdk`, чтобы составлять выражения:
-
-```ts src/command-menu-items/bulk-update.command-menu-item.ts
-import {
- defineCommandMenuItem,
- objectPermissions,
- everyEquals,
-} from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: '...',
- label: 'Bulk Update',
- availabilityType: 'RECORD_SELECTION',
- frontComponentUniversalIdentifier: '...',
- conditionalAvailabilityExpression: everyEquals(
- objectPermissions,
- 'canUpdateObjectRecords',
- true,
- ),
-});
-```
-
-**Переменные контекста** — представляют текущее состояние страницы:
-
-| Переменная | Тип | Описание |
-| ------------------------------ | --------- | ------------------------------------------------------------------------ |
-| `pageType` | `string` | Текущий тип страницы (например, `'RecordIndexPage'`, `'RecordShowPage'`) |
-| `isInSidePanel` | `boolean` | Указывает, рендерится ли компонент в боковой панели |
-| `numberOfSelectedRecords` | `number` | Количество выбранных в данный момент записей |
-| `isSelectAll` | `boolean` | Активен ли режим "выбрать все" |
-| `selectedRecords` | `array` | Объекты выбранных записей |
-| `favoriteRecordIds` | `array` | ID избранных записей |
-| `objectPermissions` | `object` | Разрешения для текущего типа объекта |
-| `targetObjectReadPermissions` | `object` | Права на чтение для целевого объекта |
-| `targetObjectWritePermissions` | `object` | Права на запись для целевого объекта |
-| `featureFlags` | `object` | Активные флаги функций |
-| `objectMetadataItem` | `object` | Метаданные текущего типа объекта |
-| `hasAnySoftDeleteFilterOnView` | `boolean` | Есть ли у текущего представления фильтр мягкого удаления |
-
-**Операторы** — комбинируют переменные в логические выражения:
-
-| Оператор | Описание |
-| ----------------------------------- | ------------------------------------------------------------------------- |
-| `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/define';
-
-const Logo = () => Export {selectedRecordIds.length} selected record(s)?
- -;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-См. [раздел о публичных ресурсах](/l/ru/developers/extend/apps/cli-and-testing#public-assets-public-folder) для подробностей.
-
-## Стилизация
-
-Компоненты фронтенда поддерживают несколько подходов к стилизации. Вы можете использовать:
-
-* **Встроенные стили** — `style={{ color: 'red' }}`
-* **Компоненты Twenty UI** — импорт из `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/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/ru/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index 063f5031bd..0000000000
--- a/packages/twenty-docs/l/ru/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,273 +0,0 @@
----
-title: Начало работы
-icon: rocket
-description: Создайте своё первое приложение Twenty за считанные минуты.
----
-
-## Требования
-
-* **Node.js 24+** — [Скачать здесь](https://nodejs.org/)
-* **Yarn 4** — поставляется вместе с Node.js через Corepack. Включите его, выполнив `corepack enable`
-* **Docker** — [Скачать здесь](https://www.docker.com/products/docker-desktop/). Требуется для запуска локального экземпляра Twenty. Пропустите, если у вас уже запущен Twenty в другом месте.
-
-Создание приложения Twenty включает три фазы. Генератор каркаса объединяет их в одну команду для идеального сценария (happy path), но каждая фаза — отдельная концепция: когда что-то идёт не так, понимание того, на какой фазе вы находитесь, подскажет, что исправить.
-
-| Фаза | Что вы делаете | Инструмент | Результат |
-| ----------------------- | ------------------------------------------------- | ----------------------------- | -------------------------------------- |
-| **1. Создание каркаса** | Сгенерировать исходный код приложения | `npx create-twenty-app` | Проект TypeScript на диске |
-| **2. Запустить сервер** | Запустить сервер Twenty для синхронизации | Docker + `yarn twenty server` | Запущенный экземпляр Twenty |
-| **3. Синхронизация** | Синхронизируйте код с сервером в реальном времени | `yarn twenty dev` | Ваши изменения появляются в интерфейсе |
-
----
-
-## Фаза 1 — Сгенерируйте каркас проекта
-
-Создайте новое приложение из шаблона:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-Вам будет предложено ввести имя и описание — нажмите **Enter**, чтобы принять значения по умолчанию. Это создаст проект TypeScript в `my-twenty-app/` с начальным файлом `application-config.ts`, ролью по умолчанию, рабочим процессом CI и интеграционным тестом.
-
-**После этой фазы:** у вас есть исходный код приложения на вашем компьютере. Он ещё не запущен — это фаза 2.
-
----
-
-## Фаза 2 — Запустите локальный сервер Twenty
-
-Вашему приложению нужен сервер Twenty для синхронизации. Сервер — это полноценный экземпляр Twenty — UI, GraphQL API, PostgreSQL — работающий локально в Docker. Ваш локальный код загружает свои определения на этот сервер, благодаря чему они появляются в интерфейсе.
-
-Генератор каркаса предложит запустить его за вас:
-
-> **Хотите настроить локальный экземпляр Twenty?**
-
-* **Да (рекомендуется)** — скачивает Docker-образ `twentycrm/twenty-app-dev` и запускает его на порту `2020`. Сначала убедитесь, что Docker запущен.
-* **Нет** — выберите это, если у вас уже есть сервер Twenty, к которому вы хотите подключиться. Позже вы можете подключить его с помощью `yarn twenty remote add`.
-
-
-
-
-
-Когда сервер будет запущен, откроется браузер для входа. Используйте предварительно созданную демонстрационную учётную запись:
-
-* **Электронная почта:** `tim@apple.dev`
-* **Пароль:** `tim@apple.dev`
-
-
-
-
-
-
-На следующем экране нажмите **Authorize** — это даст CLI доступ к вашему рабочему пространству.
-
-
-
-
-
-
-В вашем терминале появится подтверждение, что всё настроено.
-
-
-
-
-
-
-**После этой фазы:** у вас запущен сервер Twenty на [http://localhost:2020](http://localhost:2020), а ваш CLI авторизован для синхронизации с ним.
-
-
-
-
-
-
-Откройте [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Вы должны увидеть своё приложение в разделе **Your Apps**.
-
-
-
-
-
-
-Нажмите **My twenty app**, чтобы открыть его регистрацию приложения — запись на уровне сервера, описывающую ваше приложение (имя, идентификатор, учётные данные OAuth, источник). Одну и ту же регистрацию можно установить в нескольких рабочих пространствах на одном сервере.
-
-
-
-
-
-
-Нажмите **View installed app**, чтобы посмотреть установку в рабочем пространстве. Вкладка **About** показывает версию и параметры управления.
-
-
-
-
-
-
-**После этой фазы:** у вас есть интерактивный цикл разработки. Отредактируйте любой файл в `src/`, и он появится в интерфейсе.
-
-### Разовая синхронизация для CI и скриптов
-
-Передайте `--once`, чтобы выполнить одну сборку и синхронизацию и завершить работу — тот же конвейер, без наблюдателя:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Команда | Поведение | Когда использовать |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `yarn twenty dev` | Отслеживает и повторно синхронизирует при каждом изменении. Продолжает работать, пока вы его не остановите. | Интерактивная локальная разработка. |
-| `yarn twenty dev --once` | Одна сборка и синхронизация, завершает работу с кодом `0` при успехе и `1` при ошибке. | CI, хуки pre-commit, AI-агенты, скриптовые рабочие процессы. |
-
-Оба режима требуют сервер в режиме разработки и аутентифицированный удалённый сервер.
-
-
-Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### Paketleme nasıl çalışır - -Derleme adımı, her mantık işlevi ve her ön uç bileşeni için tek bir bağımsız dosya üretmek üzere esbuild kullanır. Tüm içe aktarılan paketler pakete satır içi eklenir. - -**Mantık işlevleri**, Node.js ortamında çalışır. Node yerleşik modülleri (`fs`, `path`, `crypto`, `http` vb.) kullanılabilir ve kurulmaları gerekmez. - -**Ön uç bileşenleri**, bir Web Worker içinde çalışır. Node'un yerleşik modülleri **kullanılamaz** — yalnızca tarayıcı ortamında çalışan tarayıcı API'leri ve npm paketleri kullanılabilir. - -Her iki ortamda da `twenty-client-sdk/core` ve `twenty-client-sdk/metadata` önceden sağlanmış modüller olarak mevcuttur — bunlar paketlenmez, ancak çalışma zamanında sunucu tarafından çözülür. - -## Uygulamanızı test etme - -SDK, test kodundan uygulamanızı derlemenize, dağıtmanıza, yüklemenize ve kaldırmanıza olanak tanıyan programatik API'ler sağlar. Tiplenmiş API istemcileriyle birlikte [Vitest](https://vitest.dev/) kullanarak, uygulamanızın gerçek bir Twenty sunucusunda uçtan uca çalıştığını doğrulayan entegrasyon testleri yazabilirsiniz. - -### Kurulum - -İskelet aracıyla oluşturulan uygulama zaten Vitest'i içerir. Manuel kurulum yaparsanız, bağımlılıkları yükleyin: - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -Uygulamanızın kök dizininde bir `vitest.config.ts` oluşturun: - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -Testler çalışmadan önce sunucuya erişilebildiğini doğrulayan bir kurulum dosyası oluşturun: - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### Programatik SDK API'leri - -`twenty-sdk/cli` alt yolu, test kodundan doğrudan çağırabileceğiniz fonksiyonları dışa aktarır: - -| Fonksiyon | Açıklama | -| -------------- | ----------------------------------------------------------------- | -| `appBuild` | Uygulamayı derleyin ve isteğe bağlı olarak bir tarball paketleyin | -| `appDeploy` | Bir tarball'ı sunucuya yükleyin | -| `appInstall` | Uygulamayı etkin çalışma alanına yükleyin | -| `appUninstall` | Uygulamayı etkin çalışma alanından kaldırın | - -Her fonksiyon, `success: boolean` ile birlikte `data` veya `error` içeren bir sonuç nesnesi döndürür. - -### Bir entegrasyon testi yazma - -İşte uygulamayı derleyen, dağıtan ve yükleyen; ardından çalışma alanında göründüğünü doğrulayan tam bir örnek: - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### Testleri çalıştırma - -Yerel Twenty sunucunuzun çalıştığından emin olun, ardından: - -```bash filename="Terminal" -yarn test -``` - -Veya geliştirme sırasında izleme modunda: - -```bash filename="Terminal" -yarn test:watch -``` - -### Tip denetimi - -Ayrıca testleri çalıştırmadan uygulamanızda tip denetimi çalıştırabilirsiniz: - -```bash filename="Terminal" -yarn twenty typecheck -``` - -Bu, `tsc --noEmit` komutunu çalıştırır ve tüm tip hatalarını raporlar. - -## CLI başvurusu - -`dev`, `build`, `add` ve `typecheck` dışında CLI, fonksiyonları çalıştırma, günlükleri görüntüleme ve uygulama kurulumlarını yönetme komutları sağlar. - -### Fonksiyonları çalıştırma (`yarn twenty exec`) - -Bir mantık fonksiyonunu HTTP, cron veya veritabanı olayıyla tetiklemeden manuel olarak çalıştırın: - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### Fonksiyon günlüklerini görüntüleme (`yarn twenty logs`) - -Uygulamanızın mantık fonksiyonlarının yürütme günlüklerini akış olarak alın: - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
- name: 'hello-world',
- description: 'A simple front component',
- component: HelloWorld,
-});
-```
-
-```ts src/command-menu-items/hello-world.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
- shortLabel: 'Hello',
- label: 'Hello World',
- icon: 'IconBolt',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-`yarn twenty dev` ile senkronize ettikten sonra (veya tek seferlik bir `yarn twenty dev --once` çalıştırdıktan sonra), hızlı işlem sayfanın sağ üst köşesinde görünür:
-
-Hello from my app!
-This component renders inside Twenty.
-
-
-
-
-Bileşeni satır içi işlemek için üzerine tıklayın.
-
-## Yapılandırma alanları
-
-| Alan | Zorunlu | Açıklama |
-| --------------------- | ------- | ------------------------------------------------------------------------------------- |
-| `universalIdentifier` | Evet | Bu bileşen için kalıcı benzersiz kimlik |
-| `component` | Evet | Bir React bileşen fonksiyonu |
-| `name` | Hayır | Görünen Ad |
-| `description` | Hayır | Bileşenin ne yaptığına dair açıklama |
-| `isHeadless` | Hayır | Bileşenin görünür bir kullanıcı arayüzü yoksa `true` olarak ayarlayın (aşağıya bakın) |
-
-## Bir ön uç bileşenini bir sayfaya yerleştirme
-
-Komutların ötesinde, bir ön uç bileşenini bir **sayfa düzeninde** widget olarak ekleyerek doğrudan bir kayıt sayfasına gömebilirsiniz. Ayrıntılar için [definePageLayout](/l/tr/developers/extend/apps/skills-and-agents#definepagelayout) bölümüne bakın.
-
-## Headless ve headless olmayan
-
-Ön uç bileşenler, `isHeadless` seçeneğiyle kontrol edilen iki işleme kipiyle gelir:
-
-**Headless olmayan (varsayılan)** — Bileşen görünür bir kullanıcı arayüzü (UI) oluşturur. Komut menüsünden tetiklendiğinde yan panelde açılır. `isHeadless` `false` olduğunda veya belirtilmediğinde bu varsayılan davranıştır.
-
-**Headless (`isHeadless: true`)** — Bileşen arka planda görünmez şekilde bağlanır. Yan paneli açmaz. Headless bileşenler, mantığı çalıştırıp ardından kendilerini kaldıran eylemler için tasarlanmıştır — örneğin, bir async görevi çalıştırma, bir sayfaya gitme veya bir onay modalı gösterme. Aşağıda açıklanan SDK Command bileşenleriyle doğal olarak eşleşirler.
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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,
-});
-```
-
-Bileşen `null` döndürdüğü için, Twenty bunun için bir kapsayıcı oluşturmayı atlar — düzende boş alan görünmez. Bileşen yine de tüm hook'lara ve host iletişim API'sine erişime sahiptir.
-
-## SDK Command bileşenleri
-
-`twenty-sdk` paketi, headless ön bileşenler için tasarlanmış dört Command yardımcı bileşeni sağlar. Her bileşen bağlandığında bir eylem yürütür, hataları bir snackbar bildirimi göstererek ele alır ve tamamlandığında ön bileşeni otomatik olarak kaldırır.
-
-Bunları `twenty-sdk/command` içinden içe aktarın:
-
-* **`Command`** — `execute` prop'u aracılığıyla async bir geri çağrıyı çalıştırır.
-* **`CommandLink`** — Bir uygulama yoluna gider. Props: `to`, `params`, `queryParams`, `options`.
-* **`CommandModal`** — Bir onay modalı açar. Kullanıcı onaylarsa `execute` geri çağrısını yürütür. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
-* **`CommandOpenSidePanelPage`** — Belirli bir yan panel sayfasını açar. Props: `page`, `pageTitle`, `pageIcon`.
-
-`Command` kullanarak komut menüsünden bir eylem çalıştıran headless bir ön bileşenin tam örneği:
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
- name: 'record-info',
- component: RecordInfo,
-});
-```
-
-Kullanılabilir hook'lar:
-
-| Hook | Döndürür | Açıklama |
-| --------------------------------------------- | -------------------- | -------------------------------------------------------------------------- |
-| `useUserId()` | `string` veya `null` | Geçerli kullanıcının ID'si |
-| `useSelectedRecordIds()` | `metin[]` | Tüm seçili kayıt kimlikleri (hiçbiri seçilmediyse boş dizi) |
-| `useRecordId()` | `string` veya `null` | **Kullanımdan kaldırıldı.** Bunun yerine `useSelectedRecordIds()` kullanın |
-| `useFrontComponentId()` | `string` | Bu bileşen örneğinin ID'si |
-| `useFrontComponentExecutionContext(selector)` | değişir | Bir seçici işlevle tam yürütme bağlamına erişin |
-
-## Host iletişim API'si
-
-Ön uç bileşenleri, `twenty-sdk`'deki işlevleri kullanarak gezinmeyi, modalları ve bildirimleri tetikleyebilir:
-
-| Fonksiyon | Açıklama |
-| ----------------------------------------------- | ---------------------------------- |
-| `navigate(to, params?, queryParams?, options?)` | Uygulamada bir sayfaya git |
-| `openSidePanelPage(params)` | Bir yan panel aç |
-| `closeSidePanel()` | Yan paneli kapat |
-| `openCommandConfirmationModal(params)` | Bir onay iletişim kutusu göster |
-| `enqueueSnackbar(params)` | Bir toast bildirimi göster |
-| `unmountFrontComponent()` | Bileşeni kaldır (unmount) |
-| `updateProgress(progress)` | Bir ilerleme göstergesini güncelle |
-
-Bir eylem tamamlandıktan sonra bir snackbar göstermek ve yan paneli kapatmak için host API'sini kullanan bir örnek:
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### Birden çok kayıtla çalışma
-
-Birden çok seçili kaydı yönetmek için `useSelectedRecordIds()` kullanın. Bu, toplu işlemler için kullanışlıdır:
-
-```tsx src/front-components/bulk-export.tsx
-import { defineFrontComponent, numberOfSelectedRecords } from 'twenty-sdk/define';
-import { useSelectedRecordIds } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const BulkExport = () => {
- const selectedRecordIds = useSelectedRecordIds();
-
- const handleExport = async () => {
- const client = new CoreApiClient();
-
- for (const recordId of selectedRecordIds) {
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { exported: true } },
- id: true,
- },
- });
- }
-
- await enqueueSnackbar({
- message: `Exported ${selectedRecordIds.length} records`,
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- Archive this record?
- -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
- name: 'bulk-export',
- description: 'Export selected records',
- component: BulkExport,
- command: {
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
- label: 'Bulk Export',
- availabilityType: 'RECORD_SELECTION',
- conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
- },
-});
-```
-
-## defineCommandMenuItem
-
-Bir ön uç bileşenini komut menüsüne (Cmd+K) kaydetmek için `defineCommandMenuItem` kullanın. `isPinned` `true` ise, sayfanın sağ üst köşesinde bir hızlı işlem düğmesi olarak da görünür.
-
-```ts src/command-menu-items/open-dashboard.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- label: 'Open Dashboard',
- shortLabel: 'Dashboard',
- icon: 'IconLayoutDashboard',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-| Alan | Zorunlu | Açıklama |
-| --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `universalIdentifier` | Evet | Komut için kalıcı benzersiz kimlik |
-| `label` | Evet | Komut menüsünde (Cmd+K) gösterilen tam etiket |
-| `frontComponentUniversalIdentifier` | Evet | Bu komutun açtığı ön uç bileşeninin `universalIdentifier` değeri |
-| `shortLabel` | Hayır | Sabitlenmiş hızlı işlem düğmesinde görüntülenen daha kısa etiket |
-| `icon` | Hayır | Etiketin yanında görüntülenen simge adı (örn. `'IconBolt'`, `'IconSend'`) |
-| `isPinned` | Hayır | `true` olduğunda, komutu sayfanın sağ üst köşesinde bir hızlı işlem düğmesi olarak gösterir |
-| `availabilityType` | Hayır | Komutun nerede görüneceğini kontrol eder: `'GLOBAL'` (her zaman kullanılabilir), `'RECORD_SELECTION'` (yalnızca kayıtlar seçiliyken) veya `'FALLBACK'` (başka hiçbir komut eşleşmediğinde gösterilir) |
-| `availabilityObjectUniversalIdentifier` | Hayır | Komutu belirli bir nesne türünün sayfalarıyla sınırlandırın (örn. yalnızca Company kayıtlarında) |
-| `conditionalAvailabilityExpression` | Hayır | Komutun görünür olup olmadığını dinamik olarak kontrol eden bir boolean ifade (aşağıya bakın) |
-
-## Koşullu kullanılabilirlik ifadeleri
-
-`conditionalAvailabilityExpression` alanı, geçerli sayfa bağlamına göre bir komutun ne zaman görünür olacağını kontrol etmenizi sağlar. İfadeler oluşturmak için `twenty-sdk`'den türlendirilmiş değişkenleri ve operatörleri içe aktarın:
-
-```ts src/command-menu-items/bulk-update.command-menu-item.ts
-import {
- defineCommandMenuItem,
- objectPermissions,
- everyEquals,
-} from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: '...',
- label: 'Bulk Update',
- availabilityType: 'RECORD_SELECTION',
- frontComponentUniversalIdentifier: '...',
- conditionalAvailabilityExpression: everyEquals(
- objectPermissions,
- 'canUpdateObjectRecords',
- true,
- ),
-});
-```
-
-**Bağlam değişkenleri** — bunlar sayfanın mevcut durumunu temsil eder:
-
-| Değişken | Tür | Açıklama |
-| ------------------------------ | --------- | ----------------------------------------------------------------- |
-| `pageType` | `string` | Geçerli sayfa türü (örn. `'RecordIndexPage'`, `'RecordShowPage'`) |
-| `isInSidePanel` | `boolean` | Bileşenin bir yan panelde oluşturulup oluşturulmadığı |
-| `numberOfSelectedRecords` | `number` | Şu anda seçili kayıt sayısı |
-| `isSelectAll` | `boolean` | "tümünü seç" seçeneğinin etkin olup olmadığı |
-| `selectedRecords` | `array` | Seçili kayıt nesneleri |
-| `favoriteRecordIds` | `array` | Favorilere eklenen kayıtların ID'leri |
-| `objectPermissions` | `object` | Geçerli nesne türü için izinler |
-| `targetObjectReadPermissions` | `object` | Hedef nesne için okuma izinleri |
-| `targetObjectWritePermissions` | `object` | Hedef nesne için yazma izinleri |
-| `featureFlags` | `object` | Etkin özellik bayrakları |
-| `objectMetadataItem` | `object` | Geçerli nesne türünün üst verileri |
-| `hasAnySoftDeleteFilterOnView` | `boolean` | Geçerli görünümde soft-delete filtresi olup olmadığı |
-
-**Operatörler** — değişkenleri boolean ifadelere dönüştürmek için birleştirin:
-
-| Operatör | Açıklama |
-| ----------------------------------- | --------------------------------------------------------- |
-| `isDefined(value)` | Değer null/undefined değilse `true` |
-| `isNonEmptyString(value)` | Değer boş olmayan bir string ise `true` |
-| `includes(array, value)` | Dizi değeri içeriyorsa `true` |
-| `includesEvery(array, prop, value)` | Her bir öğenin özelliği değeri içeriyorsa `true` |
-| `every(array, prop)` | Özellik her öğede truthy ise `true` |
-| `everyDefined(array, prop)` | Özellik her öğede tanımlıysa `true` |
-| `everyEquals(array, prop, value)` | Özellik her öğede değere eşitse `true` |
-| `some(array, prop)` | Özellik en az bir öğede truthy ise `true` |
-| `someDefined(array, prop)` | Özellik en az bir öğede tanımlıysa `true` |
-| `someEquals(array, prop, value)` | Özellik en az bir öğede değere eşitse `true` |
-| `someNonEmptyString(array, prop)` | Özellik en az bir öğede boş olmayan bir string ise `true` |
-| `none(array, prop)` | Özellik her öğede falsy ise `true` |
-| `noneDefined(array, prop)` | Özellik her öğede tanımsızsa `true` |
-| `noneEquals(array, prop, value)` | Özellik hiçbir öğede değere eşit değilse `true` |
-
-## Genel varlıklar
-
-Ön uç bileşenleri, `getPublicAssetUrl` kullanarak uygulamanın `public/` dizinindeki dosyalara erişebilir:
-
-```tsx
-import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
-
-const Logo = () => Export {selectedRecordIds.length} selected record(s)?
- -;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-Ayrıntılar için [genel varlıklar bölümüne](/l/tr/developers/extend/apps/cli-and-testing#public-assets-public-folder) bakın.
-
-## Stil
-
-Ön uç bileşenleri birden fazla biçimlendirme yaklaşımını destekler. Şunları kullanabilirsiniz:
-
-* **Satır içi stiller** — `style={{ color: 'red' }}`
-* **Twenty UI bileşenleri** — `twenty-sdk/ui` içinden içe aktarın (Button, Tag, Status, Chip, Avatar ve daha fazlası)
-* **Emotion** — `@emotion/react` ile CSS-in-JS
-* **Styled-components** — `styled.div` kalıpları
-* **Tailwind CSS** — yardımcı sınıflar
-* **React ile uyumlu herhangi bir CSS-in-JS kitaplığı**
-
-```tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index 51c3644a54..0000000000
--- a/packages/twenty-docs/l/tr/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,273 +0,0 @@
----
-title: Başlarken
-icon: rocket
-description: İlk Twenty uygulamanızı dakikalar içinde oluşturun.
----
-
-## Ön Gereksinimler
-
-* **Node.js 24+** — [Buradan indirin](https://nodejs.org/)
-* **Yarn 4** — Corepack aracılığıyla Node ile birlikte gelir. Etkinleştirin: `corepack enable`
-* **Docker** — [Buradan indirin](https://www.docker.com/products/docker-desktop/). Yerel bir Twenty sunucusunu çalıştırmak için gereklidir. Zaten başka bir yerde Twenty çalıştırıyorsanız atlayın.
-
-Bir Twenty uygulaması oluşturmanın üç aşaması vardır. İskelet oluşturucu bunları tek bir sorunsuz akış komutuna indirger, ancak her aşama ayrı bir kavramdır — bir şeyler başarısız olduğunda hangi aşamada olduğunuzu bilmek neyi düzeltmeniz gerektiğini söyler.
-
-| Aşama | Ne yaparsınız | Araç | Sonuç |
-| ---------------------------- | ------------------------------------------------- | ----------------------------- | ---------------------------------- |
-| **1. İskelet Oluşturma** | Uygulamanın kaynak kodunu oluşturun | `npx create-twenty-app` | Diskte bir TypeScript projesi |
-| **2. Bir sunucu çalıştırma** | Eşitleme yapacağınız bir Twenty sunucusu başlatın | Docker + `yarn twenty server` | Çalışan bir Twenty örneği |
-| **3. Eşitleme** | Kodunuzu sunucuya canlı olarak eşitleyin | `yarn twenty dev` | Değişiklikleriniz arayüzde görünür |
-
----
-
-## Aşama 1 — Projenizin iskeletini oluşturun
-
-Şablondan yeni bir uygulama oluşturun:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-Sizden bir ad ve açıklama istenir — varsayılanlar için **Enter** tuşuna basın. Bu, `my-twenty-app/` içinde bir başlangıç `application-config.ts`, varsayılan bir rol, bir CI iş akışı ve bir entegrasyon testi ile bir TypeScript projesi oluşturur.
-
-**Bu aşamadan sonra:** makinenizde uygulamanın kaynak kodu bulunur. Henüz çalışmıyor — bu, 2. Aşama.
-
----
-
-## Aşama 2 — Yerel bir Twenty sunucusu çalıştırın
-
-Uygulamanızın eşitleme yapacağı bir Twenty sunucusuna ihtiyacı vardır. Sunucu, Docker içinde yerel olarak çalışan tam bir Twenty örneğidir — UI, GraphQL API, PostgreSQL. Yerel kodunuz tanımlarını bu sunucuya yükler; bu da onların arayüzde görünmesini sağlar.
-
-İskelet oluşturucu sizin için bir tane başlatmayı teklif eder:
-
-> **Yerel bir Twenty örneği kurmak ister misiniz?**
-
-* **Evet (önerilir)** — `twentycrm/twenty-app-dev` Docker imajını çeker ve `2020` portunda başlatır. Önce Docker'ın çalıştığından emin olun.
-* **Hayır** — Zaten bağlanmak istediğiniz bir Twenty sunucunuz varsa bunu seçin. Bunu daha sonra `yarn twenty remote add` ile bağlayabilirsiniz.
-
-
-
-
-
-Sunucu çalışır duruma geldiğinde, oturum açmak için bir tarayıcı açılır. Önceden eklenmiş demo hesabını kullanın:
-
-* **E-posta:** `tim@apple.dev`
-* **Parola:** `tim@apple.dev`
-
-
-
-
-
-
-Sonraki ekranda **Authorize**'a tıklayın — bu işlem CLI'nin çalışma alanınıza erişmesine izin verir.
-
-
-
-
-
-
-Terminaliniz her şeyin kurulduğunu onaylayacaktır.
-
-
-
-
-
-
-**Bu aşamadan sonra:** [http://localhost:2020](http://localhost:2020) adresinde çalışan bir Twenty sunucunuz ve ona eşitleme yapmak için yetkilendirilmiş bir CLI'ınız olur.
-
-
-
-
-
-
-[http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) adresini açın. Uygulamanızı **Your Apps** altında görmelisiniz.
-
-
-
-
-
-
-**My twenty app**'e tıklayarak **application registration**'ı görüntüleyin — uygulamanızı tanımlayan (ad, tanımlayıcı, OAuth kimlik bilgileri, kaynak) sunucu düzeyinde bir kayıttır. Tek bir kayıt, aynı sunucudaki birden çok çalışma alanına kurulabilir.
-
-
-
-
-
-
-Çalışma alanındaki kurulumu görmek için **View installed app**'e tıklayın. **About** sekmesi sürümü ve yönetim seçeneklerini gösterir.
-
-
-
-
-
-
-**Bu aşamadan sonra:** canlı bir geliştirme döngünüz olur. `src/` içindeki herhangi bir dosyayı düzenleyin; arayüzde görünür.
-
-### CI ve betikler için tek seferlik eşitleme
-
-Tek bir derleme + eşitleme çalıştırıp çıkmak için `--once` parametresini geçin — aynı ardışık düzen, izleyici yok:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Komut | Davranış | Ne zaman kullanılmalı |
-| ------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `yarn twenty dev` | Her değişiklikte izler ve yeniden eşitler. Siz durdurana kadar çalışır. | Etkileşimli yerel geliştirme. |
-| `yarn twenty dev --once` | Tek derleme + eşitleme; başarıda `0`, başarısızlıkta `1` ile çıkar. | CI, pre-commit kancaları, AI ajanları, betiklenmiş iş akışları. |
-
-Her iki mod da geliştirme modunda bir sunucuya ve kimliği doğrulanmış bir uzak uca ihtiyaç duyar.
-
-
-Today is {format(new Date(), 'MMMM do, yyyy')}
; -}; - -export default defineFrontComponent({ - universalIdentifier: '...', - name: 'date-widget', - component: DateWidget, -}); -``` - -### 打包的工作原理 - -构建步骤使用 esbuild 为每个逻辑函数和每个前端组件生成一个自包含文件。 所有导入的包都会被内联到打包产物中。 - -**逻辑函数** 运行在 Node.js 环境中。 Node 内置模块（`fs`、`path`、`crypto`、`http` 等） 可用且无需安装。 - -**前端组件** 运行在 Web Worker 中。 Node 内置模块不可用——仅可使用浏览器 API 以及可在浏览器环境中运行的 npm 包。 - -两个环境都将 `twenty-client-sdk/core` 和 `twenty-client-sdk/metadata` 作为预置模块提供 — 这些模块不会被打包，而是在运行时由服务器解析。 - -## 测试你的应用 - -该 SDK 提供可编程的 API，使你可以在测试代码中构建、部署、安装和卸载你的应用。 结合 [Vitest](https://vitest.dev/) 和类型化 API 客户端，你可以编写集成测试，在真实的 Twenty 服务器上验证你的应用端到端运行是否正常。 - -### 设置 - -脚手架生成的应用已包含 Vitest。 如果你手动进行设置，请安装这些依赖： - -```bash filename="Terminal" -yarn add -D vitest vite-tsconfig-paths -``` - -在应用根目录下创建一个 `vitest.config.ts`： - -```ts vitest.config.ts -import tsconfigPaths from 'vite-tsconfig-paths'; -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - plugins: [ - tsconfigPaths({ - projects: ['tsconfig.spec.json'], - ignoreConfigErrors: true, - }), - ], - test: { - testTimeout: 120_000, - hookTimeout: 120_000, - include: ['src/**/*.integration-test.ts'], - setupFiles: ['src/__tests__/setup-test.ts'], - env: { - TWENTY_API_URL: 'http://localhost:2020', - TWENTY_API_KEY: 'your-api-key', - }, - }, -}); -``` - -创建一个设置文件，在测试运行前验证服务器可达： - -```ts src/__tests__/setup-test.ts -import * as fs from 'fs'; -import * as os from 'os'; -import * as path from 'path'; -import { beforeAll } from 'vitest'; - -const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020'; -const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test'); - -beforeAll(async () => { - // Verify the server is running - const response = await fetch(`${TWENTY_API_URL}/healthz`); - - if (!response.ok) { - throw new Error( - `Twenty server is not reachable at ${TWENTY_API_URL}. ` + - 'Start the server before running integration tests.', - ); - } - - // Write a temporary config for the SDK - fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true }); - - fs.writeFileSync( - path.join(TEST_CONFIG_DIR, 'config.json'), - JSON.stringify({ - remotes: { - local: { - apiUrl: process.env.TWENTY_API_URL, - apiKey: process.env.TWENTY_API_KEY, - }, - }, - defaultRemote: 'local', - }, null, 2), - ); -}); -``` - -### 可编程的 SDK API - -子路径 `twenty-sdk/cli` 导出了可直接在测试代码中调用的函数： - -| 函数 | 描述 | -| -------------- | ------------------ | -| `appBuild` | 构建应用，并可选地打包为 tar 包 | -| `appDeploy` | 将 tar 包上传到服务器 | -| `appInstall` | 在活动工作区安装该应用 | -| `appUninstall` | 从活动工作区卸载该应用 | - -每个函数都会返回一个结果对象，包含 `success: boolean`，以及 `data` 或 `error` 之一。 - -### 编写集成测试 - -下面是一个完整示例：构建、部署并安装该应用，然后验证它出现在工作区中： - -```ts src/__tests__/app-install.integration-test.ts -import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'; -import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'; -import { MetadataApiClient } from 'twenty-client-sdk/metadata'; -import { afterAll, beforeAll, describe, expect, it } from 'vitest'; - -const APP_PATH = process.cwd(); - -describe('App installation', () => { - beforeAll(async () => { - const buildResult = await appBuild({ - appPath: APP_PATH, - tarball: true, - onProgress: (message: string) => console.log(`[build] ${message}`), - }); - - if (!buildResult.success) { - throw new Error(`Build failed: ${buildResult.error?.message}`); - } - - const deployResult = await appDeploy({ - tarballPath: buildResult.data.tarballPath!, - onProgress: (message: string) => console.log(`[deploy] ${message}`), - }); - - if (!deployResult.success) { - throw new Error(`Deploy failed: ${deployResult.error?.message}`); - } - - const installResult = await appInstall({ appPath: APP_PATH }); - - if (!installResult.success) { - throw new Error(`Install failed: ${installResult.error?.message}`); - } - }); - - afterAll(async () => { - await appUninstall({ appPath: APP_PATH }); - }); - - it('should find the installed app in the workspace', async () => { - const metadataClient = new MetadataApiClient(); - - const result = await metadataClient.query({ - findManyApplications: { - id: true, - name: true, - universalIdentifier: true, - }, - }); - - const installedApp = result.findManyApplications.find( - (app: { universalIdentifier: string }) => - app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER, - ); - - expect(installedApp).toBeDefined(); - }); -}); -``` - -### 运行测试 - -确保你的本地 Twenty 服务器正在运行，然后： - -```bash filename="Terminal" -yarn test -``` - -或者在开发期间使用监听模式： - -```bash filename="Terminal" -yarn test:watch -``` - -### 类型检查 - -你也可以在不运行测试的情况下对应用进行类型检查： - -```bash filename="Terminal" -yarn twenty typecheck -``` - -这会运行 `tsc --noEmit` 并报告所有类型错误。 - -## CLI 参考 - -除了 `dev`、`build`、`add` 和 `typecheck` 外，CLI 还提供了用于执行函数、查看日志和管理应用安装的命令。 - -### 执行函数（`yarn twenty exec`） - -手动运行逻辑函数，而无需通过 HTTP、定时任务或数据库事件来触发： - -```bash filename="Terminal" -# Execute by function name -yarn twenty exec -n create-new-post-card - -# Execute by universalIdentifier -yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf - -# Pass a JSON payload -yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}' - -# Execute the post-install function -yarn twenty exec --postInstall -``` - -### 查看函数日志（`yarn twenty logs`） - -实时流式查看你的应用逻辑函数的执行日志： - -```bash filename="Terminal" -# Stream all function logs -yarn twenty logs - -# Filter by function name -yarn twenty logs -n create-new-post-card - -# Filter by universalIdentifier -yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -``` - -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
- name: 'hello-world',
- description: 'A simple front component',
- component: HelloWorld,
-});
-```
-
-```ts src/command-menu-items/hello-world.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
- shortLabel: 'Hello',
- label: 'Hello World',
- icon: 'IconBolt',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-使用 `yarn twenty dev` 同步后（或单次运行 `yarn twenty dev --once`），快速操作会出现在页面右上角：
-
-Hello from my app!
-This component renders inside Twenty.
-
-
-
-
-点击它以内联方式渲染该组件。
-
-## 配置字段
-
-| 字段 | 必填 | 描述 |
-| --------------------- | -- | ---------------------------- |
-| `universalIdentifier` | 是 | 该组件的稳定唯一 ID |
-| `component` | 是 | 一个 React 组件函数 |
-| `name` | 否 | 显示名称 |
-| `description` | 否 | 组件的功能描述 |
-| `isHeadless` | 否 | 如果组件没有可见的 UI，则设为 `true`（见下文） |
-
-## 在页面上放置前端组件
-
-除了命令之外，您还可以在**页面布局**中将其添加为小部件，从而将前端组件直接嵌入记录页面。 详情请参见[definePageLayout](/l/zh/developers/extend/apps/skills-and-agents#definepagelayout)部分。
-
-## 无头与非无头
-
-前端组件有两种由 `isHeadless` 选项控制的渲染模式：
-
-**非无头（默认）** — 该组件会渲染可见的 UI。 从命令菜单触发时，它会在侧边栏中打开。 当 `isHeadless` 为 `false` 或被省略时，这是默认行为。
-
-**无头 (`isHeadless: true`)** — 该组件会在后台以不可见的方式挂载。 它不会打开侧边栏。 无头组件旨在用于执行逻辑后自行卸载的操作——例如运行异步任务、导航到某个页面或显示确认模态框。 它们与下文介绍的 SDK Command 组件天然契合。
-
-```tsx src/front-components/sync-tracker.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, enqueueSnackbar } from 'twenty-sdk/front-component';
-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 会跳过为其渲染容器——布局中不会出现空白区域。 该组件仍可访问所有 hooks 和宿主通信 API。
-
-## SDK Command 组件
-
-`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` 从命令菜单运行一个操作：
-
-```tsx src/front-components/run-action.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
- name: 'record-info',
- component: RecordInfo,
-});
-```
-
-可用的 hooks：
-
-| 钩子 | 返回值 | 描述 |
-| --------------------------------------------- | ----------------- | ------------------------------------- |
-| `useUserId()` | `string` 或 `null` | 当前用户的 ID |
-| `useSelectedRecordIds()` | `字符串[]` | 所有已选择的记录 ID（如果未选择，则为空数组） |
-| `useRecordId()` | `string` 或 `null` | **已弃用。** 请改用 `useSelectedRecordIds()` |
-| `useFrontComponentId()` | `string` | 此组件实例的 ID |
-| `useFrontComponentExecutionContext(selector)` | 因情况而异 | 使用选择器函数访问完整的执行上下文 |
-
-## 宿主通信 API
-
-前端组件可以使用来自 `twenty-sdk` 的函数触发导航、模态框和通知：
-
-| 函数 | 描述 |
-| ----------------------------------------------- | ------------- |
-| `navigate(to, params?, queryParams?, options?)` | 在应用中导航到某个页面 |
-| `openSidePanelPage(params)` | 打开侧边栏 |
-| `closeSidePanel()` | 关闭侧边栏 |
-| `openCommandConfirmationModal(params)` | 显示确认对话框 |
-| `enqueueSnackbar(params)` | 显示一条 Toast 通知 |
-| `unmountFrontComponent()` | 卸载该组件 |
-| `updateProgress(progress)` | 更新进度指示器 |
-
-下面是一个示例，使用宿主 API 在操作完成后显示一条 snackbar 并关闭侧边栏：
-
-```tsx src/front-components/archive-record.tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const ArchiveRecord = () => {
- const recordId = useRecordId();
-
- const handleArchive = async () => {
- const client = new CoreApiClient();
-
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { status: 'ARCHIVED' } },
- id: true,
- },
- });
-
- await enqueueSnackbar({
- message: 'Record archived',
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- User: {userId}
-Record: {recordId ?? 'No record context'}
-Component: {componentId}
-
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
- name: 'archive-record',
- description: 'Archives the current record',
- component: ArchiveRecord,
-});
-```
-
-### 处理多个记录
-
-使用 `useSelectedRecordIds()` 来处理多个已选记录。 这对于批量操作很有用：
-
-```tsx src/front-components/bulk-export.tsx
-import { defineFrontComponent, numberOfSelectedRecords } from 'twenty-sdk/define';
-import { useSelectedRecordIds } from 'twenty-sdk/front-component';
-import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-sdk/clients';
-
-const BulkExport = () => {
- const selectedRecordIds = useSelectedRecordIds();
-
- const handleExport = async () => {
- const client = new CoreApiClient();
-
- for (const recordId of selectedRecordIds) {
- await client.mutation({
- updateTask: {
- __args: { id: recordId, data: { exported: true } },
- id: true,
- },
- });
- }
-
- await enqueueSnackbar({
- message: `Exported ${selectedRecordIds.length} records`,
- variant: 'success',
- });
-
- await closeSidePanel();
- };
-
- return (
- Archive this record?
- -
-
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
- name: 'bulk-export',
- description: 'Export selected records',
- component: BulkExport,
- command: {
- universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
- label: 'Bulk Export',
- availabilityType: 'RECORD_SELECTION',
- conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
- },
-});
-```
-
-## defineCommandMenuItem
-
-使用 `defineCommandMenuItem` 在命令菜单（Cmd+K）中注册一个前端组件。 如果 `isPinned` 为 `true`，它还会显示为页面右上角的快速操作按钮。
-
-```ts src/command-menu-items/open-dashboard.command-menu-item.ts
-import { defineCommandMenuItem } from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
- label: 'Open Dashboard',
- shortLabel: 'Dashboard',
- icon: 'IconLayoutDashboard',
- isPinned: true,
- availabilityType: 'GLOBAL',
- frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
-});
-```
-
-| 字段 | 必填 | 描述 |
-| --------------------------------------- | -- | -------------------------------------------------------------------------------- |
-| `universalIdentifier` | 是 | 该命令的稳定唯一 ID |
-| `label` | 是 | 在命令菜单（Cmd+K）中显示的完整标签 |
-| `frontComponentUniversalIdentifier` | 是 | 此命令打开的前端组件的 `universalIdentifier` |
-| `shortLabel` | 否 | 固定的快速操作按钮上显示的较短标签 |
-| `icon` | 否 | 显示在标签旁边的图标名称（例如 `'IconBolt'`、`'IconSend'`） |
-| `isPinned` | 否 | 为 `true` 时，会将该命令显示为页面右上角的快速操作按钮 |
-| `availabilityType` | 否 | 控制命令出现的位置：'GLOBAL'（始终可用）、'RECORD_SELECTION'（仅在选择了记录时），或 'FALLBACK'（当没有其他命令匹配时显示） |
-| `availabilityObjectUniversalIdentifier` | 否 | 将该命令限制在特定对象类型的页面上（例如仅在 Company 记录上） |
-| `conditionalAvailabilityExpression` | 否 | 用于动态控制命令是否可见的布尔表达式（见下文） |
-
-## 条件可用性表达式
-
-通过 `conditionalAvailabilityExpression` 字段，您可以基于当前页面上下文控制命令何时可见。 从 `twenty-sdk` 导入带类型的变量和运算符来构建表达式：
-
-```ts src/command-menu-items/bulk-update.command-menu-item.ts
-import {
- defineCommandMenuItem,
- objectPermissions,
- everyEquals,
-} from 'twenty-sdk/define';
-
-export default defineCommandMenuItem({
- universalIdentifier: '...',
- label: 'Bulk Update',
- availabilityType: 'RECORD_SELECTION',
- frontComponentUniversalIdentifier: '...',
- conditionalAvailabilityExpression: everyEquals(
- objectPermissions,
- 'canUpdateObjectRecords',
- true,
- ),
-});
-```
-
-**上下文变量** — 表示页面的当前状态：
-
-| 变量 | 类型 | 描述 |
-| ------------------------------ | --------- | --------------------------------------------- |
-| `pageType` | `string` | 当前页面类型（例如 'RecordIndexPage'、'RecordShowPage'） |
-| `isInSidePanel` | `boolean` | 组件是否在侧边栏中渲染 |
-| `numberOfSelectedRecords` | `number` | 当前选中的记录数量 |
-| `isSelectAll` | `boolean` | “全选”是否已激活 |
-| `selectedRecords` | `array` | 已选记录对象 |
-| `favoriteRecordIds` | `array` | 已收藏记录的 ID |
-| `objectPermissions` | `object` | 当前对象类型的权限 |
-| `targetObjectReadPermissions` | `object` | 目标对象的读取权限 |
-| `targetObjectWritePermissions` | `object` | 目标对象的写入权限 |
-| `featureFlags` | `object` | 当前启用的功能标志 |
-| `objectMetadataItem` | `object` | 当前对象类型的元数据 |
-| `hasAnySoftDeleteFilterOnView` | `boolean` | 当前视图是否包含软删除筛选器 |
-
-**运算符** — 将变量组合为布尔表达式：
-
-| 运算符 | 描述 |
-| ----------------------------------- | -------------------------------- |
-| `isDefined(value)` | 当该值不是 null/undefined 时为 `true` |
-| `isNonEmptyString(value)` | 当该值为非空字符串时为 `true` |
-| `includes(array, value)` | 当数组包含该值时为 `true` |
-| `includesEvery(array, prop, value)` | 当每个条目的属性都包含该值时为 `true` |
-| `every(array, prop)` | 当该属性在每个条目上都为 truthy 时为 `true` |
-| `everyDefined(array, prop)` | 当该属性在每个条目上都已定义时为 `true` |
-| `everyEquals(array, prop, value)` | 当该属性在每个条目上都等于该值时为 `true` |
-| `some(array, prop)` | 当至少一个条目上的该属性为 truthy 时为 `true` |
-| `someDefined(array, prop)` | 当至少一个条目上的该属性已定义时为 `true` |
-| `someEquals(array, prop, value)` | 当至少一个条目上的该属性等于该值时为 `true` |
-| `someNonEmptyString(array, prop)` | 当至少一个条目上的该属性为非空字符串时为 `true` |
-| `none(array, prop)` | 当该属性在每个条目上都为 falsy 时为 `true` |
-| `noneDefined(array, prop)` | 当该属性在每个条目上都为 undefined 时为 `true` |
-| `noneEquals(array, prop, value)` | 当该属性在任意条目上都不等于该值时为 `true` |
-
-## 公共资源
-
-前端组件可以使用 `getPublicAssetUrl` 访问应用的 `public/` 目录中的文件：
-
-```tsx
-import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
-
-const Logo = () => Export {selectedRecordIds.length} selected record(s)?
- -;
-
-export default defineFrontComponent({
- universalIdentifier: '...',
- name: 'logo',
- component: Logo,
-});
-```
-
-详情请参见[公共资源部分](/l/zh/developers/extend/apps/cli-and-testing#public-assets-public-folder)。
-
-## 样式
-
-前端组件支持多种样式方案。 您可以使用：
-
-* **内联样式** — `style={{ color: 'red' }}`
-* **Twenty UI 组件** — 从 `twenty-sdk/ui` 导入（Button、Tag、Status、Chip、Avatar 等）
-* **Emotion** — 使用 `@emotion/react` 的 CSS-in-JS
-* **Styled-components** — `styled.div` 模式
-* **Tailwind CSS** — 工具类
-* **任何 CSS-in-JS 库**（与 React 兼容）
-
-```tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
-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,
-});
-```
diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/getting-started.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/getting-started.mdx
deleted file mode 100644
index e0d7bd402b..0000000000
--- a/packages/twenty-docs/l/zh/developers/extend/apps/getting-started.mdx
+++ /dev/null
@@ -1,273 +0,0 @@
----
-title: 开始使用
-icon: rocket
-description: 几分钟内创建你的第一个 Twenty 应用。
----
-
-## 先决条件
-
-* **Node.js 24+** — [在此下载](https://nodejs.org/)
-* **Yarn 4** — 通过 Corepack 随 Node.js 提供。 启用它：`corepack enable`
-* **Docker** — [在此下载](https://www.docker.com/products/docker-desktop/)。 运行本地 Twenty 服务器所需。 如果你已经在其他地方运行了 Twenty，请跳过。
-
-构建一个 Twenty 应用包含三个阶段。 脚手架工具将它们合并为一个理想路径的命令，但每个阶段都是独立的概念——当出现问题时，知道自己处于哪个阶段可以指明需要修复什么。
-
-| 阶段 | 你要做什么 | 工具 | 结果 |
-| ------------ | -------------------- | ----------------------------- | -------------------- |
-| **1. 脚手架** | 生成应用的源代码 | `npx create-twenty-app` | 磁盘上的一个 TypeScript 项目 |
-| **2. 运行服务器** | 启动一个 Twenty 服务器以进行同步 | Docker + `yarn twenty server` | 一个正在运行的 Twenty 实例 |
-| **3. 同步** | 将你的代码实时同步到服务器 | `yarn twenty dev` | 你的更改会出现在 UI 中 |
-
----
-
-## 阶段 1 — 搭建项目脚手架
-
-从模板创建一个新应用：
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-系统会提示你输入名称和描述——按下 **Enter** 采用默认值。 这将在 `my-twenty-app/` 中生成一个 TypeScript 项目，包含一个入门版的 `application-config.ts`、一个默认角色、一个 CI 工作流，以及一个集成测试。
-
-**完成此阶段后：** 你的机器上已有该应用的源代码。 它还未运行——那是第 2 阶段的内容。
-
----
-
-## 阶段 2 — 运行本地 Twenty 服务器
-
-你的应用需要一个 Twenty 服务器来进行同步。 该服务器是一个完整的 Twenty 实例——包含 UI、GraphQL API、PostgreSQL——在本地的 Docker 中运行。 你的本地代码会将其定义上传到该服务器，从而使其显示在 UI 中。
-
-脚手架工具会为你提供启动它的选项：
-
-> **是否要设置本地 Twenty 实例？**
-
-* **是（推荐）** — 将拉取 `twentycrm/twenty-app-dev` Docker 镜像，并在端口 `2020` 上启动它。 请先确保 Docker 正在运行。
-* **否** — 如果你已经有一个想要连接的 Twenty 服务器，请选择此项。 你可以稍后通过 `yarn twenty remote add` 将其连接起来。
-
-
-
-
-
-服务器启动后，浏览器会打开登录页面。 使用预置的演示账户：
-
-* **邮箱：** `tim@apple.dev`
-* **密码：** `tim@apple.dev`
-
-
-
-
-
-
-在下一屏点击 **Authorize** —— 这将授予 CLI 访问你工作区的权限。
-
-
-
-
-
-
-你的终端会确认一切已就绪。
-
-
-
-
-
-
-**完成此阶段后：** 你在 [http://localhost:2020](http://localhost:2020) 上拥有一个正在运行的 Twenty 服务器，且你的 CLI 已获授权可与其同步。
-
-
-
-
-
-
-打开 [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer)。 你应当在 **你的应用** 下看到你的应用。
-
-
-
-
-
-
-点击 **My twenty app** 查看其**应用注册**——一条用于描述你的应用（名称、标识符、OAuth 凭据、来源）的服务器级记录。 同一服务器上的多个工作区可以安装同一个注册项。
-
-
-
-
-
-
-点击 **查看已安装的应用** 以查看工作区安装项。 **关于** 选项卡显示版本和管理选项。
-
-
-
-
-
-
-**完成此阶段后：** 你拥有一个实时的开发循环。 编辑 `src/` 中的任意文件，更改会显示在 UI 中。
-
-### 用于 CI 和脚本的一次性同步
-
-传入 `--once` 以执行一次构建与同步后退出——相同的流水线，无文件监视器：
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| 命令 | 行为 | 适用场景 |
-| ------------------------ | -------------------------------- | ------------------------------ |
-| `yarn twenty dev` | 监视并在每次更改时重新同步。 持续运行，直到你将其停止。 | 交互式本地开发。 |
-| `yarn twenty dev --once` | 单次构建与同步，成功时以 `0` 退出，失败时以 `1` 退出。 | CI、pre-commit 钩子、AI 代理、脚本化工作流。 |
-
-两种模式都需要处于开发模式的服务器和已认证的远程。
-
-
-