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

​
Обзор

После того как ваше приложение собрано и протестировано локально, у вас есть два пути для его распространения:
  • Разверните tar-архив — загрузите своё приложение напрямую на конкретный сервер Twenty для внутреннего или частного использования.
  • Опубликовать в npm — разместите ваше приложение в маркетплейсе Twenty, чтобы любое рабочее пространство могло его найти и установить.
Оба пути начинаются с одного и того же шага build.

​
Сборка вашего приложения

Выполните команду сборки, чтобы скомпилировать приложение и сгенерировать готовый к распространению manifest.json: 
yarn twenty build
Это компилирует исходные файлы TypeScript, транспилирует функции логики и фронтенд-компоненты и записывает всё в .twenty/output/. Добавьте --tarball, чтобы также создать пакет .tgz для ручного распространения или для команды deploy.

​
Развертывание на сервер (tarball)

Для приложений, которые вы не хотите делать общедоступными — собственные инструменты, интеграции только для предприятий или экспериментальные сборки — вы можете развернуть tarball напрямую на сервер Twenty.

​
Требования

Перед развертыванием вам нужен настроенный remote, указывающий на целевой сервер. Remotes локально хранят URL сервера и учётные данные аутентификации в ~/.twenty/config.json. Добавьте remote: 
yarn twenty remote add --api-url https://your-twenty-server.com --as production

​
Развертывание

Соберите и загрузите ваше приложение на сервер в одном шаге: 
yarn twenty deploy
# To deploy to a specific remote:
# yarn twenty deploy --remote production

​
Общий доступ к развернутому приложению

Совместный доступ к частным приложениям (tarball) между рабочими пространствами — функция уровня Enterprise. Вкладка Distribution будет показывать предложение обновиться вместо элементов управления совместным доступом, пока в вашем рабочем пространстве не будет действительного ключа Enterprise. Перейдите в Настройки > Панель администратора > Enterprise, чтобы включить её.
Приложения в формате tarball не отображаются в публичном маркетплейсе, поэтому другие рабочие пространства на том же сервере не найдут их при просмотре. Как только ваше рабочее пространство перейдёт на тарифный план Enterprise, вы сможете поделиться развёрнутым приложением следующим образом:
  1. Перейдите в Настройки > Приложения > Регистрации и откройте ваше приложение
  2. На вкладке Распространение нажмите Копировать ссылку для общего доступа
  3. Поделитесь этой ссылкой с пользователями в других рабочих пространствах — она ведёт их прямо на страницу установки приложения
Ссылка общего доступа использует базовый URL сервера (без какого-либо поддомена рабочего пространства), поэтому она работает для любого рабочего пространства на сервере.

​
Управление версиями

When updating an already deployed tarball app, the server requires the version in package.json to be strictly higher (per semver ordering) than the currently deployed version. Повторное развёртывание той же версии или публикация более низкой версии отклоняются до сохранения tarball — в CLI вы увидите ошибку VERSION_ALREADY_EXISTS. Чтобы выпустить обновление:
  1. Увеличьте значение поля version в вашем package.json (например: 1.2.3 → 1.2.4, 1.3.0 или 2.0.0).
  2. Выполните yarn twenty deploy (или yarn twenty deploy --remote production)
  3. Рабочие пространства, в которых установлено приложение, увидят доступное обновление в своих настройках
Пререлизные теги работают как ожидается: повышение версии 1.0.0-rc.1 → 1.0.0-rc.2 допускается, а финальный релиз вроде 1.0.0 корректно распознаётся как более высокий, чем 1.0.0-rc.5. Версия в package.json должна сама по себе быть корректной строкой semver.

​
Публикация в npm

Публикация в npm делает ваше приложение видимым в маркетплейсе Twenty. Любое рабочее пространство Twenty может просматривать, устанавливать и обновлять приложения из маркетплейса непосредственно из интерфейса.

​
Требования

  • Учётная запись npm
  • Ключевое слово twenty-app в массиве keywords вашего package.json (уже добавлено при создании проекта с помощью create-twenty-app)
{
  "name": "twenty-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["twenty-app"]
}

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

Конфигурация defineApplication() поддерживает необязательные поля, которые определяют, как ваше приложение отображается в маркетплейсе. Используйте logoUrl и screenshots, чтобы ссылаться на изображения из папки public/:
src/application-config.ts
export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});
См. аккордеон defineApplication на странице «Создание приложений» для полного списка полей маркетплейса (author, category, aboutDescription, websiteUrl, termsUrl и т. д.).

​
Публикация

yarn twenty publish
Чтобы опубликовать с определённым dist-tag (например, beta или next): 
yarn twenty publish --tag beta

​
Как работает обнаружение приложений в маркетплейсе

Сервер Twenty синхронизирует каталог маркетплейса из реестра npm каждый час. Вы можете запустить синхронизацию немедленно, вместо ожидания: 
yarn twenty catalog-sync
# To target a specific remote:
# yarn twenty catalog-sync --remote production
Метаданные, отображаемые в маркетплейсе, берутся из конфигурации defineApplication() — из таких полей, как displayName, description, author, category, logoUrl, screenshots, aboutDescription, websiteUrl и termsUrl.
Если ваше приложение не определяет aboutDescription в defineApplication(), маркетплейс автоматически использует README.md вашего пакета из npm в качестве содержимого страницы «О приложении». Это означает, что вы можете поддерживать единый README как для npm, так и для маркетплейса Twenty. Если вы хотите другое описание в маркетплейсе, явно задайте aboutDescription.

​
Публикация через CI

Используйте этот workflow GitHub Actions, чтобы публиковать автоматически при каждом релизе (использует OIDC): 
name: Publish
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          registry-url: https://registry.npmjs.org
      - run: yarn install --immutable
      - run: npx twenty build
      - run: npm publish --provenance --access public
        working-directory: .twenty/output
Для других CI-систем (GitLab CI, CircleCI и др.) применимы те же три команды: yarn install, yarn twenty build, затем npm publish из .twenty/output.
npm provenance — опционально, но рекомендуется. Публикация с флагом --provenance добавляет к вашему пакету в npm значок доверия, позволяя пользователям проверить, что пакет был собран из конкретного коммита в общедоступном конвейере CI. См. инструкции по настройке в документации по npm provenance.

​
Установка приложений

После публикации приложения (npm) или его развертывания (tarball) рабочие пространства могут установить его через интерфейс. Перейдите на страницу Настройки > Приложения в Twenty, где можно просматривать и устанавливать как приложения из маркетплейса, так и развернутые через tarball. Вы также можете устанавливать приложения из командной строки: 
yarn twenty install
Сервер при установке применяет версионирование semver, аналогичное правилам при развёртывании:
  • Установка той же версии, которая уже установлена в вашем рабочем пространстве, отклоняется с ошибкой APP_ALREADY_INSTALLED.
  • Установка версии ниже текущей отклоняется с ошибкой CANNOT_DOWNGRADE_APPLICATION.
Чтобы установить более новую версию, сначала разверните или опубликуйте её, затем снова выполните yarn twenty install.