Начало работы - Clara Documentation

Что такое приложения?

Приложения позволяют расширять Twenty с помощью пользовательских объектов, полей, логических функций, фронтенд-компонентов, навыков ИИ и многого другого — всё это управляется как код. Вместо настройки всего через интерфейс вы определяете модель данных и логику на TypeScript и развёртываете их в одном или нескольких рабочих пространствах.

Требования

Прежде чем начать, убедитесь, что на вашем компьютере установлено следующее:

Node.js 24+ — Скачать здесь
Yarn 4 — Поставляется вместе с Node.js через Corepack. Включите его, выполнив corepack enable
Docker — Скачать здесь. Требуется для запуска локального экземпляра Twenty. Не требуется, если у вас уже запущен сервер Twenty.

Создайте своё первое приложение

Сгенерируйте каркас приложения

Откройте терминал и выполните:

npx create-twenty-app@latest my-twenty-app

Вам будет предложено ввести имя и описание вашего приложения. Нажмите Enter, чтобы принять значения по умолчанию. Будет создана новая папка my-twenty-app со всем необходимым.

Настройте локальный экземпляр Twenty

Скэффолдер спросит:

Хотите настроить локальный экземпляр Twenty?

Введите yes (рекомендуется) — это скачает Docker-образ twenty-app-dev и запустит локальный сервер Twenty на порту 2020. Перед продолжением убедитесь, что Docker запущен.
Введите no — выберите это, если у вас уже запущен локальный сервер Twenty.

Войдите в своё рабочее пространство

Затем откроется окно браузера со страницей входа в Twenty. Войдите, используя предварительно созданную демонстрационную учётную запись:

Электронная почта: tim@apple.dev
Пароль: tim@apple.dev

Авторизуйте приложение

После входа вы увидите экран авторизации. Это позволит вашему приложению взаимодействовать с вашим рабочим пространством. Нажмите Authorize, чтобы продолжить.

После авторизации в терминале появится подтверждение, что всё настроено.

Начните разработку

Перейдите в папку вашего нового приложения и запустите сервер разработки:

cd my-twenty-app
yarn twenty dev

Он отслеживает исходные файлы, пересобирает при каждом изменении и автоматически синхронизирует ваше приложение с локальным сервером Twenty. В терминале должна появиться панель текущего статуса. Для более подробного вывода (журналы сборки, запросы синхронизации, трассировки ошибок) используйте флаг --verbose:

yarn twenty dev --verbose

Режим разработки доступен только на экземплярах Twenty, запущенных в режиме разработки (NODE_ENV=development). Экземпляры в продакшене отклоняют запросы синхронизации из режима разработки. Используйте yarn twenty deploy для развёртывания на продакшен-серверах — подробности см. в разделе Публикация приложений.

Разовая синхронизация с `yarn twenty dev --once`

Если вы не хотите, чтобы в фоновом режиме работал наблюдатель (например, в конвейере CI, хуке Git или скриптовом рабочем процессе), передайте флаг --once. Он запускает тот же конвейер, что и yarn twenty dev — собирает манифест, упаковывает файлы, загружает, синхронизирует, повторно генерирует типизированный клиент API — но выходит сразу после завершения синхронизации:

yarn twenty dev --once

Команда	Поведение	Когда использовать
`yarn twenty dev`	Отслеживает ваши исходные файлы и повторно синхронизирует при каждом изменении. Продолжает работать, пока вы его не остановите.	Интерактивная локальная разработка — вам нужна панель статуса в реальном времени и мгновенная обратная связь.
`yarn twenty dev --once`	Выполняет одну сборку и синхронизацию, затем завершает работу с кодом `0` при успехе или `1` при ошибке.	Скрипты, CI, хуки pre-commit, AI-агенты и любые неинтерактивные рабочие процессы.

Оба режима требуют сервер Twenty, запущенный в режиме разработки, и аутентифицированный удалённый ресурс — действуют те же предварительные требования.

Посмотрите своё приложение в Twenty

Откройте http://localhost:2020/settings/applications#developer в браузере. Перейдите в Settings > Apps и выберите вкладку Developer. Вы должны увидеть своё приложение в разделе Your Apps:

