--- 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.
Запустить локальный экземпляр?
### Войдите в своё рабочее пространство Затем откроется окно браузера со страницей входа в Twenty. Войдите, используя предварительно созданную демонстрационную учётную запись: * **Электронная почта:** `tim@apple.dev` * **Пароль:** `tim@apple.dev`
Экран входа в Twenty
### Авторизуйте приложение После входа вы увидите экран авторизации. Это позволит вашему приложению взаимодействовать с вашим рабочим пространством. Нажмите **Authorize**, чтобы продолжить.
Экран авторизации Twenty CLI
После авторизации в терминале появится подтверждение, что всё настроено.
Каркас приложения успешно создан
### Начните разработку Перейдите в папку вашего нового приложения и запустите сервер разработки: ```bash filename="Terminal" cd my-twenty-app yarn twenty dev ``` Он отслеживает исходные файлы, пересобирает при каждом изменении и автоматически синхронизирует ваше приложение с локальным сервером Twenty. В терминале должна появиться панель текущего статуса. Для более подробного вывода (журналы сборки, запросы синхронизации, трассировки ошибок) используйте флаг `--verbose`: ```bash filename="Terminal" yarn twenty dev --verbose ``` Режим разработки доступен только на экземплярах Twenty, запущенных в режиме разработки (`NODE_ENV=development`). Экземпляры в продакшене отклоняют запросы синхронизации из режима разработки. Используйте `yarn twenty deploy`, а затем `yarn twenty install`, чтобы выполнить публикацию и установку на продакшн-серверах — `deploy` публикует в реестр приложений, а `install` устанавливает его в указанное рабочее пространство. См. [Публикация приложений](/l/ru/developers/extend/apps/publishing) для подробностей.
Вывод терминала в режиме разработки
#### Разовая синхронизация с `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**:
Список Your Apps с приложением My twenty app
Нажмите **My twenty app**, чтобы открыть его **регистрацию приложения**. Регистрация — это запись на уровне сервера, описывающая ваше приложение: его имя, уникальный идентификатор, учётные данные OAuth и источник (локальный, npm или tarball). Она хранится на сервере, а не внутри какого-либо конкретного рабочего пространства. Когда вы устанавливаете приложение в рабочее пространство, Twenty создаёт привязанное к рабочему пространству **приложение**, которое ссылается на эту регистрацию. Одну и ту же регистрацию можно установить в нескольких рабочих пространствах на одном сервере.
Сведения о регистрации приложения
Нажмите **View installed app**, чтобы посмотреть установленное приложение. Вкладка **About** показывает текущую версию и параметры управления:
Установленное приложение
Готово! Отредактируйте любой файл в `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` | Обновить до конкретной версии | Данные сохраняются между перезапусками в двух томах Docker (`twenty-app-dev-data` для PostgreSQL, `twenty-app-dev-storage` для файлов). Используйте `reset`, чтобы стереть всё и начать заново. ### Обновление образа сервера Используйте `yarn twenty server upgrade`, чтобы проверить наличие более нового Docker-образа `twenty-app-dev` и обновить контейнер. Команда скачивает образ, сравнивает его с тем, из которого был создан контейнер, и пересоздаёт контейнер только если образ действительно изменился. Ваши тома данных сохраняются — заменяется только контейнер. ```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 ``` Если доступен более новый образ и контейнер был запущен, команда обновления автоматически запускает новый контейнер с обновлённым образом. Затем выполните `yarn twenty server start`, чтобы дождаться перехода контейнера в состояние healthy. Если образ не изменился, контейнер остаётся без изменений. Вы можете проверить запущенную версию с помощью `yarn twenty server status` — эта команда показывает `APP_VERSION` из контейнера. ### Запуск тестового экземпляра Передайте `--test` любой команде `server`, чтобы управлять вторым, полностью изолированным экземпляром — это полезно для запуска интеграционных тестов или экспериментов, не затрагивая ваши основные данные разработки. | Команда | Описание | | ----------------------------------- | --------------------------------------------------------------------- | | `yarn twenty server start --test` | Запустить тестовый экземпляр (по умолчанию — порт 2021) | | `yarn twenty server stop --test` | Остановить тестовый экземпляр | | `yarn twenty server status --test` | Показать состояние тестового экземпляра, URL, версию и учётные данные | | `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). Для работы сервера необходимо, чтобы **Docker** был запущен. Если вы видите ошибку "Docker not running", убедитесь, что запущен Docker Desktop (или демон Docker). ## Ручная настройка (без генератора) Если вы предпочитаете настроить всё самостоятельно, не используя `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` и все остальные команды. Не устанавливайте `twenty-sdk` глобально. Всегда используйте его как локальную зависимость проекта, чтобы каждый проект мог закреплять свою версию. ## Устранение неполадок Если столкнётесь с проблемами: * Перед запуском генератора с локальным экземпляром убедитесь, что **Docker запущен**. * Убедитесь, что используете **Node.js 24+** (`node -v` для проверки). * Убедитесь, что **Corepack включён** (`corepack enable`), чтобы Yarn 4 был доступен. * Если зависимости, похоже, повреждены, попробуйте удалить `node_modules` и снова выполнить `yarn install`. Все ещё не получается? Попросите помощи на [Discord-сервере Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).