> ## Documentation Index
> Fetch the complete documentation index at: https://twenty-claude-cool-pascal-5ay683.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# アプリケーション設定

> `defineApplication` を使用して、アプリの識別情報、デフォルトのロール、変数、およびマーケットプレイスのメタデータを宣言します。

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

* **Identity** — ユニバーサル識別子、表示名、説明。
* **Permissions** — ロジック関数およびフロントコンポーネントがどのロールで実行されるか。
* **Variables** *(optional)* — コードから環境変数として利用できるキーと値のペア。
* **プレインストール / ポストインストール / アンインストール フック** *(任意)* — [Logic Functions](/l/ja/developers/extend/apps/logic/logic-functions) を参照してください。

```ts src/application-config.ts theme={null}
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()`](/l/ja/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** タブ内で（デフォルトの変数設定セクションの代わりに）カスタム設定 UI をレンダーするには、専用のファイル内で [`defineSettingsFrontComponent()`](/l/ja/developers/extend/apps/layout/front-components#custom-settings-component) を使用してフロントコンポーネントを宣言します。 アプリごとに 1 つのみ許可されています。 システム管理のセクション（自動アップグレード、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 theme={null}
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}'`）    |

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

```ts theme={null}
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/ja/developers/extend/apps/config/roles) で宣言されたロールは、アプリのロジック関数とフロントコンポーネントがアクセスできる内容を制御します。

* ロジック関数に注入される実行時トークンは、このロールに基づいて生成されます。 人物として動作する呼び出しは、その人物が実行できる範囲によってさらに制限されるため、どちらか一方の権限を超えることはありません。 [呼び出しで使用されるアクセス権](/l/ja/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)を参照してください。
* 型付き API クライアントは、そのロールに付与された権限に制限されます。
* 最小権限の原則に従い、関数に必要な権限のみを宣言してください。

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

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

アプリを[公開](/l/ja/developers/extend/apps/operations/publishing)する予定がある場合、これらの任意フィールドでマーケットプレイスでの表示方法を制御できます:

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

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