Twenty

https://docs.twenty.com/
Admin
Twenty is an open-source CRM that provides customizable building blocks for tracking deals,...
Tokens:564,537
Snippets:5,217
Trust Score:9.5
Update:5 days ago
Show doc for...
Tokens:
Raw
### Integration test for app installation in src/__tests__/app-install.integration-test.ts

Source: https://docs.twenty.com/developers/extend/apps/operations/testing

This example demonstrates building, deploying, and installing an app, followed by a verification step using the MetadataApiClient to ensure the app appears in the workspace.

```typescript
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();
  });
});
```

--------------------------------

### Start all services

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Alternatively, start all project services simultaneously.

```bash
npx nx start
```

--------------------------------

### Install NVM

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Install curl and use it to download and run the NVM installation script.

```bash
sudo apt-get install curl

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
```

--------------------------------

### Install and Configure Git

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Install Git and set your global user name and email configuration.

```bash
sudo apt-get install git

git config --global user.name "Your Name"

git config --global user.email "youremail@domain.com"
```

--------------------------------

### Start Redis Server with Homebrew

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Start the Redis service using Homebrew services.

```bash
brew services start redis
```

--------------------------------

### Start the App

Source: https://docs.twenty.com/developers/contribute/commands

Commands to start the frontend dev server, backend server, and background worker.

```bash
npx nx start twenty-front          # Frontend dev server (http://localhost:3001)
npx nx start twenty-server         # Backend server (http://localhost:3000)
npx nx run twenty-server:worker    # Background worker
```

--------------------------------

### Provision PostgreSQL on macOS with Homebrew

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Install PostgreSQL 16, start the service, and create the required databases.

```bash
brew install postgresql@16
export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
brew services start postgresql@16
psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
```

--------------------------------

### Download .env example file

Source: https://docs.twenty.com/developers/self-host/capabilities/docker-compose

Copies the example environment file to a new .env file in the working directory.

```bash
curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example
```

--------------------------------

### Install an app via CLI

Source: https://docs.twenty.com/developers/extend/apps/operations/publishing

Use the yarn command to install an application into your Twenty workspace.

```bash
yarn twenty app:install
```

--------------------------------

### Example: Access via Domain with SSL

Source: https://docs.twenty.com/developers/self-host/capabilities/docker-compose

An example of the SERVER_URL configuration for access via a domain with SSL.

```text
SERVER_URL=https://mytwentyapp.com
```

--------------------------------

### Example output of updated PostgreSQL roles

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Example output showing the roles after creating the postgres user.

```text
Role name | Attributes  | Member of
----------+-------------+-----------
postgres  | Superuser   | {}
john      | Superuser   | {}
```

--------------------------------

### Install Twenty UI dependencies

Source: https://docs.twenty.com/ui/getting-started

Install the library and required peer dependencies for a standalone React application.

```bash
yarn add twenty-ui react@^19 react-dom@^19
```

--------------------------------

### Example: Direct Access without SSL

Source: https://docs.twenty.com/developers/self-host/capabilities/docker-compose

An example of the SERVER_URL configuration for direct access without SSL.

```text
SERVER_URL=http://123.45.67.89:3000
```

--------------------------------

### LightButton Usage

Source: https://docs.twenty.com/ui/components/input/light-button

Example of using LightButton with a start icon and subtle emphasis.

```APIDOC
## LightButton Usage

### Description
Example of using LightButton with a start icon and subtle emphasis.

### Code Example
```jsx
import { LightButton } from 'twenty-ui/components/input';
import { IconPlus } from 'twenty-ui/icon';

export const FilterActions = () => (
  <LightButton emphasis="subtle" startIcon={<IconPlus />}>
    Add filter
  </LightButton>
);
```
```

--------------------------------

### CreateRecord Button implementation

Source: https://docs.twenty.com/ui/primitives/input/button

An example of a solid accent button with a small size and a start icon.

```jsx
import { Button } from 'twenty-ui/primitives/input';
import { IconPlus } from 'twenty-ui/icon';

export const CreateRecord = () => (
  <Button variant="solid" color="accent" size="sm" startIcon={<IconPlus />}>
    Create record
  </Button>
);
```

--------------------------------

### FilterActions LightButton implementation

Source: https://docs.twenty.com/ui/components/input/light-button

Example showing how to use the LightButton component with subtle emphasis and a start icon.

