github-actions[bot]
f32b03a3ec
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
302 lines
24 KiB
Plaintext
302 lines
24 KiB
Plaintext
---
|
||
title: Начало работы
|
||
icon: rocket
|
||
description: Создайте своё первое приложение Twenty за считанные минуты.
|
||
---
|
||
|
||
## Что такое приложения?
|
||
|
||
Приложения позволяют расширять Twenty с помощью пользовательских объектов, полей, логических функций, фронтенд-компонентов, навыков ИИ и многого другого — всё это управляется как код. Вместо настройки всего через интерфейс вы определяете модель данных и логику на TypeScript и развёртываете их в одном или нескольких рабочих пространствах.
|
||
|
||
## Требования
|
||
|
||
Прежде чем начать, убедитесь, что на вашем компьютере установлено следующее:
|
||
|
||
* **Node.js 24+** — [Скачать здесь](https://nodejs.org/)
|
||
* **Yarn 4** — Поставляется вместе с Node.js через Corepack. Включите его, выполнив `corepack enable`
|
||
* **Docker** — [Скачать здесь](https://www.docker.com/products/docker-desktop/). Требуется для запуска локального экземпляра Twenty. Не требуется, если у вас уже запущен сервер Twenty.
|
||
|
||
## Создайте своё первое приложение
|
||
|
||
### Сгенерируйте каркас приложения
|
||
|
||
Откройте терминал и выполните:
|
||
|
||
```bash filename="Terminal"
|
||
npx create-twenty-app@latest my-twenty-app
|
||
```
|
||
|
||
Вам будет предложено ввести имя и описание вашего приложения. Нажмите **Enter**, чтобы принять значения по умолчанию.
|
||
|
||
Будет создана новая папка `my-twenty-app` со всем необходимым.
|
||
|
||
### Настройте локальный экземпляр Twenty
|
||
|
||
Скэффолдер спросит:
|
||
|
||
> **Хотите настроить локальный экземпляр Twenty?**
|
||
|
||
* **Введите `yes`** (рекомендуется) — это скачает Docker-образ `twenty-app-dev` и запустит локальный сервер Twenty на порту `2020`. Перед продолжением убедитесь, что Docker запущен.
|
||
* **Введите `no`** — выберите это, если у вас уже запущен локальный сервер Twenty.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Запустить локальный экземпляр?" />
|
||
</div>
|
||
|
||
### Войдите в своё рабочее пространство
|
||
|
||
Затем откроется окно браузера со страницей входа в Twenty. Войдите, используя предварительно созданную демонстрационную учётную запись:
|
||
|
||
* **Электронная почта:** `tim@apple.dev`
|
||
* **Пароль:** `tim@apple.dev`
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/login.png" alt="Экран входа в Twenty" />
|
||
</div>
|
||
|
||
### Авторизуйте приложение
|
||
|
||
После входа вы увидите экран авторизации. Это позволит вашему приложению взаимодействовать с вашим рабочим пространством.
|
||
|
||
Нажмите **Authorize**, чтобы продолжить.
|
||
|
||
<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>
|
||
|
||
### Начните разработку
|
||
|
||
Перейдите в папку вашего нового приложения и запустите сервер разработки:
|
||
|
||
```bash filename="Terminal"
|
||
cd my-twenty-app
|
||
yarn twenty dev
|
||
```
|
||
|
||
Он отслеживает исходные файлы, пересобирает при каждом изменении и автоматически синхронизирует ваше приложение с локальным сервером Twenty. В терминале должна появиться панель текущего статуса.
|
||
|
||
Для более подробного вывода (журналы сборки, запросы синхронизации, трассировки ошибок) используйте флаг `--verbose`:
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty dev --verbose
|
||
```
|
||
|
||
<Warning>
|
||
Режим разработки доступен только на экземплярах Twenty, запущенных в режиме разработки (`NODE_ENV=development`). Экземпляры в продакшене отклоняют запросы синхронизации из режима разработки. Используйте `yarn twenty deploy` для развёртывания на продакшен-серверах — подробности см. в разделе [Публикация приложений](/l/ru/developers/extend/apps/publishing).
|
||
</Warning>
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Вывод терминала в режиме разработки" />
|
||
</div>
|
||
|
||
#### Разовая синхронизация с `yarn twenty dev --once`
|
||
|
||
Если вы не хотите, чтобы в фоновом режиме работал наблюдатель (например, в конвейере CI, хуке Git или скриптовом рабочем процессе), передайте флаг `--once`. Он запускает тот же конвейер, что и `yarn twenty dev` — собирает манифест, упаковывает файлы, загружает, синхронизирует, повторно генерирует типизированный клиент API — но **выходит сразу после завершения синхронизации**:
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty dev --once
|
||
```
|
||
|
||
| Команда | Поведение | Когда использовать |
|
||
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
||
| `yarn twenty dev` | Отслеживает ваши исходные файлы и повторно синхронизирует при каждом изменении. Продолжает работать, пока вы его не остановите. | Интерактивная локальная разработка — вам нужна панель статуса в реальном времени и мгновенная обратная связь. |
|
||
| `yarn twenty dev --once` | Выполняет одну сборку и синхронизацию, затем завершает работу с кодом `0` при успехе или `1` при ошибке. | Скрипты, CI, хуки pre-commit, AI-агенты и любые неинтерактивные рабочие процессы. |
|
||
|
||
Оба режима требуют сервер Twenty, запущенный в режиме разработки, и аутентифицированный удалённый ресурс — действуют те же предварительные требования.
|
||
|
||
### Посмотрите своё приложение в Twenty
|
||
|
||
Откройте [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) в браузере. Перейдите в **Settings > Apps** и выберите вкладку **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 и источник (локальный, npm или tarball). Она хранится на сервере, а не внутри какого-либо конкретного рабочего пространства. Когда вы устанавливаете приложение в рабочее пространство, Twenty создаёт привязанное к рабочему пространству **приложение**, которое ссылается на эту регистрацию. Одну и ту же регистрацию можно установить в нескольких рабочих пространствах на одном сервере.
|
||
|
||
<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="Установленное приложение — вкладка About" />
|
||
</div>
|
||
|
||
Переключитесь на вкладку **Content**, чтобы увидеть всё, что предоставляет ваше приложение: объекты, поля, логические функции и агенты:
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Установленное приложение — вкладка Content" />
|
||
</div>
|
||
|
||
Готово! Отредактируйте любой файл в `src/`, и изменения будут подхвачены автоматически.
|
||
|
||
---
|
||
|
||
## Что вы можете создать
|
||
|
||
Приложения состоят из **сущностей** — каждая определена как файл TypeScript с одним `export default`:
|
||
|
||
| Сущность | Что делает |
|
||
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||
| **Объекты и поля** | Определяйте пользовательские модели данных (например, Post Card, Invoice) с типизированными полями |
|
||
| **Логические функции** | Серверные функции на TypeScript, запускаемые HTTP-маршрутами, расписаниями cron или событиями базы данных |
|
||
| **Фронтенд-компоненты** | React-компоненты, которые отображаются внутри интерфейса Twenty (боковая панель, виджеты, командное меню) |
|
||
| **Навыки и агенты** | Возможности ИИ — многократно используемые инструкции и автономные помощники |
|
||
| **Представления и навигация** | Предварительно настроенные представления списков и элементы бокового меню для ваших объектов |
|
||
| **Макеты страниц** | Пользовательские страницы сведений о записи с вкладками и виджетами |
|
||
|
||
Перейдите к разделу [Создание приложений](/l/ru/developers/extend/apps/building), чтобы получить подробное руководство по каждому типу сущности.
|
||
|
||
---
|
||
|
||
## Структура проекта
|
||
|
||
Инструмент генерации каркаса создаёт следующую структуру файлов:
|
||
|
||
```text filename="my-twenty-app/"
|
||
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`:
|
||
|
||
```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)).
|
||
|
||
### Ключевые файлы
|
||
|
||
| Файл / Папка | Назначение |
|
||
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `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` | Удалить все данные и начать с чистого листа |
|
||
| `yarn twenty server upgrade` | Загрузить последний образ `twenty-app-dev` и пересоздать контейнер |
|
||
| `yarn twenty server upgrade 2.2.0` | Upgrade to a specific version |
|
||
|
||
Данные сохраняются между перезапусками в двух томах Docker (`twenty-app-dev-data` для PostgreSQL, `twenty-app-dev-storage` для файлов). Используйте `reset`, чтобы стереть всё и начать заново.
|
||
|
||
### Upgrading the server image
|
||
|
||
Use `yarn twenty server upgrade` to check for a newer `twenty-app-dev` Docker image and update the container. The command pulls the image, compares it against the one the container was created from, and only recreates the container if the image actually changed. Your data volumes are preserved — only the container is replaced.
|
||
|
||
```bash filename="Terminal"
|
||
# Upgrade to the latest version (skips recreation if already up to date)
|
||
yarn twenty server upgrade
|
||
|
||
# Upgrade to a specific version
|
||
yarn twenty server upgrade 2.2.0
|
||
```
|
||
|
||
If a newer image is available and the container was running, the upgrade command automatically starts a new container with the updated image. Run `yarn twenty server start` afterward to wait for it to become healthy. If the image hasn't changed, the container is left untouched.
|
||
|
||
You can verify the running version with `yarn twenty server status`, which displays the `APP_VERSION` from the container.
|
||
|
||
### Запуск тестового экземпляра
|
||
|
||
Передайте `--test` любой команде `server`, чтобы управлять вторым, полностью изолированным экземпляром — это полезно для запуска интеграционных тестов или экспериментов, не затрагивая ваши основные данные разработки.
|
||
|
||
| Команда | Описание |
|
||
| ----------------------------------- | -------------------------------------------------------- |
|
||
| `yarn twenty server start --test` | Запустить тестовый экземпляр (по умолчанию — порт 2021) |
|
||
| `yarn twenty server stop --test` | Остановить тестовый экземпляр |
|
||
| `yarn twenty server status --test` | Show test instance status, URL, version, and credentials |
|
||
| `yarn twenty server logs --test` | Выводить журналы тестового экземпляра в потоковом режиме |
|
||
| `yarn twenty server reset --test` | Удалить тестовые данные и начать с чистого листа |
|
||
| `yarn twenty server upgrade --test` | Upgrade the test instance image |
|
||
|
||
Тестовый экземпляр запускается в собственном контейнере Docker (`twenty-app-dev-test`) с выделенными томами (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) и собственной конфигурацией, поэтому он может работать параллельно с вашим основным экземпляром без конфликтов. Совместите `--test` с `--port`, чтобы переопределить значение по умолчанию (2021).
|
||
|
||
<Note>
|
||
Для работы сервера необходимо, чтобы **Docker** был запущен. Если вы видите ошибку "Docker not running", убедитесь, что запущен Docker Desktop (или демон Docker).
|
||
</Note>
|
||
|
||
## Ручная настройка (без генератора)
|
||
|
||
Если вы предпочитаете настроить всё самостоятельно, не используя `create-twenty-app`, это можно сделать в два шага.
|
||
|
||
**1. Добавьте `twenty-sdk` и `twenty-client-sdk` в зависимости:**
|
||
|
||
```bash filename="Terminal"
|
||
yarn add twenty-sdk twenty-client-sdk
|
||
```
|
||
|
||
**2. Добавьте скрипт `twenty` в ваш `package.json`:**
|
||
|
||
```json filename="package.json"
|
||
{
|
||
"scripts": {
|
||
"twenty": "twenty"
|
||
}
|
||
}
|
||
```
|
||
|
||
Теперь вы можете запускать `yarn twenty dev`, `yarn twenty help` и все остальные команды.
|
||
|
||
<Note>
|
||
Не устанавливайте `twenty-sdk` глобально. Всегда используйте его как локальную зависимость проекта, чтобы каждый проект мог закреплять свою версию.
|
||
</Note>
|
||
|
||
## Устранение неполадок
|
||
|
||
Если столкнётесь с проблемами:
|
||
|
||
* Перед запуском генератора с локальным экземпляром убедитесь, что **Docker запущен**.
|
||
* Убедитесь, что используете **Node.js 24+** (`node -v` для проверки).
|
||
* Убедитесь, что **Corepack включён** (`corepack enable`), чтобы Yarn 4 был доступен.
|
||
* Если зависимости, похоже, повреждены, попробуйте удалить `node_modules` и снова выполнить `yarn install`.
|
||
|
||
Все ещё не получается? Попросите помощи на [Discord-сервере Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).
|