Apps とは?
Apps を使うと、Twenty のカスタマイズをコードとして構築・管理できます。 Instead of configuring everything through the UI, you define your data model and logic functions in code — making it faster to build, maintain, and roll out to multiple workspaces. 現在できること:- カスタムオブジェクトとフィールドをコードとして定義(管理されたデータモデル)
- Build logic functions with custom triggers
- 同じアプリを複数のワークスペースにデプロイ
- カスタム UI レイアウトとコンポーネント
前提条件
- Node.js 24+ と Yarn 4
- Twenty のワークスペースと API キー(https://app.twenty.com/settings/api-webhooks で作成)
始めに
公式スキャフォルダーで新しいアプリを作成し、認証して開発を開始します:プロジェクト構成(スキャフォルド作成)
npx create-twenty-app@latest my-twenty-app を実行すると、スキャフォルダーは次を行います:
- 最小限のベースアプリケーションを
my-twenty-app/にコピーします - ローカルの
twenty-sdk依存関係と Yarn 4 の設定を追加します twentyCLI と連携する設定ファイルとスクリプトを作成します- デフォルトのアプリケーション設定とデフォルトの関数ロールを生成します
コンベンション優先
アプリケーションは コンベンション優先(設定より規約) のアプローチを採用し、エンティティはファイルのサフィックスで検出されます。 これにより、src/app/ フォルダー内を柔軟に構成できます:
| ファイルサフィックス | エンティティタイプ |
|---|---|
*.object.ts | カスタムオブジェクトの定義 |
*.function.ts | サーバーレス関数の定義 |
*.front-component.tsx | フロントエンドコンポーネントの定義 |
*.role.ts | ロールの定義 |
サポートされるフォルダー構成
エンティティは次のいずれのパターンでも構成できます: 従来型(タイプ別):- package.json: Declares the app name, version, engines (Node 24+, Yarn 4), and adds
twenty-sdkplus scripts likeapp:dev,app:generate,entity:add,function:logs,function:execute,app:uninstall, andauth:loginthat delegate to the localtwentyCLI. - .gitignore:
node_modules、.yarn、generated/(型付きクライアント)、dist/、build/、カバレッジ用フォルダー、ログファイル、.env*ファイルなどの一般的な生成物を無視します。 - yarn.lock、.yarnrc.yml、.yarn/: プロジェクトで使用する Yarn 4 ツールチェーンをロックおよび構成します。
- .nvmrc: プロジェクトで想定する Node.js バージョンを固定します。
- eslint.config.mjs と tsconfig.json: アプリの TypeScript ソース向けの Lint と TypeScript 設定を提供します。
- README.md: アプリのルートにある、基本的な手順を記した短い README。
- src/: The main place where you define your application-as-code:
application.config.ts: アプリのグローバル設定(メタデータとランタイムの接続)。 「アプリケーション設定」を参照してください。*.role.ts: Role definitions used by your logic functions. 「デフォルトの関数ロール」を参照してください。*.object.ts: カスタムオブジェクトの定義。*.function.ts: Logic function definitions.*.front-component.tsx: Front component definitions.
yarn app:generateはgenerated/フォルダー(型付きの Twenty クライアント + ワークスペースの型)を作成します。yarn entity:addwill add entity definition files undersrc/for your custom objects, functions, front components, or roles.
認証
初めてyarn auth:login を実行すると、次が求められます:
- API URL(デフォルトは http://localhost:3000 または現在のワークスペースプロファイル)
- API キー
~/.twenty/config.json に保存されます。 複数のプロファイルを管理し、相互に切り替えることができます。
ワークスペースの管理
auth:switch でワークスペースを切り替えると、その後のすべてのコマンドはデフォルトでそのワークスペースを使用します。 一時的に --workspace <name> で上書きできます。
SDK リソース(型と設定)を使う
twenty-sdk は、アプリ内で使用する型付きのビルディングブロックとヘルパー関数を提供します。 以下は、最も頻繁に扱う主要な構成要素です。ヘルパー関数
この SDK は、アプリのエンティティを定義するための組み込み検証付きヘルパー関数を 4 つ提供します:| 関数 | 目的 |
|---|---|
defineApplication() | アプリケーションのメタデータを構成 |
defineObject() | フィールド付きのカスタムオブジェクトを定義 |
defineFunction() | Define logic functions with handlers |
defineRole() | ロールの権限とオブジェクトアクセスを構成 |
オブジェクトの定義
カスタムオブジェクトは、ワークスペース内のレコードのスキーマと挙動の両方を表します。 組み込み検証付きでオブジェクトを定義するにはdefineObject() を使用します:
- 組み込み検証と優れた IDE サポートのために
defineObject()を使用します。 universalIdentifierは、デプロイをまたいで一意かつ安定している必要があります。- 各フィールドには、
name、type、label、および自身の安定したuniversalIdentifierが必要です。 fields配列は任意です。カスタムフィールドなしでオブジェクトを定義できます。- You can scaffold new objects using
yarn entity:add, which guides you through naming, fields, and relationships.
ベースフィールドは自動作成されます。 カスタムオブジェクトを定義すると、Twenty は
name、createdAt、updatedAt、createdBy、position、deletedAt などの標準フィールドを自動的に追加します。 これらを fields 配列で定義する必要はありません。カスタムフィールドのみを追加してください。アプリケーション設定(application.config.ts)
すべてのアプリには、次の内容を記述する単一のapplication.config.ts ファイルがあります:
- アプリの概要: 識別子、表示名、説明。
- 関数の実行方法: 権限に使用するロール。
- (任意)変数: 関数に環境変数として公開されるキーと値のペア。
defineApplication() を使用します:
universalIdentifierフィールドは、あなたが管理する決定的な ID です。一度生成し、同期をまたいで安定したままにしてください。applicationVariablesは関数の環境変数になります(例:DEFAULT_RECIPIENT_NAMEはprocess.env.DEFAULT_RECIPIENT_NAMEとして利用可能)。defaultRoleUniversalIdentifierは、*.role.tsファイルで定義するロールと一致している必要があります(下記参照)。
ロールと権限
アプリケーションは、ワークスペース内のオブジェクトやアクションに対する権限をカプセル化するロールを定義できます。 The fielddefaultRoleUniversalIdentifier in application.config.ts designates the default role used by your app’s logic functions.
TWENTY_API_KEYとして注入される実行時の API キーは、このデフォルトの関数ロールから派生します。- 型付きクライアントの権限は、そのロールに付与された権限に制限されます。
- 最小権限の原則に従い、関数に必要な権限のみに限定した専用ロールを作成し、そのユニバーサル識別子を参照してください。
デフォルトの関数ロール(*.role.ts)
新しいアプリをスキャフォルドすると、CLI はデフォルトのロールファイルも作成します。 組み込み検証付きでロールを定義するにはdefineRole() を使用します:
universalIdentifier は、application.config.ts で defaultRoleUniversalIdentifier として参照されます。 言い換えると:
- *.role.ts は、デフォルトの関数ロールで可能な操作を定義します。
- application.config.ts でそのロールを指定することで、関数はその権限を継承します。
- スキャフォルドされたロールから開始し、最小権限の原則に従って段階的に制限してください。
objectPermissionsとfieldPermissionsを、関数に必要なオブジェクト/フィールドに置き換えてください。permissionFlagsはプラットフォームレベルの機能へのアクセスを制御します。 最小限に保ち、必要なものだけを追加してください。- 動作例は Hello World アプリにあります: packages/twenty-apps/hello-world/src/roles/function-role.ts。
Logic function config and entrypoint
各関数ファイルは、ハンドラーと任意のトリガーを含む設定をdefineFunction() でエクスポートします。 自動検出のために *.function.ts のファイルサフィックスを使用します。
- route:
/s/エンドポイント配下で、HTTP パスとメソッドで関数を公開します:
例:path: '/post-card/create',-><APP_URL>/s/post-card/createで呼び出し
- cron: CRON 式を使用してスケジュールで関数を実行します。
- databaseEvent: ワークスペースのオブジェクトのライフサイクルイベントで実行されます。 イベント操作が
updatedの場合、監視する特定のフィールドをupdatedFields配列で指定できます。 未定義または空のままにすると、任意の更新でも関数がトリガーされます。
例: person.updated
注記:
triggers配列は任意です。 トリガーのない関数は、他の関数から呼び出されるユーティリティ関数として使用できます。- 1 つの関数で複数のトリガータイプを組み合わせることができます。
ルートトリガーのペイロード
When a route trigger invokes your logic function, it receives aRoutePayload object that follows the AWS HTTP API v2 format. 型を twenty-sdk からインポートします:
RoutePayload 型は次の構造になっています:
| プロパティ | タイプ | 説明 |
|---|---|---|
headers | Record<string, string | undefined> | HTTP ヘッダー (forwardedRequestHeaders に列挙されたもののみ) |
queryStringParameters | Record<string, string | undefined> | クエリ文字列パラメーター (複数の値はカンマで連結) |
pathParameters | Record<string, string | undefined> | ルートパターンから抽出されたパスパラメーター (例: /users/:id → { id: '123' }) |
本文 | object | null | 解析済みのリクエストボディ (JSON) |
isBase64Encoded | ブール型 | body が base64 エンコードされているかどうか |
requestContext.http.method | string | HTTP メソッド (GET, POST, PUT, PATCH, DELETE) |
requestContext.http.path | string | 生のリクエストパス |
HTTP ヘッダーの転送
By default, HTTP headers from incoming requests are not passed to your logic function for security reasons. 特定のヘッダーにアクセスするには、forwardedRequestHeaders 配列に明示的に列挙してください:
ヘッダー名は小文字に正規化されます。 小文字のキーを使用してアクセスしてください (例:
event.headers['content-type'])。- Scaffolded: Run
yarn entity:addand choose the option to add a new function. これにより、ハンドラーと設定を備えたスターターファイルが生成されます。 - 手動: 新しい
*.function.tsファイルを作成し、同じパターンでdefineFunction()を使用します。
生成された型付きクライアント
ワークスペースのスキーマに基づき、generated/ にローカルの型付きクライアントを作成するには yarn app:generate を実行します。 関数内で使用します:yarn app:generate によって再生成されます。 Re-run after changing your objects or when onboarding to a new workspace.
Runtime credentials in logic functions
関数が Twenty 上で実行されると、コードが実行される前に、プラットフォームが認証情報を環境変数として注入します:TWENTY_API_URL: アプリが対象とする Twenty API のベース URL。TWENTY_API_KEY: アプリケーションのデフォルト関数ロールにスコープされた短命のキー。
- 生成されたクライアントに URL や API キーを渡す必要はありません。 実行時に process.env から
TWENTY_API_URLとTWENTY_API_KEYを読み取ります。 - API キーの権限は、
application.config.tsでdefaultRoleUniversalIdentifierによって参照されるロールによって決まります。 This is the default role used by logic functions of your application. - アプリケーションは、最小権限の原則に従うロールを定義できます。 関数に必要な権限のみを付与し、
defaultRoleUniversalIdentifierをそのロールのユニバーサル識別子に指定してください。
Hello World の例
オブジェクト、関数、複数のトリガーを示す最小のエンドツーエンド例はこちらをご覧ください。手動セットアップ(スキャフォルダーなし)
最適な導入体験のためにcreate-twenty-app の使用を推奨しますが、手動でプロジェクトをセットアップすることもできます。 CLI をグローバルにインストールしないでください。 代わりに、twenty-sdk をローカル依存関係として追加し、package.json にスクリプトを設定します:
yarn app:dev, yarn app:generate, etc.
トラブルシューティング
- 認証エラー:
yarn auth:loginを実行し、API キーに必要な権限があることを確認してください。 - サーバーに接続できません: API URL と、Twenty サーバーに到達可能であることを確認してください。
- Types or client missing/outdated: run
yarn app:generate. - 開発モードで同期されない:
yarn app:devが実行中であり、環境によって変更が無視されていないことを確認してください。