```tsx
import { LightButton } from 'twenty-ui/components/input';
import { IconPlus } from 'twenty-ui/icon';

export const FilterActions = () => (
  <LightButton emphasis="subtle" startIcon={<IconPlus />}>
    Add filter
  </LightButton>
);
```

--------------------------------

### Install from branch

Source: https://docs.twenty.com/developers/self-host/capabilities/docker-compose

Fetch configuration files from a specific branch to test unreleased changes.

```bash
BRANCH=branch-name bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
```

--------------------------------

### Create global setup file src/__tests__/global-setup.ts

Source: https://docs.twenty.com/developers/extend/apps/operations/testing

Implement a global setup file to verify server reachability, write the SDK test configuration, and synchronize the application before tests execute.

```typescript
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';

import { appDevOnce, appUninstall } from 'twenty-sdk/cli';

const APP_PATH = process.cwd();
const CONFIG_DIR = path.join(os.homedir(), '.twenty');

export async function setup() {
  const apiUrl = process.env.TWENTY_API_URL!;
  const apiKey = process.env.TWENTY_API_KEY!;

  // Verify the server is running
  const response = await fetch(`${apiUrl}/healthz`);
  if (!response.ok) {
    throw new Error(`Twenty server is not reachable at ${apiUrl}.`);
  }

  // Write the SDK's test config (the CLI reads config.test.json when NODE_ENV=test)
  fs.mkdirSync(CONFIG_DIR, { recursive: true });
  fs.writeFileSync(
    path.join(CONFIG_DIR, 'config.test.json'),
    JSON.stringify({
      remotes: { local: { apiUrl, apiKey } },
      defaultRemote: 'local',
    }, null, 2),
  );

  // Start from a clean slate, then sync the app
  await appUninstall({ appPath: APP_PATH }).catch(() => {});

  const result = await appDevOnce({ appPath: APP_PATH });
  if (!result.success) {
    throw new Error(`Dev sync failed: ${result.error?.message}`);
  }
}

export async function teardown() {
  await appUninstall({ appPath: APP_PATH });
}
```

--------------------------------

### TabButton Component Usage

Source: https://docs.twenty.com/ui/components/navigation/tab-button

Example of using TabButton with a start icon and onClick handler to add new tabs.

```APIDOC
## TabButton Component

### Description
Renders a button or anchor for tab navigation. Supports icons, badges, custom rendering, and various states.

### Usage Example
```jsx
import { useState } from 'react';
import { TabButton } from 'twenty-ui/components/navigation';
import { IconPlus } from 'twenty-ui/icon';
import { Text } from 'twenty-ui/primitives/typography';

export const AddTabAction = () => {
  const [count, setCount] = useState(1);

  return (
    <>
      <TabButton startIcon={<IconPlus />} onClick={() => setCount(count + 1)}>
        New Tab
      </TabButton>
      <Text role="status">Tabs: {count}</Text>
    </>
  );
};
```

### Props

#### active
- **Type**: boolean
- **Default**: "false"
- **Description**: Highlights the current destination or an action associated with the active tab. Does not change the control role.

#### badge
- **Type**: ReactNode
- **Description**: Content following the label and trailing icon, such as a count.

#### className
- **Type**: string | ((state: ButtonState) => string | undefined)
- **Description**: CSS class applied to the element, or a function that returns a class based on the component's state.

#### endIcon
- **Type**: ReactNode
- **Description**: Decorative content displayed after the label.

#### focusableWhenDisabled
- **Type**: boolean
- **Default**: "false"
- **Description**: Whether the button should be focusable when disabled.

#### href
- **Type**: string
- **Description**: Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract.

#### nativeButton
- **Type**: boolean
- **Default**: "true"
- **Description**: Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence.

#### render
- **Type**: ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>
- **Description**: Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role="link"` for a custom navigation anchor. Router integration belongs to the caller.

#### role
- **Type**: AriaRole
- **Description**: Role of the root element. Use `link` for custom navigation renderers.

#### size
- **Type**: "md" | "sm"
- **Default**: "sm"
- **Description**: Padding of the tab content: sm or md. Explicit size takes precedence over the ButtonGroup size, then sm applies.

#### startIcon
- **Type**: ReactNode
- **Description**: Decorative content displayed before the label.

