Documentation Index
Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
Use this file to discover all available pages before exploring further.
Что такое приложения?
Приложения позволяют расширять Twenty с помощью пользовательских объектов, полей, логических функций, фронтенд-компонентов, навыков ИИ и многого другого — всё это управляется как код. Вместо настройки всего через интерфейс вы определяете модель данных и логику на TypeScript и развёртываете их в одном или нескольких рабочих пространствах.
Требования
Прежде чем начать, убедитесь, что на вашем компьютере установлено следующее:
- Node.js 24+ — Скачать здесь
- Yarn 4 — Поставляется вместе с Node.js через Corepack. Включите его, выполнив
corepack enable
- Docker — Скачать здесь. Требуется для запуска локального экземпляра Twenty. Не требуется, если у вас уже запущен сервер Twenty.
Создайте своё первое приложение
Сгенерируйте каркас приложения
Откройте терминал и выполните:
npx create-twenty-app@latest my-twenty-app
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
--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 | Отслеживает ваши исходные файлы и повторно синхронизирует при каждом изменении. Продолжает работать, пока вы его не остановите. | Интерактивная локальная разработка — вам нужна панель статуса в реальном времени и мгновенная обратная связь. |
yarn twenty dev --once | Выполняет одну сборку и синхронизацию, затем завершает работу с кодом 0 при успехе или 1 при ошибке. | Скрипты, CI, хуки pre-commit, AI-агенты и любые неинтерактивные рабочие процессы. |
Посмотрите своё приложение в Twenty
Откройте http://localhost:2020/settings/applications#developer в браузере. Перейдите в Settings > Apps и выберите вкладку Developer. Вы должны увидеть своё приложение в разделе Your Apps:
Нажмите My twenty app, чтобы открыть его регистрацию приложения. Регистрация — это запись на уровне сервера, описывающая ваше приложение: его имя, уникальный идентификатор, учётные данные OAuth и источник (локальный, npm или tarball). Она хранится на сервере, а не внутри какого-либо конкретного рабочего пространства. Когда вы устанавливаете приложение в рабочее пространство, Twenty создаёт привязанное к рабочему пространству приложение, которое ссылается на эту регистрацию. Одну и ту же регистрацию можно установить в нескольких рабочих пространствах на одном сервере.
Нажмите View installed app, чтобы посмотреть установленное приложение. Вкладка About показывает текущую версию и параметры управления:
Переключитесь на вкладку 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
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 | Удалить все данные и начать с чистого листа |
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 | Удалить тестовые данные и начать с чистого листа |
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
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.