Список Your Apps с приложением My twenty app

Нажмите My twenty app, чтобы открыть его регистрацию приложения. Регистрация — это запись на уровне сервера, описывающая ваше приложение: его имя, уникальный идентификатор, учётные данные OAuth и источник (локальный, npm или tarball). Она хранится на сервере, а не внутри какого-либо конкретного рабочего пространства. Когда вы устанавливаете приложение в рабочее пространство, Twenty создаёт привязанное к рабочему пространству приложение, которое ссылается на эту регистрацию. Одну и ту же регистрацию можно установить в нескольких рабочих пространствах на одном сервере.

Нажмите View installed app, чтобы посмотреть установленное приложение. Вкладка About показывает текущую версию и параметры управления:

Переключитесь на вкладку Content, чтобы увидеть всё, что предоставляет ваше приложение: объекты, поля, логические функции и агенты:

Установленное приложение — вкладка Content

Готово! Отредактируйте любой файл в src/, и изменения будут подхвачены автоматически.

Что вы можете создать

Приложения состоят из сущностей — каждая определена как файл TypeScript с одним export default:

Сущность	Что делает
Объекты и поля	Определяйте пользовательские модели данных (например, Post Card, Invoice) с типизированными полями
Логические функции	Серверные функции на TypeScript, запускаемые HTTP-маршрутами, расписаниями cron или событиями базы данных
Фронтенд-компоненты	React-компоненты, которые отображаются внутри интерфейса Twenty (боковая панель, виджеты, командное меню)
Навыки и агенты	Возможности ИИ — многократно используемые инструкции и автономные помощники
Представления и навигация	Предварительно настроенные представления списков и элементы бокового меню для ваших объектов
Макеты страниц	Пользовательские страницы сведений о записи с вкладками и виджетами

Перейдите к разделу Создание приложений, чтобы получить подробное руководство по каждому типу сущности.

Структура проекта

Инструмент генерации каркаса создаёт следующую структуру файлов:

my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .oxlintrc.json
  tsconfig.json
  tsconfig.spec.json                          # TypeScript config for tests
  vitest.config.ts                            # Vitest test runner configuration
  LLMS.md
  README.md
  .github/
    └── workflows/
        └── ci.yml                            # GitHub Actions CI workflow
  public/                                     # Public assets (images, fonts, etc.)
  src/
  ├── application-config.ts                   # Required — main application configuration
  ├── default-role.ts                         # Default role for logic functions
  ├── constants/
  │   └── universal-identifiers.ts            # Auto-generated UUIDs and app metadata
  └── __tests__/
      ├── setup-test.ts                       # Test setup (server health check, config)
      └── app-install.integration-test.ts     # Integration test

Начните с примера

Чтобы начать с более полного примера с пользовательскими объектами, полями, логическими функциями, фронтенд-компонентами и многим другим, используйте флаг --example:

npx create-twenty-app@latest my-twenty-app --example postcard

Примеры берутся из каталога twenty-apps/examples на GitHub. Вы также можете сгенерировать каркас отдельных сущностей в существующем проекте с помощью yarn twenty add (см. Создание приложений).

Ключевые файлы

Файл / Папка	Назначение
`package.json`	Содержит имя, версию и зависимости вашего приложения. Содержит скрипт `twenty`, чтобы вы могли выполнить `yarn twenty help` и увидеть все команды.
`src/application-config.ts`	Обязательно. Основной файл конфигурации для вашего приложения.
`src/default-role.ts`	Роль по умолчанию, которая контролирует, к чему имеют доступ ваши логические функции.
`src/constants/universal-identifiers.ts`	Автоматически генерируемые UUID и метаданные приложения (отображаемое имя, описание).
`src/__tests__/`	Интеграционные тесты (настройка + пример теста).
`public/`	Статические ресурсы (изображения, шрифты), обслуживаемые вместе с вашим приложением.

Локальный сервер разработки

Генератор каркаса уже запустил для вас локальный сервер Twenty. Чтобы управлять им позже, используйте yarn twenty server:

Команда	Описание
`yarn twenty server start`	Запустить локальный сервер (при необходимости скачивает образ)
`yarn twenty server start --port 3030`	Запустить на пользовательском порту
`yarn twenty server start --test`	Запускает отдельный тестовый экземпляр на порту 2021
`yarn twenty server stop`	Остановить сервер (данные сохраняются)
`yarn twenty server status`	Показать состояние сервера, URL и учётные данные
`yarn twenty server logs`	Потоковый вывод журналов сервера
`yarn twenty server logs --lines 100`	Показать последние 100 строк журнала
`yarn twenty server reset`	Удалить все данные и начать с чистого листа

Данные сохраняются между перезапусками в двух томах Docker (twenty-app-dev-data для PostgreSQL, twenty-app-dev-storage для файлов). Используйте reset, чтобы стереть всё и начать заново.

Запуск тестового экземпляра

Передайте --test любой команде server, чтобы управлять вторым, полностью изолированным экземпляром — это полезно для запуска интеграционных тестов или экспериментов, не затрагивая ваши основные данные разработки.

Команда	Описание
`yarn twenty server start --test`	Запустить тестовый экземпляр (по умолчанию — порт 2021)
`yarn twenty server stop --test`	Остановить тестовый экземпляр
`yarn twenty server status --test`	Показать состояние тестового экземпляра, URL и учётные данные
`yarn twenty server logs --test`	Выводить журналы тестового экземпляра в потоковом режиме
`yarn twenty server reset --test`	Удалить тестовые данные и начать с чистого листа

Тестовый экземпляр запускается в собственном контейнере Docker (twenty-app-dev-test) с выделенными томами (twenty-app-dev-test-data, twenty-app-dev-test-storage) и собственной конфигурацией, поэтому он может работать параллельно с вашим основным экземпляром без конфликтов. Совместите --test с --port, чтобы переопределить значение по умолчанию (2021).

Для работы сервера необходимо, чтобы Docker был запущен. Если вы видите ошибку “Docker not running”, убедитесь, что запущен Docker Desktop (или демон Docker).

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

Если вы предпочитаете настроить всё самостоятельно, не используя create-twenty-app, это можно сделать в два шага. 1. Добавьте twenty-sdk и twenty-client-sdk в зависимости:

yarn add twenty-sdk twenty-client-sdk

2. Добавьте скрипт twenty в ваш package.json:

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

Теперь вы можете запускать yarn twenty dev, yarn twenty help и все остальные команды.

Не устанавливайте twenty-sdk глобально. Всегда используйте его как локальную зависимость проекта, чтобы каждый проект мог закреплять свою версию.

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

Если столкнётесь с проблемами:

Перед запуском генератора с локальным экземпляром убедитесь, что Docker запущен.
Убедитесь, что используете Node.js 24+ (node -v для проверки).
Убедитесь, что Corepack включён (corepack enable), чтобы Yarn 4 был доступен.
Если зависимости, похоже, повреждены, попробуйте удалить node_modules и снова выполнить yarn install.

Все ещё не получается? Попросите помощи на Discord-сервере Twenty.

​Что такое приложения?

​Требования

​Создайте своё первое приложение

​Сгенерируйте каркас приложения

​Настройте локальный экземпляр Twenty

​Войдите в своё рабочее пространство

​Авторизуйте приложение

​Начните разработку

​Разовая синхронизация с yarn twenty dev --once

​Посмотрите своё приложение в Twenty

​Что вы можете создать

​Структура проекта

​Начните с примера

​Ключевые файлы

​Локальный сервер разработки

​Запуск тестового экземпляра

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

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

Что такое приложения?

Требования

Создайте своё первое приложение

Сгенерируйте каркас приложения

Настройте локальный экземпляр Twenty

Войдите в своё рабочее пространство

Авторизуйте приложение

Начните разработку

Разовая синхронизация с `yarn twenty dev --once`

Посмотрите своё приложение в Twenty

Что вы можете создать

Структура проекта

Начните с примера

Ключевые файлы

Локальный сервер разработки

Запуск тестового экземпляра

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

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