#### style
- **Type**: CSSProperties | ((state: ButtonState) => CSSProperties | undefined)
- **Description**: Style applied to the element, or a function that returns a style object based on the component's state.
```

--------------------------------

### Copy Environment Variable Files

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Initialize the environment configuration by copying the example files for both the front and server packages.

```bash
cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env
cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env
```

--------------------------------

### definePostInstallLogicFunction example: seed a default record

Source: https://docs.twenty.com/developers/extend/apps/config/install-hooks

Example of a post-install logic function that seeds a welcome post card on fresh installs. It uses previousVersion to skip upgrades, calls the CoreApiClient mutation, and sets shouldRunOnVersionUpgrade to false.

```typescript
import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
  if (previousVersion) return; // fresh installs only

  const client = new CoreApiClient();
  await client.mutation({
    createPostCard: {
      __args: { data: { name: 'Welcome to Postcard', content: 'Your first card!' } },
      id: true,
    },
  });
};

export default definePostInstallLogicFunction({
  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
  name: 'post-install',
  description: 'Seeds a welcome post card after install.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: false,
  shouldRunSynchronously: false,
  handler,
});

```

--------------------------------

### Example upgrade status output

Source: https://docs.twenty.com/developers/self-host/capabilities/upgrade-guide

The output displays the current application version, instance migration status, and individual workspace migration details.

```text
APP_VERSION: v1.23.0

Instance
    Inferred version: 1.23.0
    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
    Status:           Up to date
    Executed by:      v1.23.0
    At:               2026-04-16T11:43:58.823Z

Workspace
  App*** (20202020-***)
      Inferred version: 1.23.0
      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
      Status:           Up to date
      Executed by:      v1.23.0
      At:               2026-04-16T11:44:09.361Z

Summary
    Instance: Up to date
    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)
```

--------------------------------

### Install WSL on Windows

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Run this command in PowerShell as Administrator to install WSL.

```powershell
wsl --install
```

--------------------------------

### Install CodeEditor peer dependencies

Source: https://docs.twenty.com/ui/components/code-editor/code-editor

Install the required peer dependencies for the CodeEditor component.

```bash
yarn add @monaco-editor/react monaco-editor
```

--------------------------------

### Array Data Structure Example

Source: https://docs.twenty.com/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger

Example of a JSON payload containing an array of items.

```json
{
  "items": [
    {"name": "Product A", "qty": 2},
    {"name": "Product B", "qty": 1}
  ]
}
```

--------------------------------

### Usage Example

Source: https://docs.twenty.com/ui/primitives/input/number-field

Example of a controlled NumberField with a price input, using onValueChange and onValueCommitted.

```APIDOC
## Usage Example

### Description
Example of a controlled NumberField with a price input, using onValueChange and onValueCommitted.

### Code
```jsx
import { useState } from 'react';
import { Field, NumberField } from 'twenty-ui/primitives/input';

export const PriceInput = () => {
  const [price, setPrice] = useState<number | null>(null);
  const [savedPrice, setSavedPrice] = useState<number | null>(null);

  return (
    <Field.Root>
      <Field.Label>Price</Field.Label>
      <NumberField.Root
        value={price}
        onValueChange={setPrice}
        onValueCommitted={setSavedPrice}
      >
        <NumberField.Input placeholder="Enter a price" />
      </NumberField.Root>
      <Field.Description>
        Last committed price: {savedPrice ?? 'empty'}
      </Field.Description>
    </Field.Root>
  );
};
```
```

--------------------------------

### Example output of PostgreSQL roles

Source: https://docs.twenty.com/developers/contribute/capabilities/local-setup

Example output showing the current roles in the database.

```text
 Role name | Attributes  | Member of
 ----------+-------------+-----------
 john      | Superuser   | {}
```

--------------------------------

### appInstall

Source: https://docs.twenty.com/developers/extend/apps/operations/testing

Installs the app on the active workspace. Returns a result object with success, data, or error.

```APIDOC
## appInstall

### Description
Installs the app on the active workspace.

### Function Signature
appInstall(options: { appPath: string }): Promise<Result>

### Parameters
- **appPath** (string) - Required - Path to the app directory.

### Return Value
Returns a result object with `success: boolean` and either `data` or `error`.

### Example
```typescript
const installResult = await appInstall({ appPath: APP_PATH });
```
```

--------------------------------

### Install Twenty SDK dependencies

Source: https://docs.twenty.com/developers/extend/apps/getting-started/local-server

Install the required SDK packages locally within your project to enable Twenty CLI commands.

```bash
yarn add twenty-sdk twenty-client-sdk
```

--------------------------------

### Install latest stable version

Source: https://docs.twenty.com/developers/self-host/capabilities/docker-compose

Use this command to install the latest stable version of Twenty.

```bash
bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
```
Tokens:
Raw