Начало работы

• Определяйте пользовательские объекты и поля в виде кода (управляемая модель данных)
• Создавайте логические функции с пользовательскими триггерами (HTTP-маршруты, cron, события базы данных)
• Определяйте навыки для ИИ-агентов
• Создавайте фронтенд-компоненты, которые отображаются внутри интерфейса Twenty
• Развёртывайте одно и то же приложение в нескольких рабочих пространствах

​

Требования

• Node.js 24+ и Yarn 4
• Рабочее пространство Twenty и ключ API (создайте его на https://app.twenty.com/settings/api-webhooks)

​

Начало работы

# Scaffold a new app (includes all examples by default)
npx create-twenty-app@latest my-twenty-app
cd my-twenty-app

# Start dev mode: automatically syncs local changes to your workspace
yarn twenty app:dev

# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
npx create-twenty-app@latest my-app

# Minimal: only core files (application-config.ts and default-role.ts)
npx create-twenty-app@latest my-app --minimal

# Add a new entity to your application (guided)
yarn twenty entity:add

# Watch your application's function logs
yarn twenty function:logs

# Execute a function by name
yarn twenty function:execute -n my-function -p '{"name": "test"}'

# Execute the pre-install function
yarn twenty function:execute --preInstall

# Execute the post-install function
yarn twenty function:execute --postInstall

# Uninstall the application from the current workspace
yarn twenty app:uninstall

# Display commands' help
yarn twenty help

​

Структура проекта (сгенерированного)

• Копирует минимальное базовое приложение в my-twenty-app/
• Добавляет локальную зависимость twenty-sdk и конфигурацию Yarn 4
• Создаёт файлы конфигурации и скрипты, подключённые к CLI twenty
• Генерирует основные файлы (конфигурацию приложения, роль функций по умолчанию, предустановочную и послеустановочную функции), а также примерные файлы в зависимости от выбранного режима создания каркаса

my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .yarn/
    install-state.gz
  .oxlintrc.json
  tsconfig.json
  README.md
  public/                           # Public assets folder (images, fonts, etc.)
  src/
  ├── application-config.ts           # Required - main application configuration
  ├── roles/
  │   └── default-role.ts               # Default role for logic functions
  ├── objects/
  │   └── example-object.ts             # Example custom object definition
  ├── fields/
  │   └── example-field.ts              # Example standalone field definition
  ├── logic-functions/
  │   ├── hello-world.ts                # Example logic function
  │   ├── pre-install.ts                # Pre-install logic function
  │   └── post-install.ts               # Post-install logic function
  ├── front-components/
  │   └── hello-world.tsx               # Example front component
  ├── views/
  │   └── example-view.ts                # Example saved view definition
  ├── navigation-menu-items/
  │   └── example-navigation-menu-item.ts # Example sidebar navigation link
  └── skills/
      └── example-skill.ts                # Example AI agent skill definition

• package.json: Объявляет имя приложения, версию, движки (Node 24+, Yarn 4) и добавляет twenty-sdk, а также скрипт twenty, который делегирует выполнение локальному CLI twenty. Выполните yarn twenty help, чтобы вывести список всех доступных команд.
• .gitignore: Игнорирует распространённые артефакты, такие как node_modules, .yarn, generated/ (типизированный клиент), dist/, build/, каталоги coverage, файлы журналов и файлы .env*.
• yarn.lock, .yarnrc.yml, .yarn/: Фиксируют и настраивают используемый в проекте инструментарий Yarn 4.
• .nvmrc: Фиксирует версию Node.js, ожидаемую проектом.
• .oxlintrc.json и tsconfig.json: Обеспечивают линтинг и конфигурацию TypeScript для исходников вашего приложения на TypeScript.
• README.md: Короткий README в корне приложения с базовыми инструкциями.
• public/: Папка для хранения общедоступных ресурсов (изображений, шрифтов, статических файлов), которые будут отдаваться вашим приложением. Файлы, размещённые здесь, загружаются во время синхронизации и доступны во время выполнения.
• src/: Основное место, где вы определяете приложение как код

​

Обнаружение сущностей

// This file can be named anything and placed anywhere in src/
import { defineObject, FieldType } from 'twenty-sdk';

export default defineObject({
  universalIdentifier: '...',
  nameSingular: 'postCard',
  // ... rest of config
});

• yarn twenty app:dev автоматически сгенерирует два типизированных клиента API в node_modules/twenty-sdk/generated: CoreApiClient (для данных рабочего пространства через /graphql) и MetadataApiClient (для конфигурации рабочего пространства и загрузки файлов через /metadata).
• yarn twenty entity:add добавит файлы определений сущностей в src/ для ваших пользовательских объектов, функций, фронтенд-компонентов, ролей, навыков и многого другого.

​

Аутентификация

• URL API (по умолчанию http://localhost:3000 или текущий профиль рабочего пространства)
• Ключ API

​

Управление рабочими пространствами

# Login interactively (recommended)
yarn twenty auth:login

# Login to a specific workspace profile
yarn twenty auth:login --workspace my-custom-workspace

# List all configured workspaces
yarn twenty auth:list

# Switch the default workspace (interactive)
yarn twenty auth:switch

# Switch to a specific workspace
yarn twenty auth:switch production

# Check current authentication status
yarn twenty auth:status

​

Ручная настройка (без генератора)

yarn add -D twenty-sdk

{
  "scripts": {
    "twenty": "twenty"
  }
}

​

Устранение неполадок

• Ошибки аутентификации: выполните yarn twenty auth:login и убедитесь, что у вашего ключа API есть необходимые права.
• Не удаётся подключиться к серверу: проверьте URL API и доступность сервера Twenty.
• Типы или клиент отсутствуют/устарели: перезапустите yarn twenty app:dev — он автоматически генерирует типизированный клиент.
• Режим разработки не синхронизируется: убедитесь, что запущен yarn twenty app:dev, и что ваша среда не игнорирует изменения.