Что такое приложения?
Приложения позволяют создавать и управлять настройками Twenty в виде кода. Вместо настройки всего через интерфейс вы определяете модель данных и логические функции в коде — так быстрее создавать, поддерживать и развёртывать в нескольких рабочих пространствах. Что вы можете делать уже сегодня:- Определяйте пользовательские объекты и поля в виде кода (управляемая модель данных)
- Создавайте логические функции с пользовательскими триггерами
- Развёртывайте одно и то же приложение в нескольких рабочих пространствах
Требования
- Node.js 24+ и Yarn 4
- Рабочее пространство Twenty и ключ API (создайте его на https://app.twenty.com/settings/api-webhooks)
Начало работы
Создайте новое приложение с помощью официального генератора, затем выполните аутентификацию и начните разработку:Структура проекта (сгенерированного)
Когда вы запускаетеnpx create-twenty-app@latest my-twenty-app, генератор:
- Копирует минимальное базовое приложение в
my-twenty-app/ - Добавляет локальную зависимость
twenty-sdkи конфигурацию Yarn 4 - Создаёт файлы конфигурации и скрипты, подключённые к CLI
twenty - Генерирует конфигурацию приложения по умолчанию и роль функции по умолчанию
- package.json: Declares the app name, version, engines (Node 24+, Yarn 4), and adds
twenty-sdkplus atwentyscript that delegates to the localtwentyCLI. Runyarn twenty helpto list all available commands. - .gitignore: Игнорирует распространённые артефакты, такие как
node_modules,.yarn,generated/(типизированный клиент),dist/,build/, каталоги coverage, файлы журналов и файлы.env*. - yarn.lock, .yarnrc.yml, .yarn/: Фиксируют и настраивают используемый в проекте инструментарий Yarn 4.
- .nvmrc: Фиксирует версию Node.js, ожидаемую проектом.
- eslint.config.mjs и tsconfig.json: Обеспечивают линтинг и конфигурацию TypeScript для исходников вашего приложения на TypeScript.
- README.md: Короткий README в корне приложения с базовыми инструкциями.
- public/: Папка для хранения общедоступных ресурсов (изображений, шрифтов, статических файлов), которые будут отдаваться вашим приложением. Файлы, размещённые здесь, загружаются во время синхронизации и доступны во время выполнения.
- src/: Основное место, где вы определяете приложение как код
Обнаружение сущностей
SDK обнаруживает сущности, разбирая ваши файлы TypeScript в поисках вызововexport default define<Entity>({...}). Для каждого типа сущности существует соответствующая вспомогательная функция, экспортируемая из twenty-sdk:
| Вспомогательная функция | Тип сущности |
|---|---|
defineObject() | Определения пользовательских объектов |
defineLogicFunction() | Определения логических функций |
defineFrontComponent() | Определения компонентов фронтенда |
defineRole() | Определения ролей |
defineField() | Расширения полей для существующих объектов |
Имена файлов заданы гибко. Обнаружение сущностей основано на AST — SDK сканирует ваши исходные файлы в поисках шаблона
export default define<Entity>({...}). Вы можете организовывать файлы и папки как угодно. Группировка по типу сущности (например, logic-functions/, roles/) — это лишь соглашение для организации кода, а не требование.yarn twenty app:generatewill create agenerated/folder (typed Twenty client + workspace types).yarn twenty entity:addwill add entity definition files undersrc/for your custom objects, functions, front components, or roles.
Аутентификация
The first time you runyarn twenty auth:login, you’ll be prompted for:
- URL API (по умолчанию http://localhost:3000 или текущий профиль рабочего пространства)
- Ключ API
~/.twenty/config.json. Вы можете хранить несколько профилей и переключаться между ними.
Управление рабочими пространствами
yarn twenty auth:switch, all subsequent commands will use that workspace by default. Вы по-прежнему можете временно переопределить это с помощью --workspace <name>.
Используйте ресурсы SDK (типы и конфигурация)
Пакет twenty-sdk предоставляет типизированные строительные блоки и вспомогательные функции, которые вы используете внутри своего приложения. Ниже — ключевые части, с которыми вы будете работать чаще всего.Вспомогательные функции
SDK предоставляет вспомогательные функции для определения сущностей вашего приложения. Как описано в Обнаружение сущностей, вы должны использоватьexport default define<Entity>({...}), чтобы ваши сущности были обнаружены:
| Функция | Назначение |
|---|---|
defineApplication() | Настройка метаданных приложения (обязательно, по одному на приложение) |
defineObject() | Определяет пользовательские объекты с полями |
defineLogicFunction() | Определение логических функций с обработчиками |
defineFrontComponent() | Определение фронт-компонентов для настраиваемого интерфейса |
defineRole() | Настраивает права роли и доступ к объектам |
defineField() | Расширение существующих объектов дополнительными полями |
Определение объектов
Пользовательские объекты описывают как схему, так и поведение записей в вашем рабочем пространстве. ИспользуйтеdefineObject() для определения объектов со встроенной валидацией:
- Используйте
defineObject()для встроенной валидации и лучшей поддержки в IDE. universalIdentifierдолжен быть уникальным и стабильным между развёртываниями.- Каждому полю требуются
name,type,labelи собственный стабильныйuniversalIdentifier. - Массив
fieldsнеобязателен — вы можете определять объекты без пользовательских полей. - You can scaffold new objects using
yarn twenty entity:add, which guides you through naming, fields, and relationships.
Базовые поля создаются автоматически. Когда вы определяете пользовательский объект, Twenty автоматически добавляет стандартные поля, такие как
name, createdAt, updatedAt, createdBy, position и deletedAt. Вам не нужно определять их в массиве fields — добавляйте только свои пользовательские поля.Конфигурация приложения (application-config.ts)
У каждого приложения есть единственный файлapplication-config.ts, который описывает:
- Что это за приложение: идентификаторы, отображаемое имя и описание.
- Как запускаются его функции: какую роль они используют для прав доступа.
- (Необязательно) переменные: пары ключ-значение, предоставляемые вашим функциям как переменные окружения.
defineApplication() для определения конфигурации вашего приложения:
universalIdentifier— это детерминированные идентификаторы, которыми вы управляете; сгенерируйте их один раз и сохраняйте стабильными между синхронизациями.applicationVariablesстановятся переменными окружения для ваших функций (например,DEFAULT_RECIPIENT_NAMEдоступна какprocess.env.DEFAULT_RECIPIENT_NAME).defaultRoleUniversalIdentifierдолжен соответствовать файлу роли (см. ниже).
Роли и разрешения
Приложения могут определять роли, инкапсулирующие права на объекты и действия в вашем рабочем пространстве. ПолеdefaultRoleUniversalIdentifier в application-config.ts обозначает роль по умолчанию, используемую логическими функциями вашего приложения.
- Ключ API во время выполнения, подставляемый как
TWENTY_API_KEY, получается из этой роли функции по умолчанию. - Типизированный клиент будет ограничен правами, предоставленными этой ролью.
- Следуйте принципу наименьших привилегий: создайте отдельную роль только с теми правами, которые нужны вашим функциям, и укажите её универсальный идентификатор.
Роль функции по умолчанию (*.role.ts)
Когда вы генерируете новое приложение, CLI также создаёт файл роли по умолчанию. ИспользуйтеdefineRole() для определения ролей со встроенной валидацией:
universalIdentifier этой роли затем указывается в application-config.ts как defaultRoleUniversalIdentifier. Иными словами:
- *.role.ts определяет, что может делать роль функции по умолчанию.
- application-config.ts указывает на эту роль, чтобы ваши функции наследовали её права.
- Начните со сгенерированной роли, затем постепенно ограничивайте её, следуя принципу наименьших привилегий.
- Замените
objectPermissionsиfieldPermissionsна объекты/поля, которые нужны вашим функциям. permissionFlagsуправляют доступом к возможностям на уровне платформы. Держите их минимальными; добавляйте только то, что нужно.- См. рабочий пример в приложении Hello World:
packages/twenty-apps/hello-world/src/roles/function-role.ts.
Конфигурация логической функции и точка входа
Каждый файл функции используетdefineLogicFunction() для экспорта конфигурации с обработчиком и необязательными триггерами.
- route: Публикует вашу функцию по HTTP-пути и методу под конечной точкой
/s/:
например,path: '/post-card/create',-> вызов по адресу<APP_URL>/s/post-card/create
- cron: Запускает вашу функцию по расписанию с использованием выражения CRON.
- databaseEvent: Запускается при событиях жизненного цикла объектов рабочего пространства. Когда операция события —
updated, можно указать конкретные поля для отслеживания в массивеupdatedFields. Если оставить не заданным или пустым, любое обновление будет вызывать функцию.
например, person.updated
Заметки:
- Массив
triggersнеобязателен. Функции без триггеров можно использовать как вспомогательные, вызываемые другими функциями. - Вы можете сочетать несколько типов триггеров в одной функции.
Полезная нагрузка триггера маршрута
Когда триггер маршрута вызывает вашу логическую функцию, она получает объектRoutePayload, соответствующий формату AWS HTTP API v2. Импортируйте тип из twenty-sdk:
RoutePayload имеет следующую структуру:
| Свойство | Тип | Описание |
|---|---|---|
headers | Record<string, string | undefined> | HTTP-заголовки (только перечисленные в forwardedRequestHeaders) |
queryStringParameters | Record<string, string | undefined> | Параметры строки запроса (несколько значений объединяются запятыми) |
pathParameters | Record<string, string | undefined> | Параметры пути, извлечённые из шаблона маршрута (например, /users/:id → { id: '123' }) |
текст | object | null | Разобранное тело запроса (JSON) |
isBase64Encoded | логический тип | Является ли тело закодированным в base64 |
requestContext.http.method | строка | Метод HTTP (GET, POST, PUT, PATCH, DELETE) |
requestContext.http.path | строка | Необработанный путь запроса |
Проброс HTTP-заголовков
По умолчанию HTTP-заголовки из входящих запросов не передаются в вашу логическую функцию по соображениям безопасности. Чтобы получить доступ к определённым заголовкам, явно перечислите их в массивеforwardedRequestHeaders:
Имена заголовков приводятся к нижнему регистру. Обращайтесь к ним, используя ключи в нижнем регистре (например,
event.headers['content-type']).- Scaffolded: Run
yarn twenty entity:addand choose the option to add a new logic function. Это создаёт стартовый файл с обработчиком и конфигурацией. - Вручную: Создайте новый файл
*.logic-function.tsи используйтеdefineLogicFunction(), следуя тому же шаблону.
Фронт-компоненты
Фронт-компоненты позволяют создавать пользовательские компоненты React, которые рендерятся внутри интерфейса Twenty. ИспользуйтеdefineFrontComponent() для определения компонентов со встроенной валидацией:
- Фронт-компоненты — это компоненты React, которые рендерятся в изолированных контекстах внутри Twenty.
- Используйте суффикс файла
*.front-component.tsxдля автоматического обнаружения. - Поле
componentссылается на ваш компонент React. - Components are built and synced automatically during
yarn twenty app:dev.
- Scaffolded: Run
yarn twenty entity:addand choose the option to add a new front component. - Вручную: Создайте новый файл
*.front-component.tsxи используйтеdefineFrontComponent().
Сгенерированный типизированный клиент
Runyarn twenty app:generate to create a local typed client in generated/ based on your workspace schema. Используйте его в своих функциях:
yarn twenty app:generate. Запускайте повторно после изменения ваших объектов или при подключении к новому рабочему пространству.
Учётные данные времени выполнения в логических функциях
Когда ваша функция запускается на Twenty, платформа подставляет учётные данные как переменные окружения перед выполнением вашего кода:TWENTY_API_URL: Базовый URL API Twenty, на который нацелено ваше приложение.TWENTY_API_KEY: Краткоживущий ключ, ограниченный ролью функции по умолчанию вашего приложения.
- Вам не нужно передавать URL или ключ API сгенерированному клиенту. Он читает
TWENTY_API_URLиTWENTY_API_KEYиз process.env во время выполнения. - Права ключа API определяются ролью, на которую ссылается ваш
application-config.tsчерезdefaultRoleUniversalIdentifier. Это роль по умолчанию, используемая логическими функциями вашего приложения. - Приложения могут определять роли, чтобы следовать принципу наименьших привилегий. Предоставляйте только те права, которые нужны вашим функциям, затем укажите в
defaultRoleUniversalIdentifierуниверсальный идентификатор этой роли.
Пример Hello World
Ознакомьтесь с минимальным сквозным примером, демонстрирующим объекты, логические функции, фронт-компоненты и несколько триггеров, здесь:Ручная настройка (без генератора)
Хотя мы рекомендуем использоватьcreate-twenty-app для наилучшего старта, вы также можете настроить проект вручную. Не устанавливайте CLI глобально. Instead, add twenty-sdk as a local dependency and wire a single script in your package.json:
twenty script:
yarn twenty <command>, e.g. yarn twenty app:dev, yarn twenty app:generate, yarn twenty help, etc.
Устранение неполадок
- Authentication errors: run
yarn twenty auth:loginand ensure your API key has the required permissions. - Не удаётся подключиться к серверу: проверьте URL API и доступность сервера Twenty.
- Types or client missing/outdated: run
yarn twenty app:generate. - Dev mode not syncing: ensure
yarn twenty app:devis running and that changes are not ignored by your environment.