upstream-twenty/packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdx

---
title: Конфигурация приложения
description: Определите идентификацию вашего приложения, роль по умолчанию, переменные и метаданные маркетплейса с помощью defineApplication.
icon: rocket
---

В каждом приложении должен быть ровно один вызов `defineApplication`. Он объявляет:

* **Идентификация** — универсальный идентификатор, отображаемое имя, описание.
* **Разрешения** — от имени какой роли выполняются его логические функции и фронтенд-компоненты.
* **Переменные** *(необязательно)* — пары ключ–значение, доступные вашему коду как переменные окружения.
* **Хуки предустановки / постустановки / удаления** *(необязательно)* — см. [Логические функции](/l/ru/developers/extend/apps/logic/logic-functions).

```ts src/application-config.ts
import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'My Twenty App',
  description: 'My first Twenty app',
  applicationVariables: {
    DEFAULT_RECIPIENT_NAME: {
      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
      description: 'Default recipient name for postcards',
      value: 'Jane Doe',
      isSecret: false,
    },
  },
});
```

Заметки:

* Поля `universalIdentifier` — это детерминированные идентификаторы, которые принадлежат вам. Сгенерируйте их один раз и сохраняйте неизменными между синхронизациями.
* `applicationVariables` становятся переменными окружения для ваших функций и фронтенд-компонентов. В логических функциях (на стороне сервера) они доступны как `process.env.VARIABLE_NAME`. Во фронтенд-компонентах используйте `getApplicationVariable('VARIABLE_NAME')` из `twenty-sdk/front-component`. Переменные, помеченные как `isSecret: true`, внедряются только в логические функции. Фронтенд-компоненты получают только несекретные переменные.
* Роль по умолчанию автоматически определяется из файла роли, помеченного с помощью [`defineApplicationRole()`](/l/ru/developers/extend/apps/config/roles) — вам не нужно ссылаться на неё из `defineApplication()`.
* Функции предустановки, постустановки и удаления обнаруживаются автоматически во время сборки манифеста — вам не нужно указывать их в `defineApplication()`.
* Явная передача `defaultRoleUniversalIdentifier` по-прежнему поддерживается для обратной совместимости, но считается устаревшей и вместо неё рекомендуется использовать `defineApplicationRole()`.
* `serverVariables` — это параметры конфигурации и секреты в области экземпляра (например, ключи API). В отличие от `applicationVariables`, значения для них не указываются в манифесте — оператор рабочего пространства заполняет их в настройках приложения, и они внедряются в логические функции только после того, как будут заданы.
* Оба типа переменных принимают `isDeprecated: true`. Используйте это, чтобы вывести переменную из обращения вместо её удаления: сохранение объявленного ключа сохраняет хранимое значение (удаление уничтожает значение, введённое пользователем), а переменная по-прежнему внедряется, поэтому код сможет обратиться к ней — `process.env.NEW_API_KEY ?? process.env.API_KEY`. Устаревшая переменная исчезает из настроек приложения, как только у неё больше нет значения, и никогда не учитывается при проверке конфигурации приложения, поэтому `isDeprecated` имеет приоритет над `isRequired`.
* Чтобы отобразить на вкладке **Settings** приложения пользовательский интерфейс настройки (вместо стандартного раздела настройки переменных), объявите фронтенд‑компонент с помощью [`defineSettingsFrontComponent()`](/l/ru/developers/extend/apps/layout/front-components#custom-settings-component) в отдельном файле. Для каждого приложения допускается только один такой компонент. Разделы, управляемые системой (автообновление, App URL, соединения), всегда остаются видимыми.

## Типы переменных

И `applicationVariables`, и `serverVariables` принимают необязательный `type` (а для `SELECT` / `MULTI_SELECT` — список `options`). Поддерживаемые типы: `TEXT` (по умолчанию), `BOOLEAN`, `NUMBER`, `NUMERIC`, `DATE`, `DATE_TIME`, `SELECT`, `MULTI_SELECT`, `ARRAY`, `RAW_JSON`, `RICH_TEXT`.

```ts src/application-config.ts
import { defineApplication, FieldType } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, role...
  applicationVariables: {
    MAX_POSTCARDS: {
      universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
      description: 'Maximum postcards per batch',
      type: FieldType.NUMBER,
      value: 10,
    },
    DEFAULT_REGION: {
      universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
      description: 'Default shipping region',
      type: FieldType.SELECT,
      options: [
        { label: 'Europe', value: 'eu' },
        { label: 'United States', value: 'us' },
      ],
      value: 'eu',
    },
  },
});
```

Свойство `type` влияет только на **отображение и валидацию** — оно выбирает соответствующий ввод в UI настроек рабочего пространства (переключатель, числовое поле, раскрывающийся список, выбор даты, JSON‑редактор, …) и позволяет сборке проверить вашу конфигурацию (например, `SELECT` / `MULTI_SELECT` должны объявить непустой список `options`). Оно **не** меняет то, как значение попадает в ваш код.

Значения **всегда внедряются как строки** — это заложено в природу переменных окружения (`process.env.*` содержит только строки). Когда выполняется ваша логическая функция, исполнитель сериализует каждое значение в соответствии с объявленным `type` при построении `process.env`, так что строковый формат остается единым, независимо от того, как было задано значение (значение по умолчанию в манифесте, UI настроек или предыдущая версия):

| Тип                                   | строка в `process.env`                              |
| ------------------------------------- | --------------------------------------------------- |
| `TEXT`, `SELECT`, `DATE`, `DATE_TIME` | непреобразованное значение (`"eu"`, `"2026-01-01"`) |
| `BOOLEAN`                             | `"true"` / `"false"`                                |
| `NUMBER`, `NUMERIC`                   | десятичная строка (`"10"`, `"2.5"`)                 |
| `MULTI_SELECT`, `ARRAY`               | JSON‑массив (`'["email","postcard"]'`)              |
| `RAW_JSON`, `RICH_TEXT`               | JSON‑объект (`'{"retries":3}'`)                     |

Преобразуйте строку обратно в ожидаемый вами тип:

```ts
const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }
```

Это же относится к фронтенд‑компонентам, читающим значения через `getApplicationVariable('VARIABLE_NAME')` — возвращаемое значение является строкой; при необходимости преобразуйте его.

## Роль функции по умолчанию

Роль, объявленная с помощью [`defineApplicationRole()`](/l/ru/developers/extend/apps/config/roles), определяет, к чему могут получать доступ логические функции и фронтенд‑компоненты приложения:

* Токены времени выполнения, подставляемые в ваши функции логики, формируются из этой роли. Вызов, выполняемый от имени пользователя, дополнительно ограничен тем, что может делать этот пользователь, поэтому он никогда не может превышать ни один из них. См. [Чей доступ использует вызов](/l/ru/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
* Типизированный клиент API ограничен правами, предоставленными этой роли.
* Следуйте принципу наименьших привилегий: объявляйте только те разрешения, которые действительно нужны вашим функциям.

Когда вы создаёте новое приложение с помощью шаблона, CLI создаёт стартовый файл роли по адресу `src/roles/default-role.ts`. Полную справочную информацию см. в разделе [Роли и разрешения](/l/ru/developers/extend/apps/config/roles).

## Метаданные маркетплейса

Если вы планируете [опубликовать приложение](/l/ru/developers/extend/apps/operations/publishing), эти необязательные поля определяют, как оно отображается в маркетплейсе:

| Поле               | Описание                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `author`           | Имя автора или название компании                                                                                    |
| `category`         | Категория приложения для фильтрации в маркетплейсе                                                                  |
| `logo`             | Путь к вашему логотипу приложения в `public/` (например, `public/logo.png`)                                         |
| `galleryImages`    | Массив путей галереи изображений в комплекте `public/` (например, `public/screenshot-1.png`)                        |
| `aboutDescription` | Расширенное описание в Markdown для вкладки "About". Если опущено, маркетплейс использует `README.md` пакета из npm |
| `websiteUrl`       | Ссылка на ваш сайт                                                                                                  |
| `termsUrl`         | Ссылка на условия предоставления услуг                                                                              |
| `emailSupport`     | Адрес электронной почты поддержки                                                                                   |
| `issueReportUrl`   | Ссылка на систему отслеживания проблем                                                                              |

<Note>
«logoUrl» и «screenshots» являются устаревшими псевдонимами «logo» и «galleryImages». Внешние абсолютные URL-адреса (`http://` или `https://`) не поддерживаются для этих полей: они удаляются с предупреждением на время сборки. Вместо этого объедините изображения в папку `public/` вашего приложения.
</Note>