274 lines
22 KiB
Plaintext
274 lines
22 KiB
Plaintext
---
|
||
title: Начало работы
|
||
icon: rocket
|
||
description: Создайте своё первое приложение Twenty за считанные минуты.
|
||
---
|
||
|
||
## Требования
|
||
|
||
* **Node.js 24+** — [Скачать здесь](https://nodejs.org/)
|
||
* **Yarn 4** — поставляется вместе с Node.js через Corepack. Включите его, выполнив `corepack enable`
|
||
* **Docker** — [Скачать здесь](https://www.docker.com/products/docker-desktop/). Требуется для запуска локального экземпляра Twenty. Пропустите, если у вас уже запущен Twenty в другом месте.
|
||
|
||
Создание приложения Twenty включает три фазы. Генератор каркаса объединяет их в одну команду для идеального сценария (happy path), но каждая фаза — отдельная концепция: когда что-то идёт не так, понимание того, на какой фазе вы находитесь, подскажет, что исправить.
|
||
|
||
| Фаза | Что вы делаете | Инструмент | Результат |
|
||
| ----------------------- | ------------------------------------------------- | ----------------------------- | -------------------------------------- |
|
||
| **1. Создание каркаса** | Сгенерировать исходный код приложения | `npx create-twenty-app` | Проект TypeScript на диске |
|
||
| **2. Запустить сервер** | Запустить сервер Twenty для синхронизации | Docker + `yarn twenty server` | Запущенный экземпляр Twenty |
|
||
| **3. Синхронизация** | Синхронизируйте код с сервером в реальном времени | `yarn twenty dev` | Ваши изменения появляются в интерфейсе |
|
||
|
||
---
|
||
|
||
## Фаза 1 — Сгенерируйте каркас проекта
|
||
|
||
Создайте новое приложение из шаблона:
|
||
|
||
```bash filename="Terminal"
|
||
npx create-twenty-app@latest my-twenty-app
|
||
```
|
||
|
||
Вам будет предложено ввести имя и описание — нажмите **Enter**, чтобы принять значения по умолчанию. Это создаст проект TypeScript в `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`.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Запустить локальный экземпляр?" />
|
||
</div>
|
||
|
||
Когда сервер будет запущен, откроется браузер для входа. Используйте предварительно созданную демонстрационную учётную запись:
|
||
|
||
* **Электронная почта:** `tim@apple.dev`
|
||
* **Пароль:** `tim@apple.dev`
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/login.png" alt="Экран входа в Twenty" />
|
||
</div>
|
||
|
||
На следующем экране нажмите **Authorize** — это даст CLI доступ к вашему рабочему пространству.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Экран авторизации Twenty CLI" />
|
||
</div>
|
||
|
||
В вашем терминале появится подтверждение, что всё настроено.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Каркас приложения успешно создан" />
|
||
</div>
|
||
|
||
**После этой фазы:** у вас запущен сервер Twenty на [http://localhost:2020](http://localhost:2020), а ваш CLI авторизован для синхронизации с ним.
|
||
|
||
<Note>
|
||
Если Docker не установлен или не запущен, генератор каркаса подскажет правильную команду запуска для вашей ОС. Когда Docker будет запущен, вы можете продолжить с `yarn twenty server start` — заново генерировать каркас не нужно.
|
||
</Note>
|
||
|
||
---
|
||
|
||
## Фаза 3 — Синхронизируйте свои изменения
|
||
|
||
Это внутренний цикл, в котором вы проведёте большую часть времени.
|
||
|
||
```bash filename="Terminal"
|
||
cd my-twenty-app
|
||
yarn twenty dev
|
||
```
|
||
|
||
Эта команда отслеживает `src/`, пересобирает при каждом изменении и синхронизирует результат с сервером. Отредактируйте файл, сохраните — и через секунду сервер отразит изменения. В терминале появится панель текущего статуса.
|
||
|
||
Для более подробного вывода (журналы сборки, запросы синхронизации, трассировки ошибок) добавьте `--verbose`.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/dev.png" alt="Вывод терминала в режиме разработки" />
|
||
</div>
|
||
|
||
Откройте [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Вы должны увидеть своё приложение в разделе **Your Apps**.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Список Your Apps с приложением My twenty app" />
|
||
</div>
|
||
|
||
Нажмите **My twenty app**, чтобы открыть его регистрацию приложения — запись на уровне сервера, описывающую ваше приложение (имя, идентификатор, учётные данные OAuth, источник). Одну и ту же регистрацию можно установить в нескольких рабочих пространствах на одном сервере.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Сведения о регистрации приложения" />
|
||
</div>
|
||
|
||
Нажмите **View installed app**, чтобы посмотреть установку в рабочем пространстве. Вкладка **About** показывает версию и параметры управления.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Установленное приложение" />
|
||
</div>
|
||
|
||
**После этой фазы:** у вас есть интерактивный цикл разработки. Отредактируйте любой файл в `src/`, и он появится в интерфейсе.
|
||
|
||
### Разовая синхронизация для CI и скриптов
|
||
|
||
Передайте `--once`, чтобы выполнить одну сборку и синхронизацию и завершить работу — тот же конвейер, без наблюдателя:
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty dev --once
|
||
```
|
||
|
||
| Команда | Поведение | Когда использовать |
|
||
| ------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
||
| `yarn twenty dev` | Отслеживает и повторно синхронизирует при каждом изменении. Продолжает работать, пока вы его не остановите. | Интерактивная локальная разработка. |
|
||
| `yarn twenty dev --once` | Одна сборка и синхронизация, завершает работу с кодом `0` при успехе и `1` при ошибке. | CI, хуки pre-commit, AI-агенты, скриптовые рабочие процессы. |
|
||
|
||
Оба режима требуют сервер в режиме разработки и аутентифицированный удалённый сервер.
|
||
|
||
<Warning>
|
||
Режим разработки доступен только на экземплярах Twenty, запущенных в режиме разработки (`NODE_ENV=development`). Экземпляры в продакшене отклоняют запросы синхронизации из режима разработки — используйте `yarn twenty deploy` для развёртывания на производственные серверы. См. [Публикация приложений](/l/ru/developers/extend/apps/publishing).
|
||
</Warning>
|
||
|
||
---
|
||
|
||
## Что вы можете создать
|
||
|
||
Приложения состоят из **сущностей** — каждая определена как файл TypeScript с одним `export default`:
|
||
|
||
| Сущность | Что делает |
|
||
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||
| **Объекты и поля** | Пользовательские модели данных (почтовая открытка, счёт и т. д.) с типизированными полями |
|
||
| **Логические функции** | Серверный TypeScript, запускаемый HTTP-маршрутами, расписаниями cron или событиями базы данных |
|
||
| **Фронтенд-компоненты** | React-компоненты, которые отображаются внутри интерфейса Twenty (боковая панель, виджеты, командное меню) |
|
||
| **Навыки и агенты** | Возможности ИИ — многократно используемые инструкции и автономные помощники |
|
||
| **Представления и навигация** | Предварительно настроенные представления списков и элементы бокового меню |
|
||
| **Макеты страниц** | Пользовательские страницы сведений о записи с вкладками и виджетами |
|
||
|
||
Полная справка: [Создание приложений](/l/ru/developers/extend/apps/building).
|
||
|
||
## Структура проекта
|
||
|
||
```text filename="my-twenty-app/"
|
||
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`, чтобы начать с более полного проекта (пользовательские объекты, поля, логические функции, фронтенд-компоненты):
|
||
|
||
```bash filename="Terminal"
|
||
npx create-twenty-app@latest my-twenty-app --example postcard
|
||
```
|
||
|
||
Примеры берутся из каталога [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) на GitHub. Вы также можете сгенерировать каркас отдельных сущностей в существующем проекте с помощью `yarn twenty add` — см. [Создание приложений](/l/ru/developers/extend/apps/building#scaffolding-entities-with-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` | Обновить до конкретной версии |
|
||
|
||
Данные сохраняются между перезапусками в двух томах Docker (`twenty-app-dev-data` для PostgreSQL, `twenty-app-dev-storage` для файлов). Используйте `reset`, чтобы стереть всё.
|
||
|
||
### Обновление образа сервера
|
||
|
||
`yarn twenty server upgrade` скачивает последний образ, сравнивает дайджесты и пересоздаёт контейнер только если действительно что-то изменилось. Ваши тома данных сохраняются — заменяется только контейнер. Если был скачан новый образ и контейнер работал, при обновлении автоматически запускается новый контейнер; затем выполните `yarn twenty server start`, чтобы дождаться его готовности.
|
||
|
||
```bash filename="Terminal"
|
||
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` | Обновить его образ |
|
||
|
||
Тестовый экземпляр запускается в собственном контейнере Docker (`twenty-app-dev-test`) с выделенными томами (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) и собственной конфигурацией, поэтому он может работать параллельно с вашим основным экземпляром без конфликтов. Совместите `--test` с `--port`, чтобы переопределить значение по умолчанию (2021).
|
||
|
||
---
|
||
|
||
## Ручная настройка (без генератора)
|
||
|
||
Пропустите генератор каркаса, если вы добавляете SDK в существующий проект:
|
||
|
||
```bash filename="Terminal"
|
||
yarn add twenty-sdk twenty-client-sdk
|
||
```
|
||
|
||
Добавьте скрипт в `package.json`:
|
||
|
||
```json filename="package.json"
|
||
{
|
||
"scripts": {
|
||
"twenty": "twenty"
|
||
}
|
||
}
|
||
```
|
||
|
||
Теперь вы можете запускать `yarn twenty dev`, `yarn twenty server start` и остальные команды.
|
||
|
||
<Note>
|
||
Не устанавливайте `twenty-sdk` глобально — фиксируйте версию в каждом проекте, чтобы каждое приложение использовало свою собственную версию.
|
||
</Note>
|
||
|
||
---
|
||
|
||
## Устранение неполадок
|
||
|
||
* **Ошибки Docker** — убедитесь, что Docker Desktop (или демон) запущен перед выполнением `yarn twenty server start`. Сообщение об ошибке укажет правильную команду запуска для вашей ОС.
|
||
* **Неподходящая версия Node** — нужна 24+. Проверьте с помощью `node -v`.
|
||
* **Отсутствует Yarn 4** — выполните `corepack enable`.
|
||
* **Зависимости повреждены** — `rm -rf node_modules && yarn install`.
|
||
|
||
Застряли? Попросите помощи на [Discord-сервере Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).
|