Требования
- Node.js 24+ — Скачать здесь
- Yarn 4 — поставляется вместе с Node.js через Corepack. Включите его, выполнив
corepack enable - Docker — Скачать здесь. Требуется для запуска локального экземпляра Twenty. Пропустите, если у вас уже запущен Twenty в другом месте.
| Фаза | Что вы делаете | Инструмент | Результат |
|---|---|---|---|
| 1. Создание каркаса | Сгенерировать исходный код приложения | npx create-twenty-app | Проект TypeScript на диске |
| 2. Запустить сервер | Запустить сервер Twenty для синхронизации | Docker + yarn twenty server | Запущенный экземпляр Twenty |
| 3. Синхронизация | Синхронизируйте код с сервером в реальном времени | yarn twenty dev | Ваши изменения появляются в интерфейсе |
Фаза 1 — Сгенерируйте каркас проекта
Создайте новое приложение из шаблона: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
Если Docker не установлен или не запущен, генератор каркаса подскажет правильную команду запуска для вашей ОС. Когда Docker будет запущен, вы можете продолжить с
yarn twenty docker:start — заново генерировать каркас не нужно.Фаза 3 — Синхронизируйте свои изменения
Это внутренний цикл, в котором вы проведёте большую часть времени.src/, пересобирает при каждом изменении и синхронизирует результат с сервером. Отредактируйте файл, сохраните — и через несколько секунд сервер отразит изменения. В терминале появится панель текущего статуса.
Для более подробного вывода (журналы сборки, запросы синхронизации, трассировки ошибок) добавьте --verbose.
src/, и он появится в интерфейсе.
Разовая синхронизация для CI и скриптов
Передайте--once, чтобы выполнить одну сборку и синхронизацию и завершить работу — тот же конвейер, без наблюдателя:
| Команда | Поведение | Когда использовать |
|---|---|---|
yarn twenty dev | Отслеживает и повторно синхронизирует при каждом изменении. Продолжает работать, пока вы его не остановите. | Интерактивная локальная разработка. |
yarn twenty dev --once | Одна сборка и синхронизация, завершает работу с кодом 0 при успехе и 1 при ошибке. | CI, хуки pre-commit, AI-агенты, скриптовые рабочие процессы. |
yarn twenty dev --once --dry-run | Создает и выводит изменения метаданных без их применения. | Проверка того, какие изменения внесет синхронизация, прежде чем зафиксировать их. |
--dry-run.
Параметры режима разработки
| Флаг | Описание |
|---|---|
--once | Выполнить сборку и синхронизацию один раз, затем завершить работу. |
--dry-run | С опцией --once можно просмотреть изменения метаданных, не применяя их. Ничего не записывает. |
--debounceMs \<ms> | Установить задержку дебаунса изменений файлов в миллисекундах (по умолчанию: 2000). |
--verbose / --debug | Показывать подробные журналы сборки, запросы синхронизации и трассировки ошибок. |
Что вы можете создать
Приложения состоят из сущностей — каждая определена как файл TypeScript с однимexport default:
| Сущность | Что делает |
|---|---|
| Объекты и поля | Пользовательские модели данных (почтовая открытка, счёт и т. д.) с типизированными полями |
| Логические функции | Серверный TypeScript, запускаемый HTTP-маршрутами, расписаниями cron или событиями базы данных |
| Фронтенд-компоненты | React-компоненты, которые отображаются внутри интерфейса Twenty (боковая панель, виджеты, командное меню) |
| Навыки и агенты | Возможности ИИ — многократно используемые инструкции и автономные помощники |
| Представления и навигация | Предварительно настроенные представления списков и элементы бокового меню |
| Макеты страниц | Пользовательские страницы сведений о записи с вкладками и виджетами |
Следующие шаги
Конфигурация
Идентификация приложения, роль по умолчанию, хуки установки, публичные ресурсы.
Данные
Объекты, поля и двунаправленные связи.
Логика
Логические функции, навыки, агенты и OAuth-подключения.
Макет
Представления, навигация, макеты страниц, фронтенд-компоненты.
Операции
CLI, тестирование, удалённые серверы, CI и публикация вашего приложения.