+ 
+
+
+Once the server is up, a browser opens for sign-in. Use the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+ 
+
+
+Click **Authorize** on the next screen — this gives the CLI access to your workspace.
+
+
+
+ 
+
+
+Your terminal will confirm everything is set up.
+
+
+
+ 
+
+
+**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.
+
+
+
+ 
+
+
+Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
+
+
+
+ 
+
+
+Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
+
+
+
+ 
+
+
+Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
+
+
+
+ 
+
+
+**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.
+
+### One-shot sync for CI and scripts
+
+Pass `--once` to run a single build + sync and exit — same pipeline, no watcher:
+
+```bash filename="Terminal"
+yarn twenty dev --once
+```
+
+| Command | Behavior | When to use |
+| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
+| `yarn twenty dev --once` | Single build + sync, exits `0` on success, `1` on failure. | CI, pre-commit hooks, AI agents, scripted workflows. |
+
+Both modes need a server in development mode and an authenticated remote.
+
+
+
+
+ );
+};
+
+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',
+});
+```
+
+After syncing with `yarn twenty dev` (or running a one-shot `yarn twenty dev --once`), the quick action appears in the top-right corner of the page:
+
+Hello from my app!
+This component renders inside Twenty.
+
+ 
+
+
+Click it to render the component inline.
+
+## Configuration fields
+
+| Field | Required | Description |
+| --------------------- | -------- | ------------------------------------------------------------ |
+| `universalIdentifier` | Yes | Stable unique ID for this component |
+| `component` | Yes | A React component function |
+| `name` | No | Display name |
+| `description` | No | Description of what the component does |
+| `isHeadless` | No | Set to `true` if the component has no visible UI (see below) |
+
+## Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See [Page Layouts](/l/de/developers/extend/apps/layout/page-layouts) for details.
+
+## Headless vs non-headless
+
+Front components come in two rendering modes controlled by the `isHeadless` option:
+
+**Non-headless (default)** — The component renders a visible UI. When triggered from the command menu it opens in the side panel. This is the default behavior when `isHeadless` is `false` or omitted.
+
+**Headless (`isHeadless: true`)** — The component mounts invisibly in the background. It does not open the side panel. Headless components are designed for actions that execute logic and then unmount themselves — for example, running an async task, navigating to a page, or showing a confirmation modal. They pair naturally with the SDK Command components described below.
+
+```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,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+## SDK Command components
+
+The `twenty-sdk` package provides four Command helper components designed for headless front components. Each component executes an action on mount, handles errors by showing a snackbar notification, and automatically unmounts the front component when done.
+
+Import them from `twenty-sdk/command`:
+
+* **`Command`** — Runs an async callback via the `execute` prop.
+* **`CommandLink`** — Navigates to an app path. Props: `to`, `params`, `queryParams`, `options`.
+* **`CommandModal`** — Opens a confirmation modal. If the user confirms, executes the `execute` callback. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
+* **`CommandOpenSidePanelPage`** — Opens a specific side panel page. Props: `page`, `pageTitle`, `pageIcon`.
+
+Here is a full example of a headless front component using `Command` to run an action from the command menu:
+
+```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,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Description |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useSelectedRecordIds()` | `string[]` | All selected record IDs (empty array if none selected) |
+| `useRecordId()` | `string` or `null` | **Deprecated.** Use `useSelectedRecordIds()` instead |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | varies | Access the full execution context with a selector function |
+
+## Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Function | Description |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Close the side panel |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+Here is an example that uses the host API to show a snackbar and close the side panel after an action completes:
+
+```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,
+});
+```
+
+### Working with multiple records
+
+Use `useSelectedRecordIds()` to handle multiple selected records. This is useful for bulk operations:
+
+```tsx src/front-components/bulk-export.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds, numberOfSelectedRecords } 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,
+ },
+});
+```
+
+## Public assets
+
+Front components can access files from the app's `public/` directory using `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,
+});
+```
+
+See the [public assets section](/l/de/developers/extend/apps/config/public-assets) for details.
+
+## Styling
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/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/layout/navigation-menu-items.mdx b/packages/twenty-docs/l/de/developers/extend/apps/layout/navigation-menu-items.mdx
new file mode 100644
index 0000000000..bbfca36165
--- /dev/null
+++ b/packages/twenty-docs/l/de/developers/extend/apps/layout/navigation-menu-items.mdx
@@ -0,0 +1,44 @@
+---
+title: Navigation Menu Items
+description: Add custom entries to the workspace sidebar — links to saved views or external URLs.
+icon: Balken
+---
+
+A **navigation menu item** is an entry in the left sidebar. Use `defineNavigationMenuItem()` to ship custom sidebar links — typically one per [view](/l/de/developers/extend/apps/layout/views) you ship — or to point at external URLs.
+
+```ts src/navigation-menu-items/example-navigation-menu-item.ts
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
+
+export default defineNavigationMenuItem({
+ universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
+ name: 'example-navigation-menu-item',
+ icon: 'IconList',
+ color: 'blue',
+ position: 0,
+ type: NavigationMenuItemType.VIEW,
+ viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Hauptpunkte
+
+* `type` determines what the menu item links to. Each type pairs with a specific identifier field:
+
+ | Typ | Was es tut | Required field |
+ | ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- |
+ | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |
+ | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |
+ | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |
+ | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |
+ | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |
+
+* `position` controls ordering in the sidebar.
+
+* `icon` and `color` are optional and customize how the entry looks.
+
+* `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Setup + +The scaffolded app already includes Vitest. If you set it up manually, install the dependencies: + +```bash filename="Terminal" +yarn add -D vitest vite-tsconfig-paths +``` + +Create a `vitest.config.ts` at the root of your 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', + }, + }, +}); +``` + +Create a setup file that verifies the server is reachable before tests run: + +```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), + ); +}); +``` + +## Programmatic SDK APIs + +The `twenty-sdk/cli` subpath exports functions you can call directly from test code: + +| Function | Description | +| -------------- | ------------------------------------------- | +| `appBuild` | Build the app and optionally pack a tarball | +| `appDeploy` | Upload a tarball to the server | +| `appInstall` | Install the app on the active workspace | +| `appUninstall` | Uninstall the app from the active workspace | + +Each function returns a result object with `success: boolean` and either `data` or `error`. + +## Writing an integration test + +Here is a full example that builds, deploys, and installs the app, then verifies it appears in the workspace: + +```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(); + }); +}); +``` + +## Running tests + +Make sure your local Twenty server is running, then: + +```bash filename="Terminal" +yarn test +``` + +Or in watch mode during development: + +```bash filename="Terminal" +yarn test:watch +``` + +## Type checking + +You can also run type checking on your app without running tests: + +```bash filename="Terminal" +yarn twenty typecheck +``` + +This runs `tsc --noEmit` and reports any type errors. + +## CI with GitHub Actions + +The scaffolder generates a ready-to-use GitHub Actions workflow at `.github/workflows/ci.yml`. It runs your integration tests automatically on every push to `main` and on pull requests. + +The workflow: + +1. Checks out your code +2. Spins up a temporary Twenty server using the `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` action +3. Installs dependencies with `yarn install --immutable` +4. Runs `yarn test` with `TWENTY_API_URL` and `TWENTY_API_KEY` injected from the action outputs + +```yaml .github/workflows/ci.yml +name: CI + +on: + push: + branches: + - main + pull_request: {} + +env: + TWENTY_VERSION: latest + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Spawn Twenty instance + id: twenty + uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main + with: + twenty-version: ${{ env.TWENTY_VERSION }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Enable Corepack + run: corepack enable + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: '.nvmrc' + cache: 'yarn' + + - name: Install dependencies + run: yarn install --immutable + + - name: Run integration tests + run: yarn test + env: + TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }} + TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }} +``` + +You don't need to configure any secrets — the `spawn-twenty-docker-image` action starts an ephemeral Twenty server directly in the runner and outputs the connection details. The `GITHUB_TOKEN` secret is provided automatically by GitHub. + +To pin a specific Twenty version instead of `latest`, change the `TWENTY_VERSION` environment variable at the top of the workflow. diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/config/application.mdx new file mode 100644 index 0000000000..2684760e48 --- /dev/null +++ b/packages/twenty-docs/l/pt/developers/extend/apps/config/application.mdx @@ -0,0 +1,65 @@ +--- +title: Application Config +description: Declare your app's identity, default role, variables, and marketplace metadata with defineApplication. +icon: rocket +--- + +Every app must have exactly one `defineApplication` call. It declares: + +* **Identity** — universal identifier, display name, description. +* **Permissions** — which role its logic functions and front components run under. +* **Variables** *(optional)* — key–value pairs exposed to your code as environment variables. +* **Pre-install / post-install hooks** *(optional)* — see [Logic Functions](/l/pt/developers/extend/apps/logic/logic-functions). + +```ts src/application-config.ts +import { defineApplication } from 'twenty-sdk/define'; +import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role'; + +export default defineApplication({ + universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d', + displayName: 'My Twenty App', + description: 'My first Twenty app', + applicationVariables: { + DEFAULT_RECIPIENT_NAME: { + universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de', + description: 'Default recipient name for postcards', + value: 'Jane Doe', + isSecret: false, + }, + }, + defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER, +}); +``` + +Notes: + +* `universalIdentifier` fields are deterministic IDs you own. Generate them once and keep them stable across syncs. +* `applicationVariables` become environment variables for your functions and front components (e.g., `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`). +* `defaultRoleUniversalIdentifier` must reference a role defined with [`defineRole()`](/l/pt/developers/extend/apps/config/roles). +* Pre-install and post-install functions are detected automatically during the manifest build — you do not need to reference them in `defineApplication()`. + +## Default function role + +The `defaultRoleUniversalIdentifier` controls what the app's logic functions and front components can access: + +* The runtime token injected as `TWENTY_APP_ACCESS_TOKEN` is derived from this role. +* The typed API client is restricted to the permissions granted to that role. +* Follow least-privilege: declare only the permissions your functions need. + +When you scaffold a new app, the CLI creates a starter role file at `src/roles/default-role.ts`. See [Roles & Permissions](/l/pt/developers/extend/apps/config/roles) for the full reference. + +## Marketplace metadata + +If you plan to [publish your app](/l/pt/developers/extend/apps/operations/publishing), these optional fields control how it appears in the marketplace: + +| Field | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `author` | Author or company name | +| `category` | App category for marketplace filtering | +| `logoUrl` | Path to your app logo (e.g., `public/logo.png`) | +| `screenshots` | Array of screenshot paths (e.g., `public/screenshot-1.png`) | +| `aboutDescription` | Longer markdown description for the "About" tab. If omitted, the marketplace uses the package's `README.md` from npm | +| `websiteUrl` | Link to your website | +| `termsUrl` | Link to terms of service | +| `emailSupport` | Support email address | +| `issueReportUrl` | Link to issue tracker | diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/config/install-hooks.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/config/install-hooks.mdx new file mode 100644 index 0000000000..c2d4c0d2bc --- /dev/null +++ b/packages/twenty-docs/l/pt/developers/extend/apps/config/install-hooks.mdx @@ -0,0 +1,206 @@ +--- +title: Install Hooks +description: Run logic before or after the install — seed data, back up records, validate the upgrade. +icon: wrench +--- + +Install hooks are special logic functions that run during the install or upgrade lifecycle. They share the same handler runtime as regular [logic functions](/l/pt/developers/extend/apps/logic/logic-functions) and receive an `InstallPayload`, but they're declared with their own define functions — `definePostInstallLogicFunction()` and `definePreInstallLogicFunction()` — and live outside the normal trigger model (HTTP, cron, database events). + +Each app may define **at most one pre-install** and **at most one post-install** function. The manifest build will error if more than one of either is detected. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ install flow │ +│ │ +│ upload package → [pre-install] → metadata migration → │ +│ generate SDK → [post-install] │ +│ │ +│ old schema visible new schema visible │ +└─────────────────────────────────────────────────────────────┘ +``` + +
+
+
+
+Once the server is up, a browser opens for sign-in. Use the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+Click **Authorize** on the next screen — this gives the CLI access to your workspace.
+
+
+
+
+
+
+Your terminal will confirm everything is set up.
+
+
+
+
+
+
+**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.
+
+
+
+
+
+
+Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
+
+
+
+
+
+
+Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
+
+
+
+
+
+
+Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
+
+
+
+
+
+
+**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.
+
+### One-shot sync for CI and scripts
+
+Pass `--once` to run a single build + sync and exit — same pipeline, no watcher:
+
+```bash filename="Terminal"
+yarn twenty dev --once
+```
+
+| Command | Behavior | When to use |
+| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
+| `yarn twenty dev --once` | Single build + sync, exits `0` on success, `1` on failure. | CI, pre-commit hooks, AI agents, scripted workflows. |
+
+Both modes need a server in development mode and an authenticated remote.
+
+
+
+
+ );
+};
+
+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',
+});
+```
+
+After syncing with `yarn twenty dev` (or running a one-shot `yarn twenty dev --once`), the quick action appears in the top-right corner of the page:
+
+Hello from my app!
+This component renders inside Twenty.
+
+
+
+
+Click it to render the component inline.
+
+## Configuration fields
+
+| Field | Required | Description |
+| --------------------- | -------- | ------------------------------------------------------------ |
+| `universalIdentifier` | Yes | Stable unique ID for this component |
+| `component` | Yes | A React component function |
+| `name` | No | Display name |
+| `description` | No | Description of what the component does |
+| `isHeadless` | No | Set to `true` if the component has no visible UI (see below) |
+
+## Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See [Page Layouts](/l/pt/developers/extend/apps/layout/page-layouts) for details.
+
+## Headless vs non-headless
+
+Front components come in two rendering modes controlled by the `isHeadless` option:
+
+**Non-headless (default)** — The component renders a visible UI. When triggered from the command menu it opens in the side panel. This is the default behavior when `isHeadless` is `false` or omitted.
+
+**Headless (`isHeadless: true`)** — The component mounts invisibly in the background. It does not open the side panel. Headless components are designed for actions that execute logic and then unmount themselves — for example, running an async task, navigating to a page, or showing a confirmation modal. They pair naturally with the SDK Command components described below.
+
+```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,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+## SDK Command components
+
+The `twenty-sdk` package provides four Command helper components designed for headless front components. Each component executes an action on mount, handles errors by showing a snackbar notification, and automatically unmounts the front component when done.
+
+Import them from `twenty-sdk/command`:
+
+* **`Command`** — Runs an async callback via the `execute` prop.
+* **`CommandLink`** — Navigates to an app path. Props: `to`, `params`, `queryParams`, `options`.
+* **`CommandModal`** — Opens a confirmation modal. If the user confirms, executes the `execute` callback. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
+* **`CommandOpenSidePanelPage`** — Opens a specific side panel page. Props: `page`, `pageTitle`, `pageIcon`.
+
+Here is a full example of a headless front component using `Command` to run an action from the command menu:
+
+```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,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Description |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useSelectedRecordIds()` | `string[]` | All selected record IDs (empty array if none selected) |
+| `useRecordId()` | `string` or `null` | **Deprecated.** Use `useSelectedRecordIds()` instead |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | varies | Access the full execution context with a selector function |
+
+## Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Function | Description |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Close the side panel |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+Here is an example that uses the host API to show a snackbar and close the side panel after an action completes:
+
+```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,
+});
+```
+
+### Working with multiple records
+
+Use `useSelectedRecordIds()` to handle multiple selected records. This is useful for bulk operations:
+
+```tsx src/front-components/bulk-export.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds, numberOfSelectedRecords } 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,
+ },
+});
+```
+
+## Public assets
+
+Front components can access files from the app's `public/` directory using `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,
+});
+```
+
+See the [public assets section](/l/pt/developers/extend/apps/config/public-assets) for details.
+
+## Styling
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/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/layout/navigation-menu-items.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/layout/navigation-menu-items.mdx
new file mode 100644
index 0000000000..6946751826
--- /dev/null
+++ b/packages/twenty-docs/l/pt/developers/extend/apps/layout/navigation-menu-items.mdx
@@ -0,0 +1,44 @@
+---
+title: Navigation Menu Items
+description: Add custom entries to the workspace sidebar — links to saved views or external URLs.
+icon: bars
+---
+
+A **navigation menu item** is an entry in the left sidebar. Use `defineNavigationMenuItem()` to ship custom sidebar links — typically one per [view](/l/pt/developers/extend/apps/layout/views) you ship — or to point at external URLs.
+
+```ts src/navigation-menu-items/example-navigation-menu-item.ts
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
+
+export default defineNavigationMenuItem({
+ universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
+ name: 'example-navigation-menu-item',
+ icon: 'IconList',
+ color: 'blue',
+ position: 0,
+ type: NavigationMenuItemType.VIEW,
+ viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Pontos-chave
+
+* `type` determines what the menu item links to. Each type pairs with a specific identifier field:
+
+ | Tipo | O que faz | Required field |
+ | ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- |
+ | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |
+ | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |
+ | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |
+ | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |
+ | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |
+
+* `position` controls ordering in the sidebar.
+
+* `icon` and `color` are optional and customize how the entry looks.
+
+* `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Setup + +The scaffolded app already includes Vitest. If you set it up manually, install the dependencies: + +```bash filename="Terminal" +yarn add -D vitest vite-tsconfig-paths +``` + +Create a `vitest.config.ts` at the root of your 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', + }, + }, +}); +``` + +Create a setup file that verifies the server is reachable before tests run: + +```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), + ); +}); +``` + +## Programmatic SDK APIs + +The `twenty-sdk/cli` subpath exports functions you can call directly from test code: + +| Function | Description | +| -------------- | ------------------------------------------- | +| `appBuild` | Build the app and optionally pack a tarball | +| `appDeploy` | Upload a tarball to the server | +| `appInstall` | Install the app on the active workspace | +| `appUninstall` | Uninstall the app from the active workspace | + +Each function returns a result object with `success: boolean` and either `data` or `error`. + +## Writing an integration test + +Here is a full example that builds, deploys, and installs the app, then verifies it appears in the workspace: + +```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(); + }); +}); +``` + +## Running tests + +Make sure your local Twenty server is running, then: + +```bash filename="Terminal" +yarn test +``` + +Or in watch mode during development: + +```bash filename="Terminal" +yarn test:watch +``` + +## Type checking + +You can also run type checking on your app without running tests: + +```bash filename="Terminal" +yarn twenty typecheck +``` + +This runs `tsc --noEmit` and reports any type errors. + +## CI with GitHub Actions + +The scaffolder generates a ready-to-use GitHub Actions workflow at `.github/workflows/ci.yml`. It runs your integration tests automatically on every push to `main` and on pull requests. + +The workflow: + +1. Checks out your code +2. Spins up a temporary Twenty server using the `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` action +3. Installs dependencies with `yarn install --immutable` +4. Runs `yarn test` with `TWENTY_API_URL` and `TWENTY_API_KEY` injected from the action outputs + +```yaml .github/workflows/ci.yml +name: CI + +on: + push: + branches: + - main + pull_request: {} + +env: + TWENTY_VERSION: latest + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Spawn Twenty instance + id: twenty + uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main + with: + twenty-version: ${{ env.TWENTY_VERSION }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Enable Corepack + run: corepack enable + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: '.nvmrc' + cache: 'yarn' + + - name: Install dependencies + run: yarn install --immutable + + - name: Run integration tests + run: yarn test + env: + TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }} + TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }} +``` + +You don't need to configure any secrets — the `spawn-twenty-docker-image` action starts an ephemeral Twenty server directly in the runner and outputs the connection details. The `GITHUB_TOKEN` secret is provided automatically by GitHub. + +To pin a specific Twenty version instead of `latest`, change the `TWENTY_VERSION` environment variable at the top of the workflow. diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/config/application.mdx new file mode 100644 index 0000000000..92393ec357 --- /dev/null +++ b/packages/twenty-docs/l/ro/developers/extend/apps/config/application.mdx @@ -0,0 +1,65 @@ +--- +title: Application Config +description: Declare your app's identity, default role, variables, and marketplace metadata with defineApplication. +icon: rocket +--- + +Every app must have exactly one `defineApplication` call. It declares: + +* **Identity** — universal identifier, display name, description. +* **Permissions** — which role its logic functions and front components run under. +* **Variables** *(optional)* — key–value pairs exposed to your code as environment variables. +* **Pre-install / post-install hooks** *(optional)* — see [Logic Functions](/l/ro/developers/extend/apps/logic/logic-functions). + +```ts src/application-config.ts +import { defineApplication } from 'twenty-sdk/define'; +import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role'; + +export default defineApplication({ + universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d', + displayName: 'My Twenty App', + description: 'My first Twenty app', + applicationVariables: { + DEFAULT_RECIPIENT_NAME: { + universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de', + description: 'Default recipient name for postcards', + value: 'Jane Doe', + isSecret: false, + }, + }, + defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER, +}); +``` + +Notes: + +* `universalIdentifier` fields are deterministic IDs you own. Generate them once and keep them stable across syncs. +* `applicationVariables` become environment variables for your functions and front components (e.g., `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`). +* `defaultRoleUniversalIdentifier` must reference a role defined with [`defineRole()`](/l/ro/developers/extend/apps/config/roles). +* Pre-install and post-install functions are detected automatically during the manifest build — you do not need to reference them in `defineApplication()`. + +## Default function role + +The `defaultRoleUniversalIdentifier` controls what the app's logic functions and front components can access: + +* The runtime token injected as `TWENTY_APP_ACCESS_TOKEN` is derived from this role. +* The typed API client is restricted to the permissions granted to that role. +* Follow least-privilege: declare only the permissions your functions need. + +When you scaffold a new app, the CLI creates a starter role file at `src/roles/default-role.ts`. See [Roles & Permissions](/l/ro/developers/extend/apps/config/roles) for the full reference. + +## Marketplace metadata + +If you plan to [publish your app](/l/ro/developers/extend/apps/operations/publishing), these optional fields control how it appears in the marketplace: + +| Field | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `author` | Author or company name | +| `category` | App category for marketplace filtering | +| `logoUrl` | Path to your app logo (e.g., `public/logo.png`) | +| `screenshots` | Array of screenshot paths (e.g., `public/screenshot-1.png`) | +| `aboutDescription` | Longer markdown description for the "About" tab. If omitted, the marketplace uses the package's `README.md` from npm | +| `websiteUrl` | Link to your website | +| `termsUrl` | Link to terms of service | +| `emailSupport` | Support email address | +| `issueReportUrl` | Link to issue tracker | diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/config/install-hooks.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/config/install-hooks.mdx new file mode 100644 index 0000000000..1c7eaa0011 --- /dev/null +++ b/packages/twenty-docs/l/ro/developers/extend/apps/config/install-hooks.mdx @@ -0,0 +1,206 @@ +--- +title: Install Hooks +description: Run logic before or after the install — seed data, back up records, validate the upgrade. +icon: wrench +--- + +Install hooks are special logic functions that run during the install or upgrade lifecycle. They share the same handler runtime as regular [logic functions](/l/ro/developers/extend/apps/logic/logic-functions) and receive an `InstallPayload`, but they're declared with their own define functions — `definePostInstallLogicFunction()` and `definePreInstallLogicFunction()` — and live outside the normal trigger model (HTTP, cron, database events). + +Each app may define **at most one pre-install** and **at most one post-install** function. The manifest build will error if more than one of either is detected. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ install flow │ +│ │ +│ upload package → [pre-install] → metadata migration → │ +│ generate SDK → [post-install] │ +│ │ +│ old schema visible new schema visible │ +└─────────────────────────────────────────────────────────────┘ +``` + +
+
+
+
+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 | When to use |
+| ------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `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.
+
+
+
+
+ );
+};
+
+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ă**. See [Page Layouts](/l/ro/developers/extend/apps/layout/page-layouts) for details.
+
+## 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 } from 'twenty-sdk/define';
+import { useSelectedRecordIds, numberOfSelectedRecords } 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,
+ },
+});
+```
+
+## 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/config/public-assets) 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/layout/navigation-menu-items.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/layout/navigation-menu-items.mdx
new file mode 100644
index 0000000000..d1491a9301
--- /dev/null
+++ b/packages/twenty-docs/l/ro/developers/extend/apps/layout/navigation-menu-items.mdx
@@ -0,0 +1,44 @@
+---
+title: Navigation Menu Items
+description: Add custom entries to the workspace sidebar — links to saved views or external URLs.
+icon: bars
+---
+
+A **navigation menu item** is an entry in the left sidebar. Use `defineNavigationMenuItem()` to ship custom sidebar links — typically one per [view](/l/ro/developers/extend/apps/layout/views) you ship — or to point at external URLs.
+
+```ts src/navigation-menu-items/example-navigation-menu-item.ts
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
+
+export default defineNavigationMenuItem({
+ universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
+ name: 'example-navigation-menu-item',
+ icon: 'IconList',
+ color: 'blue',
+ position: 0,
+ type: NavigationMenuItemType.VIEW,
+ viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Puncte cheie
+
+* `type` determines what the menu item links to. Each type pairs with a specific identifier field:
+
+ | Tip | Ce face | Required field |
+ | ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- |
+ | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |
+ | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |
+ | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |
+ | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |
+ | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |
+
+* `position` controls ordering in the sidebar.
+
+* `icon` and `color` are optional and customize how the entry looks.
+
+* `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.
+
+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. + +## 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. + +## CI cu GitHub Actions + +Scaffolderul generează un workflow GitHub Actions gata de utilizare în `.github/workflows/ci.yml`. Rulează automat testele de integrare la fiecare push pe `main` și la pull request-uri. + +Workflow-ul: + +1. Preia codul +2. Pornește un server Twenty temporar folosind acțiunea `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` +3. Instalează dependențele cu `yarn install --immutable` +4. Rulează `yarn test` cu `TWENTY_API_URL` și `TWENTY_API_KEY` injectate din rezultatele acțiunii + +```yaml .github/workflows/ci.yml +name: CI + +on: + push: + branches: + - main + pull_request: {} + +env: + TWENTY_VERSION: latest + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Spawn Twenty instance + id: twenty + uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main + with: + twenty-version: ${{ env.TWENTY_VERSION }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Enable Corepack + run: corepack enable + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: '.nvmrc' + cache: 'yarn' + + - name: Install dependencies + run: yarn install --immutable + + - name: Run integration tests + run: yarn test + env: + TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }} + TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }} +``` + +Nu trebuie să configurați niciun secret — acțiunea `spawn-twenty-docker-image` pornește un server Twenty efemer direct în runner și oferă detaliile de conectare. Secretul `GITHUB_TOKEN` este furnizat automat de GitHub. + +Pentru a fixa o versiune Twenty specifică în loc de `latest`, modificați variabila de mediu `TWENTY_VERSION` din partea de sus a workflow-ului. diff --git a/packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdx new file mode 100644 index 0000000000..46af2e8c9d --- /dev/null +++ b/packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdx @@ -0,0 +1,65 @@ +--- +title: Application Config +description: Declare your app's identity, default role, variables, and marketplace metadata with defineApplication. +icon: rocket +--- + +Every app must have exactly one `defineApplication` call. It declares: + +* **Identity** — universal identifier, display name, description. +* **Permissions** — which role its logic functions and front components run under. +* **Variables** *(optional)* — key–value pairs exposed to your code as environment variables. +* **Pre-install / post-install hooks** *(optional)* — see [Logic Functions](/l/ru/developers/extend/apps/logic/logic-functions). + +```ts src/application-config.ts +import { defineApplication } from 'twenty-sdk/define'; +import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role'; + +export default defineApplication({ + universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d', + displayName: 'My Twenty App', + description: 'My first Twenty app', + applicationVariables: { + DEFAULT_RECIPIENT_NAME: { + universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de', + description: 'Default recipient name for postcards', + value: 'Jane Doe', + isSecret: false, + }, + }, + defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER, +}); +``` + +Notes: + +* `universalIdentifier` fields are deterministic IDs you own. Generate them once and keep them stable across syncs. +* `applicationVariables` become environment variables for your functions and front components (e.g., `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`). +* `defaultRoleUniversalIdentifier` must reference a role defined with [`defineRole()`](/l/ru/developers/extend/apps/config/roles). +* Pre-install and post-install functions are detected automatically during the manifest build — you do not need to reference them in `defineApplication()`. + +## Default function role + +The `defaultRoleUniversalIdentifier` controls what the app's logic functions and front components can access: + +* The runtime token injected as `TWENTY_APP_ACCESS_TOKEN` is derived from this role. +* The typed API client is restricted to the permissions granted to that role. +* Follow least-privilege: declare only the permissions your functions need. + +When you scaffold a new app, the CLI creates a starter role file at `src/roles/default-role.ts`. See [Roles & Permissions](/l/ru/developers/extend/apps/config/roles) for the full reference. + +## Marketplace metadata + +If you plan to [publish your app](/l/ru/developers/extend/apps/operations/publishing), these optional fields control how it appears in the marketplace: + +| Field | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `author` | Author or company name | +| `category` | App category for marketplace filtering | +| `logoUrl` | Path to your app logo (e.g., `public/logo.png`) | +| `screenshots` | Array of screenshot paths (e.g., `public/screenshot-1.png`) | +| `aboutDescription` | Longer markdown description for the "About" tab. If omitted, the marketplace uses the package's `README.md` from npm | +| `websiteUrl` | Link to your website | +| `termsUrl` | Link to terms of service | +| `emailSupport` | Support email address | +| `issueReportUrl` | Link to issue tracker | diff --git a/packages/twenty-docs/l/ru/developers/extend/apps/config/install-hooks.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/config/install-hooks.mdx new file mode 100644 index 0000000000..38efdbe1e9 --- /dev/null +++ b/packages/twenty-docs/l/ru/developers/extend/apps/config/install-hooks.mdx @@ -0,0 +1,206 @@ +--- +title: Install Hooks +description: Run logic before or after the install — seed data, back up records, validate the upgrade. +icon: wrench +--- + +Install hooks are special logic functions that run during the install or upgrade lifecycle. They share the same handler runtime as regular [logic functions](/l/ru/developers/extend/apps/logic/logic-functions) and receive an `InstallPayload`, but they're declared with their own define functions — `definePostInstallLogicFunction()` and `definePreInstallLogicFunction()` — and live outside the normal trigger model (HTTP, cron, database events). + +Each app may define **at most one pre-install** and **at most one post-install** function. The manifest build will error if more than one of either is detected. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ install flow │ +│ │ +│ upload package → [pre-install] → metadata migration → │ +│ generate SDK → [post-install] │ +│ │ +│ old schema visible new schema visible │ +└─────────────────────────────────────────────────────────────┘ +``` + +
+
+
+
+Once the server is up, a browser opens for sign-in. Use the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+Click **Authorize** on the next screen — this gives the CLI access to your workspace.
+
+
+
+
+
+
+Your terminal will confirm everything is set up.
+
+
+
+
+
+
+**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.
+
+
+
+
+
+
+Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
+
+
+
+
+
+
+Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
+
+
+
+
+
+
+Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
+
+
+
+
+
+
+**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.
+
+### One-shot sync for CI and scripts
+
+Pass `--once` to run a single build + sync and exit — same pipeline, no watcher:
+
+```bash filename="Terminal"
+yarn twenty dev --once
+```
+
+| Command | Behavior | When to use |
+| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
+| `yarn twenty dev --once` | Single build + sync, exits `0` on success, `1` on failure. | CI, pre-commit hooks, AI agents, scripted workflows. |
+
+Both modes need a server in development mode and an authenticated remote.
+
+
+
+
+ );
+};
+
+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',
+});
+```
+
+After syncing with `yarn twenty dev` (or running a one-shot `yarn twenty dev --once`), the quick action appears in the top-right corner of the page:
+
+Hello from my app!
+This component renders inside Twenty.
+
+
+
+
+Click it to render the component inline.
+
+## Configuration fields
+
+| Field | Required | Description |
+| --------------------- | -------- | ------------------------------------------------------------ |
+| `universalIdentifier` | Yes | Stable unique ID for this component |
+| `component` | Yes | A React component function |
+| `name` | No | Display name |
+| `description` | No | Description of what the component does |
+| `isHeadless` | No | Set to `true` if the component has no visible UI (see below) |
+
+## Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See [Page Layouts](/l/ru/developers/extend/apps/layout/page-layouts) for details.
+
+## Headless vs non-headless
+
+Front components come in two rendering modes controlled by the `isHeadless` option:
+
+**Non-headless (default)** — The component renders a visible UI. When triggered from the command menu it opens in the side panel. This is the default behavior when `isHeadless` is `false` or omitted.
+
+**Headless (`isHeadless: true`)** — The component mounts invisibly in the background. It does not open the side panel. Headless components are designed for actions that execute logic and then unmount themselves — for example, running an async task, navigating to a page, or showing a confirmation modal. They pair naturally with the SDK Command components described below.
+
+```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,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+## SDK Command components
+
+The `twenty-sdk` package provides four Command helper components designed for headless front components. Each component executes an action on mount, handles errors by showing a snackbar notification, and automatically unmounts the front component when done.
+
+Import them from `twenty-sdk/command`:
+
+* **`Command`** — Runs an async callback via the `execute` prop.
+* **`CommandLink`** — Navigates to an app path. Props: `to`, `params`, `queryParams`, `options`.
+* **`CommandModal`** — Opens a confirmation modal. If the user confirms, executes the `execute` callback. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
+* **`CommandOpenSidePanelPage`** — Opens a specific side panel page. Props: `page`, `pageTitle`, `pageIcon`.
+
+Here is a full example of a headless front component using `Command` to run an action from the command menu:
+
+```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,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Description |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useSelectedRecordIds()` | `string[]` | All selected record IDs (empty array if none selected) |
+| `useRecordId()` | `string` or `null` | **Deprecated.** Use `useSelectedRecordIds()` instead |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | varies | Access the full execution context with a selector function |
+
+## Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Function | Description |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Close the side panel |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+Here is an example that uses the host API to show a snackbar and close the side panel after an action completes:
+
+```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,
+});
+```
+
+### Working with multiple records
+
+Use `useSelectedRecordIds()` to handle multiple selected records. This is useful for bulk operations:
+
+```tsx src/front-components/bulk-export.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds, numberOfSelectedRecords } 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,
+ },
+});
+```
+
+## Public assets
+
+Front components can access files from the app's `public/` directory using `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,
+});
+```
+
+See the [public assets section](/l/ru/developers/extend/apps/config/public-assets) for details.
+
+## Styling
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/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/layout/navigation-menu-items.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/layout/navigation-menu-items.mdx
new file mode 100644
index 0000000000..1b7f893831
--- /dev/null
+++ b/packages/twenty-docs/l/ru/developers/extend/apps/layout/navigation-menu-items.mdx
@@ -0,0 +1,44 @@
+---
+title: Navigation Menu Items
+description: Add custom entries to the workspace sidebar — links to saved views or external URLs.
+icon: меню
+---
+
+A **navigation menu item** is an entry in the left sidebar. Use `defineNavigationMenuItem()` to ship custom sidebar links — typically one per [view](/l/ru/developers/extend/apps/layout/views) you ship — or to point at external URLs.
+
+```ts src/navigation-menu-items/example-navigation-menu-item.ts
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
+
+export default defineNavigationMenuItem({
+ universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
+ name: 'example-navigation-menu-item',
+ icon: 'IconList',
+ color: 'blue',
+ position: 0,
+ type: NavigationMenuItemType.VIEW,
+ viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Основные моменты
+
+* `type` determines what the menu item links to. Each type pairs with a specific identifier field:
+
+ | Тип | Что делает | Required field |
+ | ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- |
+ | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |
+ | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |
+ | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |
+ | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |
+ | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |
+
+* `position` controls ordering in the sidebar.
+
+* `icon` and `color` are optional and customize how the entry looks.
+
+* `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Setup + +The scaffolded app already includes Vitest. If you set it up manually, install the dependencies: + +```bash filename="Terminal" +yarn add -D vitest vite-tsconfig-paths +``` + +Create a `vitest.config.ts` at the root of your 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', + }, + }, +}); +``` + +Create a setup file that verifies the server is reachable before tests run: + +```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), + ); +}); +``` + +## Programmatic SDK APIs + +The `twenty-sdk/cli` subpath exports functions you can call directly from test code: + +| Function | Description | +| -------------- | ------------------------------------------- | +| `appBuild` | Build the app and optionally pack a tarball | +| `appDeploy` | Upload a tarball to the server | +| `appInstall` | Install the app on the active workspace | +| `appUninstall` | Uninstall the app from the active workspace | + +Each function returns a result object with `success: boolean` and either `data` or `error`. + +## Writing an integration test + +Here is a full example that builds, deploys, and installs the app, then verifies it appears in the workspace: + +```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(); + }); +}); +``` + +## Running tests + +Make sure your local Twenty server is running, then: + +```bash filename="Terminal" +yarn test +``` + +Or in watch mode during development: + +```bash filename="Terminal" +yarn test:watch +``` + +## Type checking + +You can also run type checking on your app without running tests: + +```bash filename="Terminal" +yarn twenty typecheck +``` + +This runs `tsc --noEmit` and reports any type errors. + +## CI with GitHub Actions + +The scaffolder generates a ready-to-use GitHub Actions workflow at `.github/workflows/ci.yml`. It runs your integration tests automatically on every push to `main` and on pull requests. + +The workflow: + +1. Checks out your code +2. Spins up a temporary Twenty server using the `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` action +3. Installs dependencies with `yarn install --immutable` +4. Runs `yarn test` with `TWENTY_API_URL` and `TWENTY_API_KEY` injected from the action outputs + +```yaml .github/workflows/ci.yml +name: CI + +on: + push: + branches: + - main + pull_request: {} + +env: + TWENTY_VERSION: latest + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Spawn Twenty instance + id: twenty + uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main + with: + twenty-version: ${{ env.TWENTY_VERSION }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Enable Corepack + run: corepack enable + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: '.nvmrc' + cache: 'yarn' + + - name: Install dependencies + run: yarn install --immutable + + - name: Run integration tests + run: yarn test + env: + TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }} + TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }} +``` + +You don't need to configure any secrets — the `spawn-twenty-docker-image` action starts an ephemeral Twenty server directly in the runner and outputs the connection details. The `GITHUB_TOKEN` secret is provided automatically by GitHub. + +To pin a specific Twenty version instead of `latest`, change the `TWENTY_VERSION` environment variable at the top of the workflow. diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/config/application.mdx new file mode 100644 index 0000000000..633d12dc0f --- /dev/null +++ b/packages/twenty-docs/l/tr/developers/extend/apps/config/application.mdx @@ -0,0 +1,65 @@ +--- +title: Application Config +description: Declare your app's identity, default role, variables, and marketplace metadata with defineApplication. +icon: rocket +--- + +Every app must have exactly one `defineApplication` call. It declares: + +* **Identity** — universal identifier, display name, description. +* **Permissions** — which role its logic functions and front components run under. +* **Variables** *(optional)* — key–value pairs exposed to your code as environment variables. +* **Pre-install / post-install hooks** *(optional)* — see [Logic Functions](/l/tr/developers/extend/apps/logic/logic-functions). + +```ts src/application-config.ts +import { defineApplication } from 'twenty-sdk/define'; +import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role'; + +export default defineApplication({ + universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d', + displayName: 'My Twenty App', + description: 'My first Twenty app', + applicationVariables: { + DEFAULT_RECIPIENT_NAME: { + universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de', + description: 'Default recipient name for postcards', + value: 'Jane Doe', + isSecret: false, + }, + }, + defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER, +}); +``` + +Notes: + +* `universalIdentifier` fields are deterministic IDs you own. Generate them once and keep them stable across syncs. +* `applicationVariables` become environment variables for your functions and front components (e.g., `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`). +* `defaultRoleUniversalIdentifier` must reference a role defined with [`defineRole()`](/l/tr/developers/extend/apps/config/roles). +* Pre-install and post-install functions are detected automatically during the manifest build — you do not need to reference them in `defineApplication()`. + +## Default function role + +The `defaultRoleUniversalIdentifier` controls what the app's logic functions and front components can access: + +* The runtime token injected as `TWENTY_APP_ACCESS_TOKEN` is derived from this role. +* The typed API client is restricted to the permissions granted to that role. +* Follow least-privilege: declare only the permissions your functions need. + +When you scaffold a new app, the CLI creates a starter role file at `src/roles/default-role.ts`. See [Roles & Permissions](/l/tr/developers/extend/apps/config/roles) for the full reference. + +## Marketplace metadata + +If you plan to [publish your app](/l/tr/developers/extend/apps/operations/publishing), these optional fields control how it appears in the marketplace: + +| Field | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `author` | Author or company name | +| `category` | App category for marketplace filtering | +| `logoUrl` | Path to your app logo (e.g., `public/logo.png`) | +| `screenshots` | Array of screenshot paths (e.g., `public/screenshot-1.png`) | +| `aboutDescription` | Longer markdown description for the "About" tab. If omitted, the marketplace uses the package's `README.md` from npm | +| `websiteUrl` | Link to your website | +| `termsUrl` | Link to terms of service | +| `emailSupport` | Support email address | +| `issueReportUrl` | Link to issue tracker | diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/config/install-hooks.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/config/install-hooks.mdx new file mode 100644 index 0000000000..cb66b87a8e --- /dev/null +++ b/packages/twenty-docs/l/tr/developers/extend/apps/config/install-hooks.mdx @@ -0,0 +1,206 @@ +--- +title: Install Hooks +description: Run logic before or after the install — seed data, back up records, validate the upgrade. +icon: wrench +--- + +Install hooks are special logic functions that run during the install or upgrade lifecycle. They share the same handler runtime as regular [logic functions](/l/tr/developers/extend/apps/logic/logic-functions) and receive an `InstallPayload`, but they're declared with their own define functions — `definePostInstallLogicFunction()` and `definePreInstallLogicFunction()` — and live outside the normal trigger model (HTTP, cron, database events). + +Each app may define **at most one pre-install** and **at most one post-install** function. The manifest build will error if more than one of either is detected. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ install flow │ +│ │ +│ upload package → [pre-install] → metadata migration → │ +│ generate SDK → [post-install] │ +│ │ +│ old schema visible new schema visible │ +└─────────────────────────────────────────────────────────────┘ +``` + +
+
+
+
+Once the server is up, a browser opens for sign-in. Use the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+Click **Authorize** on the next screen — this gives the CLI access to your workspace.
+
+
+
+
+
+
+Your terminal will confirm everything is set up.
+
+
+
+
+
+
+**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.
+
+
+
+
+
+
+Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
+
+
+
+
+
+
+Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
+
+
+
+
+
+
+Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
+
+
+
+
+
+
+**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.
+
+### One-shot sync for CI and scripts
+
+Pass `--once` to run a single build + sync and exit — same pipeline, no watcher:
+
+```bash filename="Terminal"
+yarn twenty dev --once
+```
+
+| Command | Behavior | When to use |
+| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
+| `yarn twenty dev --once` | Single build + sync, exits `0` on success, `1` on failure. | CI, pre-commit hooks, AI agents, scripted workflows. |
+
+Both modes need a server in development mode and an authenticated remote.
+
+
+
+
+ );
+};
+
+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',
+});
+```
+
+After syncing with `yarn twenty dev` (or running a one-shot `yarn twenty dev --once`), the quick action appears in the top-right corner of the page:
+
+Hello from my app!
+This component renders inside Twenty.
+
+
+
+
+Click it to render the component inline.
+
+## Configuration fields
+
+| Field | Required | Description |
+| --------------------- | -------- | ------------------------------------------------------------ |
+| `universalIdentifier` | Yes | Stable unique ID for this component |
+| `component` | Yes | A React component function |
+| `name` | No | Display name |
+| `description` | No | Description of what the component does |
+| `isHeadless` | No | Set to `true` if the component has no visible UI (see below) |
+
+## Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See [Page Layouts](/l/tr/developers/extend/apps/layout/page-layouts) for details.
+
+## Headless vs non-headless
+
+Front components come in two rendering modes controlled by the `isHeadless` option:
+
+**Non-headless (default)** — The component renders a visible UI. When triggered from the command menu it opens in the side panel. This is the default behavior when `isHeadless` is `false` or omitted.
+
+**Headless (`isHeadless: true`)** — The component mounts invisibly in the background. It does not open the side panel. Headless components are designed for actions that execute logic and then unmount themselves — for example, running an async task, navigating to a page, or showing a confirmation modal. They pair naturally with the SDK Command components described below.
+
+```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,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+## SDK Command components
+
+The `twenty-sdk` package provides four Command helper components designed for headless front components. Each component executes an action on mount, handles errors by showing a snackbar notification, and automatically unmounts the front component when done.
+
+Import them from `twenty-sdk/command`:
+
+* **`Command`** — Runs an async callback via the `execute` prop.
+* **`CommandLink`** — Navigates to an app path. Props: `to`, `params`, `queryParams`, `options`.
+* **`CommandModal`** — Opens a confirmation modal. If the user confirms, executes the `execute` callback. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
+* **`CommandOpenSidePanelPage`** — Opens a specific side panel page. Props: `page`, `pageTitle`, `pageIcon`.
+
+Here is a full example of a headless front component using `Command` to run an action from the command menu:
+
+```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,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Description |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useSelectedRecordIds()` | `string[]` | All selected record IDs (empty array if none selected) |
+| `useRecordId()` | `string` or `null` | **Deprecated.** Use `useSelectedRecordIds()` instead |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | varies | Access the full execution context with a selector function |
+
+## Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Function | Description |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Close the side panel |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+Here is an example that uses the host API to show a snackbar and close the side panel after an action completes:
+
+```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,
+});
+```
+
+### Working with multiple records
+
+Use `useSelectedRecordIds()` to handle multiple selected records. This is useful for bulk operations:
+
+```tsx src/front-components/bulk-export.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds, numberOfSelectedRecords } 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,
+ },
+});
+```
+
+## Public assets
+
+Front components can access files from the app's `public/` directory using `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,
+});
+```
+
+See the [public assets section](/l/tr/developers/extend/apps/config/public-assets) for details.
+
+## Styling
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/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/layout/navigation-menu-items.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/layout/navigation-menu-items.mdx
new file mode 100644
index 0000000000..e97866cae7
--- /dev/null
+++ b/packages/twenty-docs/l/tr/developers/extend/apps/layout/navigation-menu-items.mdx
@@ -0,0 +1,44 @@
+---
+title: Navigation Menu Items
+description: Add custom entries to the workspace sidebar — links to saved views or external URLs.
+icon: bars
+---
+
+A **navigation menu item** is an entry in the left sidebar. Use `defineNavigationMenuItem()` to ship custom sidebar links — typically one per [view](/l/tr/developers/extend/apps/layout/views) you ship — or to point at external URLs.
+
+```ts src/navigation-menu-items/example-navigation-menu-item.ts
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
+
+export default defineNavigationMenuItem({
+ universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
+ name: 'example-navigation-menu-item',
+ icon: 'IconList',
+ color: 'blue',
+ position: 0,
+ type: NavigationMenuItemType.VIEW,
+ viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Önemli noktalar
+
+* `type` determines what the menu item links to. Each type pairs with a specific identifier field:
+
+ | Tür | Ne yapar | Required field |
+ | ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- |
+ | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |
+ | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |
+ | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |
+ | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |
+ | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |
+
+* `position` controls ordering in the sidebar.
+
+* `icon` and `color` are optional and customize how the entry looks.
+
+* `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Setup + +The scaffolded app already includes Vitest. If you set it up manually, install the dependencies: + +```bash filename="Terminal" +yarn add -D vitest vite-tsconfig-paths +``` + +Create a `vitest.config.ts` at the root of your 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', + }, + }, +}); +``` + +Create a setup file that verifies the server is reachable before tests run: + +```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), + ); +}); +``` + +## Programmatic SDK APIs + +The `twenty-sdk/cli` subpath exports functions you can call directly from test code: + +| Function | Description | +| -------------- | ------------------------------------------- | +| `appBuild` | Build the app and optionally pack a tarball | +| `appDeploy` | Upload a tarball to the server | +| `appInstall` | Install the app on the active workspace | +| `appUninstall` | Uninstall the app from the active workspace | + +Each function returns a result object with `success: boolean` and either `data` or `error`. + +## Writing an integration test + +Here is a full example that builds, deploys, and installs the app, then verifies it appears in the workspace: + +```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(); + }); +}); +``` + +## Running tests + +Make sure your local Twenty server is running, then: + +```bash filename="Terminal" +yarn test +``` + +Or in watch mode during development: + +```bash filename="Terminal" +yarn test:watch +``` + +## Type checking + +You can also run type checking on your app without running tests: + +```bash filename="Terminal" +yarn twenty typecheck +``` + +This runs `tsc --noEmit` and reports any type errors. + +## CI with GitHub Actions + +The scaffolder generates a ready-to-use GitHub Actions workflow at `.github/workflows/ci.yml`. It runs your integration tests automatically on every push to `main` and on pull requests. + +The workflow: + +1. Checks out your code +2. Spins up a temporary Twenty server using the `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` action +3. Installs dependencies with `yarn install --immutable` +4. Runs `yarn test` with `TWENTY_API_URL` and `TWENTY_API_KEY` injected from the action outputs + +```yaml .github/workflows/ci.yml +name: CI + +on: + push: + branches: + - main + pull_request: {} + +env: + TWENTY_VERSION: latest + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Spawn Twenty instance + id: twenty + uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main + with: + twenty-version: ${{ env.TWENTY_VERSION }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Enable Corepack + run: corepack enable + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: '.nvmrc' + cache: 'yarn' + + - name: Install dependencies + run: yarn install --immutable + + - name: Run integration tests + run: yarn test + env: + TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }} + TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }} +``` + +You don't need to configure any secrets — the `spawn-twenty-docker-image` action starts an ephemeral Twenty server directly in the runner and outputs the connection details. The `GITHUB_TOKEN` secret is provided automatically by GitHub. + +To pin a specific Twenty version instead of `latest`, change the `TWENTY_VERSION` environment variable at the top of the workflow. diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/config/application.mdx new file mode 100644 index 0000000000..eba2fab940 --- /dev/null +++ b/packages/twenty-docs/l/zh/developers/extend/apps/config/application.mdx @@ -0,0 +1,65 @@ +--- +title: Application Config +description: Declare your app's identity, default role, variables, and marketplace metadata with defineApplication. +icon: rocket +--- + +Every app must have exactly one `defineApplication` call. It declares: + +* **Identity** — universal identifier, display name, description. +* **Permissions** — which role its logic functions and front components run under. +* **Variables** *(optional)* — key–value pairs exposed to your code as environment variables. +* **Pre-install / post-install hooks** *(optional)* — see [Logic Functions](/l/zh/developers/extend/apps/logic/logic-functions). + +```ts src/application-config.ts +import { defineApplication } from 'twenty-sdk/define'; +import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role'; + +export default defineApplication({ + universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d', + displayName: 'My Twenty App', + description: 'My first Twenty app', + applicationVariables: { + DEFAULT_RECIPIENT_NAME: { + universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de', + description: 'Default recipient name for postcards', + value: 'Jane Doe', + isSecret: false, + }, + }, + defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER, +}); +``` + +Notes: + +* `universalIdentifier` fields are deterministic IDs you own. Generate them once and keep them stable across syncs. +* `applicationVariables` become environment variables for your functions and front components (e.g., `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`). +* `defaultRoleUniversalIdentifier` must reference a role defined with [`defineRole()`](/l/zh/developers/extend/apps/config/roles). +* Pre-install and post-install functions are detected automatically during the manifest build — you do not need to reference them in `defineApplication()`. + +## Default function role + +The `defaultRoleUniversalIdentifier` controls what the app's logic functions and front components can access: + +* The runtime token injected as `TWENTY_APP_ACCESS_TOKEN` is derived from this role. +* The typed API client is restricted to the permissions granted to that role. +* Follow least-privilege: declare only the permissions your functions need. + +When you scaffold a new app, the CLI creates a starter role file at `src/roles/default-role.ts`. See [Roles & Permissions](/l/zh/developers/extend/apps/config/roles) for the full reference. + +## Marketplace metadata + +If you plan to [publish your app](/l/zh/developers/extend/apps/operations/publishing), these optional fields control how it appears in the marketplace: + +| Field | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `author` | Author or company name | +| `category` | App category for marketplace filtering | +| `logoUrl` | Path to your app logo (e.g., `public/logo.png`) | +| `screenshots` | Array of screenshot paths (e.g., `public/screenshot-1.png`) | +| `aboutDescription` | Longer markdown description for the "About" tab. If omitted, the marketplace uses the package's `README.md` from npm | +| `websiteUrl` | Link to your website | +| `termsUrl` | Link to terms of service | +| `emailSupport` | Support email address | +| `issueReportUrl` | Link to issue tracker | diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/config/install-hooks.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/config/install-hooks.mdx new file mode 100644 index 0000000000..734ffc2828 --- /dev/null +++ b/packages/twenty-docs/l/zh/developers/extend/apps/config/install-hooks.mdx @@ -0,0 +1,206 @@ +--- +title: Install Hooks +description: Run logic before or after the install — seed data, back up records, validate the upgrade. +icon: wrench +--- + +Install hooks are special logic functions that run during the install or upgrade lifecycle. They share the same handler runtime as regular [logic functions](/l/zh/developers/extend/apps/logic/logic-functions) and receive an `InstallPayload`, but they're declared with their own define functions — `definePostInstallLogicFunction()` and `definePreInstallLogicFunction()` — and live outside the normal trigger model (HTTP, cron, database events). + +Each app may define **at most one pre-install** and **at most one post-install** function. The manifest build will error if more than one of either is detected. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ install flow │ +│ │ +│ upload package → [pre-install] → metadata migration → │ +│ generate SDK → [post-install] │ +│ │ +│ old schema visible new schema visible │ +└─────────────────────────────────────────────────────────────┘ +``` + +
+
+
+
+Once the server is up, a browser opens for sign-in. Use the pre-seeded demo account:
+
+* **Email:** `tim@apple.dev`
+* **Password:** `tim@apple.dev`
+
+
+
+
+
+
+Click **Authorize** on the next screen — this gives the CLI access to your workspace.
+
+
+
+
+
+
+Your terminal will confirm everything is set up.
+
+
+
+
+
+
+**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.
+
+
+
+
+
+
+Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
+
+
+
+
+
+
+Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
+
+
+
+
+
+
+Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
+
+
+
+
+
+
+**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.
+
+### One-shot sync for CI and scripts
+
+Pass `--once` to run a single build + sync and exit — same pipeline, no watcher:
+
+```bash filename="Terminal"
+yarn twenty dev --once
+```
+
+| Command | Behavior | When to use |
+| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
+| `yarn twenty dev --once` | Single build + sync, exits `0` on success, `1` on failure. | CI, pre-commit hooks, AI agents, scripted workflows. |
+
+Both modes need a server in development mode and an authenticated remote.
+
+
+
+
+ );
+};
+
+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',
+});
+```
+
+After syncing with `yarn twenty dev` (or running a one-shot `yarn twenty dev --once`), the quick action appears in the top-right corner of the page:
+
+Hello from my app!
+This component renders inside Twenty.
+
+
+
+
+Click it to render the component inline.
+
+## Configuration fields
+
+| Field | Required | Description |
+| --------------------- | -------- | ------------------------------------------------------------ |
+| `universalIdentifier` | Yes | Stable unique ID for this component |
+| `component` | Yes | A React component function |
+| `name` | No | Display name |
+| `description` | No | Description of what the component does |
+| `isHeadless` | No | Set to `true` if the component has no visible UI (see below) |
+
+## Placing a front component on a page
+
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See [Page Layouts](/l/zh/developers/extend/apps/layout/page-layouts) for details.
+
+## Headless vs non-headless
+
+Front components come in two rendering modes controlled by the `isHeadless` option:
+
+**Non-headless (default)** — The component renders a visible UI. When triggered from the command menu it opens in the side panel. This is the default behavior when `isHeadless` is `false` or omitted.
+
+**Headless (`isHeadless: true`)** — The component mounts invisibly in the background. It does not open the side panel. Headless components are designed for actions that execute logic and then unmount themselves — for example, running an async task, navigating to a page, or showing a confirmation modal. They pair naturally with the SDK Command components described below.
+
+```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,
+});
+```
+
+Because the component returns `null`, Twenty skips rendering a container for it — no empty space appears in the layout. The component still has access to all hooks and the host communication API.
+
+## SDK Command components
+
+The `twenty-sdk` package provides four Command helper components designed for headless front components. Each component executes an action on mount, handles errors by showing a snackbar notification, and automatically unmounts the front component when done.
+
+Import them from `twenty-sdk/command`:
+
+* **`Command`** — Runs an async callback via the `execute` prop.
+* **`CommandLink`** — Navigates to an app path. Props: `to`, `params`, `queryParams`, `options`.
+* **`CommandModal`** — Opens a confirmation modal. If the user confirms, executes the `execute` callback. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
+* **`CommandOpenSidePanelPage`** — Opens a specific side panel page. Props: `page`, `pageTitle`, `pageIcon`.
+
+Here is a full example of a headless front component using `Command` to run an action from the command menu:
+
+```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,
+});
+```
+
+Available hooks:
+
+| Hook | Returns | Description |
+| --------------------------------------------- | ------------------ | ---------------------------------------------------------- |
+| `useUserId()` | `string` or `null` | The current user's ID |
+| `useSelectedRecordIds()` | `string[]` | All selected record IDs (empty array if none selected) |
+| `useRecordId()` | `string` or `null` | **Deprecated.** Use `useSelectedRecordIds()` instead |
+| `useFrontComponentId()` | `string` | This component instance's ID |
+| `useFrontComponentExecutionContext(selector)` | varies | Access the full execution context with a selector function |
+
+## Host communication API
+
+Front components can trigger navigation, modals, and notifications using functions from `twenty-sdk`:
+
+| Function | Description |
+| ----------------------------------------------- | ----------------------------- |
+| `navigate(to, params?, queryParams?, options?)` | Navigate to a page in the app |
+| `openSidePanelPage(params)` | Open a side panel |
+| `closeSidePanel()` | Close the side panel |
+| `openCommandConfirmationModal(params)` | Show a confirmation dialog |
+| `enqueueSnackbar(params)` | Show a toast notification |
+| `unmountFrontComponent()` | Unmount the component |
+| `updateProgress(progress)` | Update a progress indicator |
+
+Here is an example that uses the host API to show a snackbar and close the side panel after an action completes:
+
+```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,
+});
+```
+
+### Working with multiple records
+
+Use `useSelectedRecordIds()` to handle multiple selected records. This is useful for bulk operations:
+
+```tsx src/front-components/bulk-export.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds, numberOfSelectedRecords } 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,
+ },
+});
+```
+
+## Public assets
+
+Front components can access files from the app's `public/` directory using `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,
+});
+```
+
+See the [public assets section](/l/zh/developers/extend/apps/config/public-assets) for details.
+
+## Styling
+
+Front components support multiple styling approaches. You can use:
+
+* **Inline styles** — `style={{ color: 'red' }}`
+* **Twenty UI components** — import from `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar, and more)
+* **Emotion** — CSS-in-JS with `@emotion/react`
+* **Styled-components** — `styled.div` patterns
+* **Tailwind CSS** — utility classes
+* **Any CSS-in-JS library** compatible with React
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/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/layout/navigation-menu-items.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/layout/navigation-menu-items.mdx
new file mode 100644
index 0000000000..f6eaed750f
--- /dev/null
+++ b/packages/twenty-docs/l/zh/developers/extend/apps/layout/navigation-menu-items.mdx
@@ -0,0 +1,44 @@
+---
+title: Navigation Menu Items
+description: Add custom entries to the workspace sidebar — links to saved views or external URLs.
+icon: bars
+---
+
+A **navigation menu item** is an entry in the left sidebar. Use `defineNavigationMenuItem()` to ship custom sidebar links — typically one per [view](/l/zh/developers/extend/apps/layout/views) you ship — or to point at external URLs.
+
+```ts src/navigation-menu-items/example-navigation-menu-item.ts
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
+
+export default defineNavigationMenuItem({
+ universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
+ name: 'example-navigation-menu-item',
+ icon: 'IconList',
+ color: 'blue',
+ position: 0,
+ type: NavigationMenuItemType.VIEW,
+ viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Key points
+
+* `type` determines what the menu item links to. Each type pairs with a specific identifier field:
+
+ | 类型 | 作用 | Required field |
+ | ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------- |
+ | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |
+ | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |
+ | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |
+ | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |
+ | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |
+
+* `position` controls ordering in the sidebar.
+
+* `icon` and `color` are optional and customize how the entry looks.
+
+* `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.
+
+Today is {format(new Date(), 'MMMM do, yyyy')}
; +}; + +export default defineFrontComponent({ + universalIdentifier: '...', + name: 'date-widget', + component: DateWidget, +}); +``` + +### How bundling works + +The build step uses esbuild to produce a single self-contained file per logic function and per front component. All imported packages are inlined into the bundle. + +**Logic functions** run in a Node.js environment. Node built-in modules (`fs`, `path`, `crypto`, `http`, etc.) are available and do not need to be installed. + +**Front components** run in a Web Worker. Node built-in modules are **not** available — only browser APIs and npm packages that work in a browser environment. + +Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server. + +## Setup + +The scaffolded app already includes Vitest. If you set it up manually, install the dependencies: + +```bash filename="Terminal" +yarn add -D vitest vite-tsconfig-paths +``` + +Create a `vitest.config.ts` at the root of your 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', + }, + }, +}); +``` + +Create a setup file that verifies the server is reachable before tests run: + +```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), + ); +}); +``` + +## Programmatic SDK APIs + +The `twenty-sdk/cli` subpath exports functions you can call directly from test code: + +| Function | Description | +| -------------- | ------------------------------------------- | +| `appBuild` | Build the app and optionally pack a tarball | +| `appDeploy` | Upload a tarball to the server | +| `appInstall` | Install the app on the active workspace | +| `appUninstall` | Uninstall the app from the active workspace | + +Each function returns a result object with `success: boolean` and either `data` or `error`. + +## Writing an integration test + +Here is a full example that builds, deploys, and installs the app, then verifies it appears in the workspace: + +```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(); + }); +}); +``` + +## Running tests + +Make sure your local Twenty server is running, then: + +```bash filename="Terminal" +yarn test +``` + +Or in watch mode during development: + +```bash filename="Terminal" +yarn test:watch +``` + +## Type checking + +You can also run type checking on your app without running tests: + +```bash filename="Terminal" +yarn twenty typecheck +``` + +This runs `tsc --noEmit` and reports any type errors. + +## CI with GitHub Actions + +The scaffolder generates a ready-to-use GitHub Actions workflow at `.github/workflows/ci.yml`. It runs your integration tests automatically on every push to `main` and on pull requests. + +The workflow: + +1. Checks out your code +2. Spins up a temporary Twenty server using the `twentyhq/twenty/.github/actions/spawn-twenty-docker-image` action +3. Installs dependencies with `yarn install --immutable` +4. Runs `yarn test` with `TWENTY_API_URL` and `TWENTY_API_KEY` injected from the action outputs + +```yaml .github/workflows/ci.yml +name: CI + +on: + push: + branches: + - main + pull_request: {} + +env: + TWENTY_VERSION: latest + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Spawn Twenty instance + id: twenty + uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main + with: + twenty-version: ${{ env.TWENTY_VERSION }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Enable Corepack + run: corepack enable + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: '.nvmrc' + cache: 'yarn' + + - name: Install dependencies + run: yarn install --immutable + + - name: Run integration tests + run: yarn test + env: + TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }} + TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }} +``` + +You don't need to configure any secrets — the `spawn-twenty-docker-image` action starts an ephemeral Twenty server directly in the runner and outputs the connection details. The `GITHUB_TOKEN` secret is provided automatically by GitHub. + +To pin a specific Twenty version instead of `latest`, change the `TWENTY_VERSION` environment variable at the top of the workflow.