Skip to main content
Фронтенд-компоненты — это компоненты React, которые отображаются непосредственно внутри интерфейса Twenty. Они выполняются в изолированном Web Worker с использованием Remote DOM — ваш код изолирован (sandboxed), но рендерится нативно на странице, а не в iframe.

Где можно использовать фронт-компоненты

Фронт-компоненты могут отображаться в двух местах внутри Twenty:
  • Боковая панель — фронт-компоненты с интерфейсом открываются в правой боковой панели. Это поведение по умолчанию, когда фронт-компонент запускается из меню команд.
  • Виджеты (дашборды и страницы записей) — фронт-компоненты можно встраивать как виджеты в макеты страниц. При настройке дашборда или макета страницы записи пользователи могут добавить виджет фронт-компонента.
Сам по себе фронт-компонент недоступен из интерфейса — его нужно сделать доступным. Сделать это можно двумя способами:
  • Связать его с элементом командного меню — регистрирует его в командном меню (Cmd+K) и, при необходимости, как закреплённое быстрое действие.
  • Встроить его как виджет в макет страницы — размещает его на странице деталей записи или на дашборде.

Простой пример

Самый быстрый способ увидеть фронт-компонент в действии — связать его с defineCommandMenuItem, чтобы он появился как кнопка быстрого действия в правом верхнем углу страницы:
src/front-components/hello-world.tsx
src/command-menu-items/hello-world.command-menu-item.ts
После синхронизации с помощью yarn twenty dev (или однократного запуска yarn twenty dev --once) быстрое действие появится в правом верхнем углу страницы:
Кнопка быстрого действия в правом верхнем углу
Нажмите её, чтобы отобразить компонент инлайн.

Поля конфигурации

Размещение фронт-компонента на странице

Помимо команд, вы можете встроить фронт-компонент непосредственно на страницу записи, добавив его как виджет в макет страницы. См. макеты страниц для подробностей.

Headless и non-headless

Фронт-компоненты поддерживают два режима отображения, управляемых опцией isHeadless: Non-headless (по умолчанию) — компонент отображает видимый интерфейс. При запуске из меню команд он открывается в боковой панели. Это поведение по умолчанию, когда isHeadless имеет значение false или опущен. Headless (isHeadless: true) — компонент монтируется невидимо в фоновом режиме. Он не открывает боковую панель. Компоненты headless предназначены для действий, которые выполняют логику и затем размонтируются — например, запуск асинхронной задачи, переход на страницу или показ модального окна подтверждения. Они естественно сочетаются с компонентами SDK Command, описанными ниже.
src/front-components/sync-tracker.tsx
Поскольку компонент возвращает null, Twenty пропускает рендеринг контейнера для него — в макете не появляется пустое место. Компонент по-прежнему имеет доступ ко всем хукам и API взаимодействия с хостом.

Компоненты SDK Command

Пакет twenty-sdk предоставляет четыре вспомогательных компонента Command, предназначенных для headless фронт-компонентов. Каждый компонент выполняет действие при монтировании, обрабатывает ошибки, показывая уведомление snackbar, и автоматически размонтирует фронт-компонент по завершении. Импортируйте их из twenty-sdk/command:
  • Command — запускает асинхронный колбэк через проп execute.
  • CommandLink — переходит по пути внутри приложения. Пропы: to, params, queryParams, options.
  • CommandModal — открывает модальное окно подтверждения. Если пользователь подтвердит, выполняет колбэк execute. Пропы: title, subtitle, execute, confirmButtonText, confirmButtonAccent.
  • CommandOpenSidePanelPage — открывает страницу боковой панели. Пропсы зависят от page — например, ViewRecord принимает recordId + objectNameSingular, другие страницы принимают pageTitle + pageIcon.
Полный пример headless фронт-компонента, использующего Command для запуска действия из меню команд:
src/front-components/run-action.tsx
src/command-menu-items/run-action.command-menu-item.ts
А также пример с использованием CommandModal для запроса подтверждения перед выполнением:
src/front-components/delete-draft.tsx

Вызов логической функции

Front-компоненты выполняются в браузере в изолированном Web Worker, в то время как логические функции выполняются на стороне сервера. Между ними нет прямого внутрипроцессного вызова — вместо этого front-компонент обращается к логической функции по HTTP. Логическая функция, объявленная с httpRouteTriggerSettings, доступна по HTTP по своему пути маршрута. Twenty внедряет в воркер базовый URL, с которого обслуживаются ваши функции, в виде TWENTY_FUNCTIONS_URL вместе с TWENTY_APP_ACCESS_TOKEN, который аутентифицирует вызов. Пока что нет отдельного клиентского SDK для вызова ваших собственных функций, поэтому вызывайте их с помощью обычного fetch:
В Twenty Cloud логические функции с HTTP-триггером обслуживаются на выделенном домене для каждого рабочего пространства по адресу https://\<your-workspace-subdomain>.twenty.com\<path> — именно к этому и разрешается TWENTY_FUNCTIONS_URL. Для внешних вызовов скопируйте точный URL из настроек HTTP trigger функции или на вкладке Settings приложения.
Устаревший маршрут функции /s/ не рекомендуется к использованию и будет деактивирован 2026-07-24. Вместо этого используйте TWENTY_FUNCTIONS_URL (выше) и перенесите все жестко заданные URL вида /s/ до этой даты. Маршрут /s/ по-прежнему доступен при самостоятельном размещении (self-hosting).
Безголовый front-компонент может выполнить вызов при монтировании через компонент Command, а затем автоматически размонтироваться:
src/front-components/sync-prs.tsx
Путь, добавляемый к TWENTY_FUNCTIONS_URL, — это значение httpRouteTriggerSettings.path логической функции. Сохраните isAuthRequired: true; TWENTY_APP_ACCESS_TOKEN, который Twenty выпускает для вашего компонента, аутентифицирует запрос:
src/logic-functions/fetch-prs.logic-function.ts
TWENTY_FUNCTIONS_URL и TWENTY_APP_ACCESS_TOKEN внедряются автоматически — см. переменные приложения. Поскольку секретные переменные приложения никогда не раскрываются front-компонентам, храните ключи API и другую конфиденциальную логику в логической функции, а не во front-компоненте.

