---
title: Начало работы
description: Создайте своё первое приложение Twenty за считанные минуты.
---

<Warning>
Приложения сейчас проходят альфа-тестирование. Функция работает, но продолжает развиваться.
</Warning>

Приложения позволяют расширять Twenty с помощью пользовательских объектов, полей, логических функций, навыков ИИ и UI-компонентов — всё это управляется как код.

## Требования

Прежде чем начать, убедитесь, что на вашем компьютере установлено следующее:

* **Node.js 24+** — [Скачать здесь](https://nodejs.org/)
* **Yarn 4** — Поставляется вместе с Node.js через Corepack. Включите его, выполнив `corepack enable`
* **Docker** — [Скачать здесь](https://www.docker.com/products/docker-desktop/). Требуется для запуска локального экземпляра Twenty. Не требуется, если у вас уже запущен сервер Twenty.

## Шаг 1: Сгенерируйте каркас приложения

Откройте терминал и выполните:

```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app
```

Вам будет предложено ввести имя и описание вашего приложения. Нажмите **Enter**, чтобы принять значения по умолчанию.

Будет создана новая папка `my-twenty-app` со всем необходимым.

<Note>
Генератор поддерживает следующие флаги:

* `--minimal` — сгенерировать только основные файлы, без примеров (по умолчанию)
* `--exhaustive` — сгенерировать все примеры сущностей
* `--name <name>` — задать имя приложения (пропускает запрос)
* `--display-name <displayName>` — задать отображаемое имя (пропускает запрос)
* `--description <description>` — задать описание (пропускает запрос)
* `--skip-local-instance` — пропустить запрос на настройку локального сервера
</Note>

## Шаг 2: Настройте локальный экземпляр 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>

## Шаг 3: Войдите в своё рабочее пространство

Затем откроется окно браузера со страницей входа в Twenty. Войдите, используя предварительно созданную демонстрационную учётную запись:

* **Электронная почта:** `tim@apple.dev`
* **Пароль:** `tim@apple.dev`

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Экран входа в Twenty" />
</div>

## Шаг 4: Авторизуйте приложение

После входа вы увидите экран авторизации. Это позволит вашему приложению взаимодействовать с вашим рабочим пространством.

Нажмите **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>

## Шаг 5: Начните разработку

Перейдите в папку вашего нового приложения и запустите сервер разработки:

```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>

## Шаг 6: Посмотрите своё приложение в 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/`, и изменения будут подхвачены автоматически.

Перейдите к разделу [Создание приложений](/l/ru/developers/extend/apps/building) за подробным руководством по созданию объектов, логических функций, фронтенд-компонентов, навыков и многого другого.

---

## Структура проекта

Скэффолдер генерирует следующую структуру файлов (показано в режиме `--exhaustive`, который включает примеры для каждого типа сущностей):

```text filename="my-twenty-app/"
my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .yarn/
    install-state.gz
  .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
  ├── __tests__/
  │   ├── setup-test.ts                   # Test setup (server health check, config)
  │   └── app-install.integration-test.ts # Example integration test
  ├── roles/
  │   └── default-role.ts                 # Default role for logic functions
  ├── objects/
  │   └── example-object.ts               # Example custom object definition
  ├── fields/
  │   └── example-field.ts                # Example standalone field definition
  ├── logic-functions/
  │   ├── hello-world.ts                  # Example logic function
  │   ├── create-hello-world-company.ts   # Example logic function using CoreApiClient
  │   ├── pre-install.ts                  # Runs before installation
  │   └── post-install.ts                 # Runs after installation
  ├── front-components/
  │   └── hello-world.tsx                 # Example front component
  ├── page-layouts/
  │   └── example-record-page-layout.ts   # Example page layout with front component
  ├── views/
  │   └── example-view.ts                 # Example saved view definition
  ├── navigation-menu-items/
  │   └── example-navigation-menu-item.ts # Example sidebar navigation link
  ├── skills/
  │   └── example-skill.ts                # Example AI agent skill definition
  └── agents/
      └── example-agent.ts                # Example AI agent definition
```

По умолчанию (`--minimal`) создаются только основные файлы: `application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` и `logic-functions/post-install.ts`. Используйте `--exhaustive`, чтобы включить все показанные выше файлы-примеры.

### Ключевые файлы

| Файл / Папка                 | Назначение                                                                                                                                         |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `package.json`               | Содержит имя, версию и зависимости вашего приложения. Содержит скрипт `twenty`, чтобы вы могли выполнить `yarn twenty help` и увидеть все команды. |
| `src/application-config.ts`  | **Обязательно.** Основной файл конфигурации для вашего приложения.                                                                                 |
| `src/roles/`                 | Определяет роли, которые контролируют доступ логических функций.                                                                                   |
| `src/logic-functions/`       | Серверные функции, запускаемые маршрутами, расписаниями cron или событиями базы данных.                                                            |
| `src/front-components/`      | Компоненты React, которые отображаются внутри интерфейса Twenty.                                                                                   |
| `src/objects/`               | Пользовательские определения объектов для расширения вашей модели данных.                                                                          |
| `src/fields/`                | Пользовательские поля, добавляемые к существующим объектам.                                                                                        |
| `src/views/`                 | Конфигурации сохранённых представлений.                                                                                                            |
| `src/navigation-menu-items/` | Пользовательские ссылки в боковой навигации.                                                                                                       |
| `src/skills/`                | Навыки, расширяющие возможности ИИ-агентов Twenty.                                                                                                 |
| `src/agents/`                | ИИ-агенты с пользовательскими промптами.                                                                                                           |
| `src/page-layouts/`          | Пользовательские макеты страниц для представлений записей.                                                                                         |
| `src/__tests__/`             | Интеграционные тесты (настройка + пример теста).                                                                                                   |
| `public/`                    | Статические ресурсы (изображения, шрифты), обслуживаемые вместе с вашим приложением.                                                               |

## Управление удалёнными серверами

Remote — это сервер Twenty, к которому подключается ваше приложение. Во время настройки скэффолдер автоматически создаст его для вас. Вы можете в любой момент добавлять новые remotes или переключаться между ними.

```bash filename="Terminal"
# Add a new remote (opens a browser for OAuth login)
yarn twenty remote add

# Connect to a local Twenty server (auto-detects port 2020 or 3000)
yarn twenty remote add --local

# Add a remote non-interactively (useful for CI)
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote

# List all configured remotes
yarn twenty remote list

# Switch the active remote
yarn twenty remote switch <name>
```

Ваши учётные данные хранятся в `~/.twenty/config.json`.

## Локальный сервер разработки (`yarn twenty server`)

CLI может управлять локальным сервером Twenty, запущенным в Docker. Это тот же сервер, который автоматически запускается при создании каркаса приложения с помощью `create-twenty-app`, но им можно управлять и вручную.

### Запуск сервера

```bash filename="Terminal"
yarn twenty server start
```

Эта команда скачивает Docker-образ `twentycrm/twenty-app-dev:latest` (если его ещё нет), создаёт контейнер с именем `twenty-app-dev` и запускает его на порту **2020**. CLI ждёт, пока сервер пройдёт проверку работоспособности, прежде чем вернуть управление.

Создаются два тома Docker для сохранения данных между перезапусками:

* `twenty-app-dev-data` — база данных PostgreSQL
* `twenty-app-dev-storage` — файловое хранилище

Если порт 2020 уже используется, вы можете запустить на другом порту:

```bash filename="Terminal"
yarn twenty server start --port 3030
```

CLI автоматически настраивает внутренние `NODE_PORT` и `SERVER_URL` контейнера в соответствии с выбранным портом, чтобы логические функции, OAuth и прочие внутренние сетевые взаимодействия работали корректно.

После запуска сервер автоматически регистрируется как remote `local` в конфигурации вашего CLI.

### Проверка состояния сервера

```bash filename="Terminal"
yarn twenty server status
```

Показывает, запущен ли сервер, его URL и учётные данные по умолчанию (`tim@apple.dev` / `tim@apple.dev`).

### Просмотр журналов сервера

```bash filename="Terminal"
yarn twenty server logs
```

Выводит журналы контейнера в потоковом режиме. Используйте `--lines`, чтобы задать, сколько последних строк показывать:

```bash filename="Terminal"
yarn twenty server logs --lines 100
```

### Остановка сервера

```bash filename="Terminal"
yarn twenty server stop
```

Останавливает контейнер. Ваши данные сохраняются в томах Docker — следующий `start` продолжит с того места, где вы остановились.

### Сброс сервера

```bash filename="Terminal"
yarn twenty server reset
```

Удаляет контейнер и оба тома Docker, полностью стирая все данные. Следующий `start` создаст новый чистый экземпляр.

<Note>
  Для работы сервера необходимо, чтобы **Docker** был запущен. Если вы видите ошибку "Docker not running", убедитесь, что запущен Docker Desktop (или демон Docker).
</Note>

### Справочник команд

| Команда                                | Описание                                                       |
| -------------------------------------- | -------------------------------------------------------------- |
| `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`             | Удалить все данные и начать с чистого листа                    |

## CI с GitHub Actions

Скэффолдер генерирует готовый к использованию workflow GitHub Actions в `.github/workflows/ci.yml`. Он автоматически запускает ваши интеграционные тесты при каждом пуше в `main` и в pull request'ах.

Рабочий процесс:

1. Извлекает ваш код
2. Поднимает временный сервер Twenty с помощью экшена `twentyhq/twenty/.github/actions/spawn-twenty-docker-image`
3. Устанавливает зависимости с помощью `yarn install --immutable`
4. Запускает `yarn test` с `TWENTY_API_URL` и `TWENTY_API_KEY`, переданными из выходных данных экшена

```yaml .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request: {}

env:
  TWENTY_VERSION: latest

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Spawn Twenty instance
        id: twenty
        uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
        with:
          twenty-version: ${{ env.TWENTY_VERSION }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Enable Corepack
        run: corepack enable

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: '.nvmrc'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --immutable

      - name: Run integration tests
        run: yarn test
        env:
          TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
          TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
```

Вам не нужно настраивать секреты — экшен `spawn-twenty-docker-image` запускает эфемерный сервер Twenty прямо в раннере и выводит данные для подключения. Секрет `GITHUB_TOKEN` предоставляется GitHub автоматически.

Чтобы закрепить конкретную версию Twenty вместо `latest`, измените переменную окружения `TWENTY_VERSION` в начале workflow.

## Ручная настройка (без генератора)

Если вы предпочитаете настроить всё самостоятельно, не используя `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).