github-actions[bot]
0b8421a45a
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
256 lines
17 KiB
Plaintext
256 lines
17 KiB
Plaintext
---
|
|
title: Начало работы
|
|
description: Создайте своё первое приложение Twenty за считанные минуты.
|
|
---
|
|
|
|
<Warning>
|
|
Приложения сейчас проходят альфа-тестирование. Функция работает, но продолжает развиваться.
|
|
</Warning>
|
|
|
|
## Что такое приложения?
|
|
|
|
Приложения позволяют расширять 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.
|
|
|
|
## Create your first app
|
|
|
|
### Scaffold your app
|
|
|
|
Откройте терминал и выполните:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
Вам будет предложено ввести имя и описание вашего приложения. Нажмите **Enter**, чтобы принять значения по умолчанию.
|
|
|
|
Будет создана новая папка `my-twenty-app` со всем необходимым.
|
|
|
|
### Set up a local Twenty instance
|
|
|
|
Скэффолдер спросит:
|
|
|
|
> **Хотите настроить локальный экземпляр 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>
|
|
|
|
### Sign in to your workspace
|
|
|
|
Затем откроется окно браузера со страницей входа в Twenty. Войдите, используя предварительно созданную демонстрационную учётную запись:
|
|
|
|
* **Электронная почта:** `tim@apple.dev`
|
|
* **Пароль:** `tim@apple.dev`
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/login.png" alt="Экран входа в Twenty" />
|
|
</div>
|
|
|
|
### Authorize the app
|
|
|
|
После входа вы увидите экран авторизации. Это позволит вашему приложению взаимодействовать с вашим рабочим пространством.
|
|
|
|
Нажмите **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>
|
|
|
|
### Start developing
|
|
|
|
Перейдите в папку вашего нового приложения и запустите сервер разработки:
|
|
|
|
```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>
|
|
|
|
### See your app in 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/`, и изменения будут подхвачены автоматически.
|
|
|
|
---
|
|
|
|
## Что вы можете создать
|
|
|
|
Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
|
|
|
|
| Entity | What it does |
|
|
| ----------------------- | --------------------------------------------------------------------------------------------- |
|
|
| **Objects & Fields** | Define custom data models (like Post Card, Invoice) with typed fields |
|
|
| **Логические функции** | Server-side TypeScript functions triggered by HTTP routes, cron schedules, or database events |
|
|
| **Фронтенд-компоненты** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
|
|
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
|
|
| **Views & Navigation** | Pre-configured list views and sidebar menu items for your objects |
|
|
| **Макеты страниц** | Custom record detail pages with tabs and widgets |
|
|
|
|
Head over to [Building Apps](/l/ru/developers/extend/apps/building) for a detailed guide on each entity type.
|
|
|
|
---
|
|
|
|
## Структура проекта
|
|
|
|
The scaffolder generates the following file structure:
|
|
|
|
```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
|
|
```
|
|
|
|
### Starting from an example
|
|
|
|
To start from a more complete example with custom objects, fields, logic functions, front components, and more, use the `--example` flag:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Examples are sourced from the [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) directory on GitHub. You can also scaffold individual entities into an existing project with `yarn twenty add` (see [Building Apps](/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` | Default role that controls what your logic functions can access. |
|
|
| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and app metadata (display name, description). |
|
|
| `src/__tests__/` | Интеграционные тесты (настройка + пример теста). |
|
|
| `public/` | Статические ресурсы (изображения, шрифты), обслуживаемые вместе с вашим приложением. |
|
|
|
|
## Local development server
|
|
|
|
The scaffolder already started a local Twenty server for you. To manage it later, use `yarn twenty server`:
|
|
|
|
| Команда | Описание |
|
|
| -------------------------------------- | -------------------------------------------------------------- |
|
|
| `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 logs --lines 100` | Показать последние 100 строк журнала |
|
|
| `yarn twenty server reset` | Удалить все данные и начать с чистого листа |
|
|
|
|
Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh.
|
|
|
|
<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).
|