アプリケーション設定

すべてのアプリは、defineApplication の呼び出しを厳密に 1 つ持つ必要があります。ここでは次の内容を宣言します。

Identity — ユニバーサル識別子、表示名、説明。
Permissions — ロジック関数およびフロントコンポーネントがどのロールで実行されるか。
Variables (optional) — コードから環境変数として利用できるキーと値のペア。
Pre-install / post-install hooks (optional) — Logic Functions を参照してください。

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 フィールドは、あなたが所有する安定した ID です。一度生成し、その後の同期でも安定して維持してください。
applicationVariables は関数やフロントコンポーネントの環境変数になります。ロジック関数（サーバーサイド）では、process.env.VARIABLE_NAME として利用できます。フロントコンポーネントでは、twenty-sdk/front-component の getApplicationVariable('VARIABLE_NAME') を使用します。 isSecret: true が指定された変数は、ロジック関数にのみインジェクトされます。フロントコンポーネントには、秘密ではない変数のみが渡されます。
デフォルトのロールは、defineApplicationRole() でマークされたロールファイルから自動的に検出されます。defineApplication() から参照する必要はありません。
プレインストール関数とポストインストール関数は、マニフェストのビルド中に自動検出されます—defineApplication() で参照する必要はありません。
後方互換性のために defaultRoleUniversalIdentifier を明示的に渡すことも依然としてサポートされていますが、defineApplicationRole() が推奨されるため、非推奨となっています。
serverVariables はインスタンス単位の構成およびシークレット（例: API キー）です。 applicationVariables と異なり、マニフェスト内で値は宣言されません。ワークスペースのオペレーターがアプリの設定からそれらを入力し、設定された時点でのみロジック関数に注入されます。

変数の型

applicationVariables と serverVariables の両方は、オプションの type（および SELECT / MULTI_SELECT の場合は options リスト）を受け取ります。サポートされている型: TEXT (既定), BOOLEAN, NUMBER, NUMERIC, DATE, DATE_TIME, SELECT, MULTI_SELECT, ARRAY, RAW_JSON, RICH_TEXT。

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進数の文字列（`"10"`, `"2.5"`）
`MULTI_SELECT`, `ARRAY`	JSON 配列（`'["email","postcard"]'`）
`RAW_JSON`, `RICH_TEXT`	JSON オブジェクト（`'{"retries":3}'`）

文字列を、想定している型に再度パースしてください:

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() で宣言されたロールは、アプリのロジック関数とフロントコンポーネントがアクセスできる内容を制御します。

TWENTY_APP_ACCESS_TOKEN として注入される実行時トークンは、このロールに基づいて生成されます。
型付き API クライアントは、そのロールに付与された権限に制限されます。
最小権限の原則に従い、関数に必要な権限のみを宣言してください。

新しいアプリをスキャフォルドすると、CLI は src/roles/default-role.ts にスターターロールファイルを作成します。詳細は Roles & Permissions を参照してください。

マーケットプレイスのメタデータ

アプリを公開する予定がある場合、これらの任意フィールドでマーケットプレイスでの表示方法を制御できます:

フィールド	説明
`author`	作成者または会社名
`category`	マーケットプレイスのフィルタリング用のアプリカテゴリ
`logo`	`public/`にバンドルされているアプリのロゴのパス（例：`public/logo.png`）
`galleryImages`	`public/`にバンドルされているギャラリー画像パスの配列（例：`public/screenshot-1.png`）
`aboutDescription`	「About」タブ向けの詳細な Markdown 説明。省略した場合、マーケットプレイスは npm のパッケージにある `README.md` を使用します。
`websiteUrl`	自社ウェブサイトへのリンク
`termsUrl`	利用規約へのリンク
`emailSupport`	サポート用メールアドレス
`issueReportUrl`	課題トラッカーへのリンク

logoUrlとscreenshotsは、logoとgalleryImagesの別名は非推奨です。外部絶対URL (http://またはhttps://) はこれらのフィールドでサポートされていません: ビルド時に警告が表示されます。アプリの public/ フォルダに画像を束ねます。

概要

アプリ

API

セルフホスト

貢献

変数の型

デフォルトの関数ロール

マーケットプレイスのメタデータ

​変数の型

​デフォルトの関数ロール

​マーケットプレイスのメタデータ

変数の型

デフォルトの関数ロール

マーケットプレイスのメタデータ