Вызов REST API Twenty

Чтобы читать или изменять записи Twenty из фронт-компонента, используйте RestApiClient из twenty-client-sdk/rest. Он принадлежит к тому же семейству клиентов, что и CoreApiClient и MetadataApiClient, но нацелен на REST API Twenty (/rest/...) вместо GraphQL API, считывая базовый URL из TWENTY_API_URL. В options принимаются headers, query (объект с параметрами строки запроса; значения, равные null или undefined, пропускаются) и AbortSignal через signal. Объект body, не являющийся FormData, автоматически сериализуется в JSON. При получении 401 клиент один раз обновляет токен доступа через хост и повторяет запрос. Базовый URL и токен по умолчанию берутся из окружения. При необходимости передавайте переопределения в конструктор — например, в тестах:
Неудачные запросы выбрасывают RestApiClientError, который содержит status, statusText, url и распарсенное body:

Доступ к контексту времени выполнения

Внутри вашего компонента используйте хуки SDK для доступа к текущему пользователю, записи и экземпляру компонента:
src/front-components/record-info.tsx
Доступные хуки:

Переменные приложения

Переменные приложения, определенные в defineApplication() с isSecret: false, доступны внутри фронтенд-компонентов через утилиту getApplicationVariable:
src/front-components/greeting.tsx
Секретные переменные (isSecret: true) не доступны фронтенд-компонентам. Они доступны только в логических функциях, которые выполняются на стороне сервера. Это предотвращает отправку в браузер конфиденциальных значений, таких как ключи API.
Следующие системные переменные всегда доступны через process.env:

API взаимодействия с хостом

Компоненты фронтенда могут вызывать навигацию, модальные окна и уведомления с помощью функций из twenty-sdk: Пример, который использует API хоста для показа snackbar и закрытия боковой панели после завершения действия:
src/front-components/archive-record.tsx

Работа с несколькими записями

Используйте useSelectedRecordIds() для обработки нескольких выбранных записей. Это полезно для массовых операций:
src/front-components/bulk-export.tsx

Публичные ресурсы

Компоненты фронтенда могут получать доступ к файлам из каталога приложения public/ с помощью getPublicAssetUrl:
См. раздел о публичных ресурсах для подробностей.

Стилизация

Компоненты фронтенда поддерживают несколько подходов к стилизации. Вы можете использовать:
  • Встроенные стилиstyle={{ color: 'red' }}
  • Twenty UI components — собственная библиотека компонентов Twenty; см. раздел Using Twenty UI components ниже
  • Emotion — CSS-in-JS с @emotion/react
  • Styled-components — паттерны styled.div
  • Tailwind CSS — утилитарные классы
  • Любая библиотека CSS-in-JS, совместимая с React

Использование компонентов Twenty UI

Twenty поставляет свою библиотеку компонентов как пакет twenty-ui. Компоненты фронтенда могут использовать его для кнопок, тегов, статусных плашек, чипов, аватаров, иконок, типографики и токенов темы, которые автоматически соответствуют светлой и тёмной теме рабочего пространства.

Установка

Добавьте пакет в своё приложение, зафиксировав его на версии, с которой поставляется ваш экземпляр Twenty:
twenty-ui включается в ваш компонент фронтенда на этапе сборки, поэтому его достаточно иметь в зависимостях вашего приложения — во время выполнения ничего настраивать не нужно.

Импорт компонентов

Импортируйте из соответствующего подпути, а не из корня пакета, чтобы в ваш бандл попали только те компоненты, которые вы используете:

Иконки

Импортируйте отдельные иконки из twenty-ui/icon:
Каждая именованная иконка участвует в tree-shaking, поэтому импорт нескольких иконок почти не увеличит размер вашего бандла. Избегайте IconsProvider, useIcons и iconsState — они подключают весь набор иконок Tabler (несколько мегабайт).

Темизация и токены темы

Компоненты Twenty UI автоматически подстраиваются под светлую и тёмную темы рабочего пространства — рендерер применяет активную цветовую схему на хосте, а компоненты вычисляют свои цвета относительно неё. Чтобы использовать те же дизайн‑токены в собственных встроенных стилях, вызовите хук useTheme(). Он возвращает токены темы Twenty (отступы, цвета, радиусы, шрифты), привязанные к активной теме, без необходимости настраивать ThemeProvider в вашем компоненте:
Поскольку useTheme() — это хук, вы читаете токены внутри тела компонента, поэтому значения всегда соответствуют активной теме. Та же карта токенов также экспортируется как константа themeCssVariables, но в компонентах фронтенда предпочтительнее использовать useTheme() — модульная константа, разыменующая themeCssVariables, может быть undefined, пока извлекается манифест приложения. Чтобы явно разветвлять логику по активной цветовой схеме, считайте её с помощью useColorScheme() из twenty-sdk/front-component, который возвращает 'light' или 'dark'.