Требования
- Node.js 24+ — Скачать здесь
- Yarn 4 — поставляется вместе с Node.js через Corepack. Включите его, выполнив
corepack enable
- Docker — Скачать здесь. Требуется для запуска локального экземпляра Twenty. Пропустите, если у вас уже запущен Twenty в другом месте.
Создание приложения Twenty включает три фазы. Генератор каркаса объединяет их в одну команду для идеального сценария (happy path), но каждая фаза — отдельная концепция: когда что-то идёт не так, понимание того, на какой фазе вы находитесь, подскажет, что исправить.
| Фаза | Что вы делаете | Инструмент | Результат |
|---|
| 1. Создание каркаса | Сгенерировать исходный код приложения | npx create-twenty-app | Проект TypeScript на диске |
| 2. Запустить сервер | Запустить сервер Twenty для синхронизации | Docker + yarn twenty server | Запущенный экземпляр Twenty |
| 3. Синхронизация | Синхронизируйте код с сервером в реальном времени | yarn twenty dev | Ваши изменения появляются в интерфейсе |
Фаза 1 — Сгенерируйте каркас проекта
Создайте новое приложение из шаблона:
npx create-twenty-app@latest my-twenty-app
my-twenty-app/ с начальным файлом application-config.ts, ролью по умолчанию, рабочим процессом CI и интеграционным тестом.
После этой фазы: у вас есть исходный код приложения на вашем компьютере. Он ещё не запущен — это фаза 2.
Фаза 2 — Запустите локальный сервер Twenty
Вашему приложению нужен сервер Twenty для синхронизации. Сервер — это полноценный экземпляр Twenty — UI, GraphQL API, PostgreSQL — работающий локально в Docker. Ваш локальный код загружает свои определения на этот сервер, благодаря чему они появляются в интерфейсе.
Генератор каркаса предложит запустить его за вас:
Хотите настроить локальный экземпляр Twenty?
- Да (рекомендуется) — скачивает Docker-образ
twentycrm/twenty-app-dev и запускает его на порту 2020. Сначала убедитесь, что Docker запущен.
- Нет — выберите это, если у вас уже есть сервер Twenty, к которому вы хотите подключиться. Позже вы можете подключить его с помощью
yarn twenty remote add.
Когда сервер будет запущен, откроется браузер для входа. Используйте предварительно созданную демонстрационную учётную запись:
- Электронная почта:
tim@apple.dev
- Пароль:
tim@apple.dev
На следующем экране нажмите Authorize — это даст CLI доступ к вашему рабочему пространству.
В вашем терминале появится подтверждение, что всё настроено.
После этой фазы: у вас запущен сервер Twenty на http://localhost:2020, а ваш CLI авторизован для синхронизации с ним.
Если Docker не установлен или не запущен, генератор каркаса подскажет правильную команду запуска для вашей ОС. Когда Docker будет запущен, вы можете продолжить с yarn twenty server start — заново генерировать каркас не нужно.
Фаза 3 — Синхронизируйте свои изменения
Это внутренний цикл, в котором вы проведёте большую часть времени.
cd my-twenty-app
yarn twenty dev
src/, пересобирает при каждом изменении и синхронизирует результат с сервером. Отредактируйте файл, сохраните — и через секунду сервер отразит изменения. В терминале появится панель текущего статуса.
Для более подробного вывода (журналы сборки, запросы синхронизации, трассировки ошибок) добавьте --verbose.
Откройте http://localhost:2020/settings/applications#developer. Вы должны увидеть своё приложение в разделе Your Apps.
Нажмите My twenty app, чтобы открыть его регистрацию приложения — запись на уровне сервера, описывающую ваше приложение (имя, идентификатор, учётные данные OAuth, источник). Одну и ту же регистрацию можно установить в нескольких рабочих пространствах на одном сервере.
Нажмите View installed app, чтобы посмотреть установку в рабочем пространстве. Вкладка About показывает версию и параметры управления.
После этой фазы: у вас есть интерактивный цикл разработки. Отредактируйте любой файл в src/, и он появится в интерфейсе.
Разовая синхронизация для CI и скриптов
Передайте --once, чтобы выполнить одну сборку и синхронизацию и завершить работу — тот же конвейер, без наблюдателя:
| Команда | Поведение | Когда использовать |
|---|
yarn twenty dev | Отслеживает и повторно синхронизирует при каждом изменении. Продолжает работать, пока вы его не остановите. | Интерактивная локальная разработка. |
yarn twenty dev --once | Одна сборка и синхронизация, завершает работу с кодом 0 при успехе и 1 при ошибке. | CI, хуки pre-commit, AI-агенты, скриптовые рабочие процессы. |
Режим разработки доступен только на экземплярах Twenty, запущенных в режиме разработки (NODE_ENV=development). Экземпляры в продакшене отклоняют запросы синхронизации из режима разработки — используйте yarn twenty deploy для развёртывания на производственные серверы. См. Публикация приложений.
Что вы можете создать
Приложения состоят из сущностей — каждая определена как файл TypeScript с одним export default:
| Сущность | Что делает |
|---|
| Объекты и поля | Пользовательские модели данных (почтовая открытка, счёт и т. д.) с типизированными полями |
| Логические функции | Серверный TypeScript, запускаемый HTTP-маршрутами, расписаниями cron или событиями базы данных |
| Фронтенд-компоненты | React-компоненты, которые отображаются внутри интерфейса Twenty (боковая панель, виджеты, командное меню) |
| Навыки и агенты | Возможности ИИ — многократно используемые инструкции и автономные помощники |
| Представления и навигация | Предварительно настроенные представления списков и элементы бокового меню |
| Макеты страниц | Пользовательские страницы сведений о записи с вкладками и виджетами |
Структура проекта
my-twenty-app/
package.json
src/
application-config.ts # Required — your app's entry point
default-role.ts # Permissions for logic functions
constants/
universal-identifiers.ts # Auto-generated UUIDs and metadata
__tests__/
setup-test.ts
app-install.integration-test.ts
.github/workflows/ci.yml # GitHub Actions
public/ # Static assets
vitest.config.ts # Test runner config
tsconfig.json, tsconfig.spec.json
.nvmrc, .yarnrc.yml, .oxlintrc.json
README.md, LLMS.md
| Файл / Папка | Назначение |
|---|
src/application-config.ts | Обязательно. Основной файл конфигурации для вашего приложения. |
src/default-role.ts | Роль по умолчанию, контролирующая, к чему имеют доступ ваши логические функции. |
src/constants/universal-identifiers.ts | Автоматически генерируемые UUID и метаданные (отображаемое имя, описание). |
src/__tests__/ | Интеграционные тесты (настройка + пример теста). |
public/ | Статические ресурсы (изображения, шрифты), обслуживаемые вместе с вашим приложением. |
Начните с примера
Используйте --example, чтобы начать с более полного проекта (пользовательские объекты, поля, логические функции, фронтенд-компоненты):
npx create-twenty-app@latest my-twenty-app --example postcard
yarn twenty add — см. Создание приложений.
Управление локальным сервером
Используйте yarn twenty server для управления локальным контейнером Twenty:
| Команда | Что делает |
|---|
yarn twenty server start | Запустить сервер (при необходимости скачивает образ) |
yarn twenty server start --port 3030 | Запустить на пользовательском порту |
yarn twenty server stop | Остановить сервер (данные сохраняются) |
yarn twenty server status | Показать URL, версию и учётные данные для входа |
yarn twenty server logs | Потоковый вывод журналов сервера |
yarn twenty server reset | Стереть данные и начать заново |
yarn twenty server upgrade | Скачать последний образ twenty-app-dev |
yarn twenty server upgrade 2.2.0 | Обновить до конкретной версии |
twenty-app-dev-data для PostgreSQL, twenty-app-dev-storage для файлов). Используйте reset, чтобы стереть всё.
Обновление образа сервера
yarn twenty server upgrade скачивает последний образ, сравнивает дайджесты и пересоздаёт контейнер только если действительно что-то изменилось. Ваши тома данных сохраняются — заменяется только контейнер. Если был скачан новый образ и контейнер работал, при обновлении автоматически запускается новый контейнер; затем выполните yarn twenty server start, чтобы дождаться его готовности.
yarn twenty server upgrade # Latest
yarn twenty server upgrade 2.2.0 # Specific version
yarn twenty server status (эта команда показывает APP_VERSION, встроенную в контейнер).
Запуск параллельного тестового экземпляра
Передайте --test любой команде server, чтобы управлять вторым, полностью изолированным экземпляром — это полезно для запуска интеграционных тестов или экспериментов, не затрагивая ваши основные данные разработки.
| Команда | Что делает |
|---|
yarn twenty server start --test | Запустить тестовый экземпляр (по умолчанию — порт 2021) |
yarn twenty server stop --test | Остановить его |
yarn twenty server status --test | Показать его статус |
yarn twenty server logs --test | Транслировать его журналы |
yarn twenty server reset --test | Стереть его данные |
yarn twenty server upgrade --test | Обновить его образ |
twenty-app-dev-test) с выделенными томами (twenty-app-dev-test-data, twenty-app-dev-test-storage) и собственной конфигурацией, поэтому он может работать параллельно с вашим основным экземпляром без конфликтов. Совместите --test с --port, чтобы переопределить значение по умолчанию (2021).
Ручная настройка (без генератора)
Пропустите генератор каркаса, если вы добавляете SDK в существующий проект:
yarn add twenty-sdk twenty-client-sdk
package.json:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev, yarn twenty server start и остальные команды.
Не устанавливайте twenty-sdk глобально — фиксируйте версию в каждом проекте, чтобы каждое приложение использовало свою собственную версию.
Устранение неполадок
- Ошибки Docker — убедитесь, что Docker Desktop (или демон) запущен перед выполнением
yarn twenty server start. Сообщение об ошибке укажет правильную команду запуска для вашей ОС.
- Неподходящая версия Node — нужна 24+. Проверьте с помощью
node -v.
- Отсутствует Yarn 4 — выполните
corepack enable.
- Зависимости повреждены —
rm -rf node_modules && yarn install.
Застряли? Попросите помощи на Discord-сервере Twenty.
