Понятия

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

Как работают приложения

Приложение — это набор сущностей, объявленных с помощью функций defineEntity() из пакета twenty-sdk. SDK обнаруживает эти объявления посредством анализа AST на этапе сборки и формирует манифест — полное описание того, что ваше приложение добавляет в рабочее пространство. Эти функции проверяют вашу конфигурацию на этапе сборки и обеспечивают автодополнение в IDE и безопасность типов.

your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json

Организация файлов — на ваше усмотрение. Обнаружение сущностей основано на AST — SDK находит вызовы export default defineEntity(...) независимо от расположения файла. Структура папок выше — это соглашение, а не требование.

Типы сущностей

Сущность	Назначение	Документация
Приложение	Идентификация приложения, роль по умолчанию, переменные	Конфигурация приложения
Роль	Наборы прав для объектов и полей	Роли и разрешения
Объект	Пользовательские типы записей с полями	Объекты
Поле	Добавляйте поля к объектам из других приложений	Расширение объектов
Связь	Двунаправленные связи между объектами	Связи
Логическая функция	Серверный TypeScript с триггерами	Логические функции
Навык	Повторно используемые инструкции для ИИ-агента	Навыки и агенты
Агент	ИИ-агенты с пользовательскими промптами	Навыки и агенты
Провайдер подключения	Учётные данные OAuth для сторонних API	Подключения
Представление	Преднастроенные представления списков записей	Представления
Пункт меню навигации	Пользовательские элементы боковой панели	Элементы меню навигации
Макет страницы	Вкладки и виджеты на странице сведений о записи	Макеты страниц
Компонент фронтенда	Изолированный в песочнице интерфейс React внутри Twenty	Компоненты фронтенда
Общие зависимости	Зависимости, общие для фронтенд-компонентов приложения, указанные в package.json	Общие зависимости
Элемент меню команд	Быстрые действия и элементы Cmd+K	Элементы меню команд

Изоляция в песочнице

Логические функции выполняются в изолированных процессах Node.js на сервере. Они получают доступ к данным только через типизированный API-клиент, который действует либо от имени человека, запустившего выполнение, либо от имени самого приложения. См. Чей доступ использует вызов.
Компоненты фронтенда запускаются в Web Workers с использованием Remote DOM — изолированы от основной страницы, но при этом рендерят нативные элементы DOM (не iframes). Они взаимодействуют с Twenty через хостовый API обмена сообщениями.
Права доступа применяются на уровне API. Внедряются два токена времени выполнения, оба производные от роли, объявленной с помощью defineApplicationRole(); область действия токена по умолчанию дополнительно ограничивается тем, что может делать человек, запустивший выполнение, когда за выполнением стоит человек.

Жизненный цикл приложения

┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘

yarn twenty dev — следит за исходными файлами и синхронизирует изменения в реальном времени с подключённым сервером Twenty. Типизированный клиент API автоматически пересоздаётся при изменении схемы.
yarn twenty dev:build — компилирует TypeScript, упаковывает логические функции и фронтенд-компоненты с помощью esbuild и формирует манифест.
Хуки до/после установки и удаления — необязательные функции, которые выполняются во время установки или непосредственно перед удалением. См. раздел Install Hooks для подробностей.

Следующие шаги

Конфигурация

Идентификация приложения, роль по умолчанию, а также хуки установки и удаления.

Данные

Объекты, поля и двунаправленные связи.

Логика

Логические функции, навыки, агенты и OAuth-подключения.

Макет

Представления, навигация, макеты страниц, фронтенд-компоненты.

Операции

CLI, тестирование, удаленные окружения, CI и публикация вашего приложения.

Обзор

Приложения

API

Самостоятельный хостинг

Внести вклад

Как работают приложения

Типы сущностей

Изоляция в песочнице

Жизненный цикл приложения

Следующие шаги

Конфигурация

Данные

Логика

Макет

Операции

​Как работают приложения

​Типы сущностей

​Изоляция в песочнице

​Жизненный цикл приложения

​Следующие шаги

Конфигурация

Данные

Логика

Макет

Операции

Как работают приложения

Типы сущностей

Изоляция в песочнице

Жизненный цикл приложения

Следующие шаги