インストールフック

インストールフックは、インストールまたはアップグレードのライフサイクル中に実行される特別なロジック関数です。これらは通常のロジック関数と同じハンドラーランタイムを共有し、InstallPayload（{ previousVersion?: string; newVersion: string } — 新規インストールでは previousVersion は undefined）を受け取りますが、独自の define 関数で宣言され、通常のトリガーモデル (HTTP、cron、データベースイベント) の外側で動作します。各アプリは、プレインストール関数は最大 1 つ、ポストインストール関数も最大 1 つまで定義できます。どちらかが複数検出された場合、マニフェストのビルドはエラーになります。

┌─────────────────────────────────────────────────────────────┐
│ install flow                                                │
│                                                             │
│   upload package → [pre-install] → metadata migration →     │
│   generate SDK → [post-install]                             │
│                                                             │
│                  old schema visible    new schema visible   │
└─────────────────────────────────────────────────────────────┘

ひと目でわかる概要

	`definePreInstallLogicFunction`	`definePostInstallLogicFunction`
実行タイミング	メタデータマイグレーションの前 — 以前のスキーマとデータはまだそのまま残っている	マイグレーションと SDK 生成の後 — 新しいスキーマが適用されている
実行	常に同期的であり、インストールをブロックする	デフォルトでは非同期（キュー投入され、最大 3 回再試行）；`shouldRunSynchronously: true` の指定で同期実行に切り替え可能
失敗時	スキーマ変更の前にインストールが中止される	非同期: 最大 3 回まで再試行される。同期: 呼び出し元は `POST_INSTALL_ERROR` を受け取る（スキーマ変更はロールバックされない）
典型的な用途	マイグレーションで失われるデータのバックアップや修復を行う；スローすることでリスクの高いアップグレードを拒否する	デフォルトデータのシーディング、ワークスペースの構成、外部リソースの登録

経験則: 既定では post-install を使用する。マイグレーション自体が破壊的で、消える前の状態を先に扱う必要がある場合にのみ、pre-install を使ってください。

やりたいこと…	使用
データのシーディング、ワークスペースの構成、外部リソースの登録	`post-install`
インストール応答をブロックすべきでない長時間処理を実行する	`post-install`（既定の非同期モード。ワーカーによる再試行あり）
インストールが返った直後に呼び出し元がすぐに依存する高速なセットアップを実行する	`post-install`（`shouldRunSynchronously: true` を指定）
次のマイグレーションで失われるデータを読み取る、またはバックアップする	`pre-install`
既存データを破損させる恐れのあるアップグレードを拒否する	`pre-install`（ハンドラーからスロー）
すべてのアップグレードで調整処理を実行する	`shouldRunOnVersionUpgrade: true` を指定したいずれかのフック

両方のフックに共通する動作

設定は、トリガー設定を除いた defineLogicFunction の設定に shouldRunOnVersionUpgrade を加えたものです。
実行タイミング: 既定では新規インストール時のみ。アップグレード時にも実行するには、shouldRunOnVersionUpgrade: true を設定します。 previousVersion / newVersion を使って、アップグレードパスに応じて分岐させます。
べき等性が重要です: 非同期 post-install は再試行される可能性があり、さらに shouldRunOnVersionUpgrade が有効な場合はいずれのフックもアップグレード時に再実行されます。
通常のロジック関数の環境（APPLICATION_ID、APP_ACCESS_TOKEN、API_URL）が注入されるため、アプリのトークンを使って Twenty API を呼び出せます。
フックはビルド時に自動的にアプリケーションマニフェストにアタッチされます（preInstallLogicFunction / postInstallLogicFunction）。defineApplication() 内で参照する必要はありません。
デフォルトの timeoutSeconds は 300 に設定されており、データシーディングのような長めのセットアップ作業を許容します。
開発モードでは実行されません: yarn twenty dev はインストールフローをスキップしてファイルを直接同期するため、フックはそこで一切実行されません。代わりに手動でトリガーしてください:

yarn twenty dev:function:exec --postInstall
yarn twenty dev:function:exec --preInstall

definePostInstallLogicFunction

ワークスペースのメタデータマイグレーションが適用された後に実行されます

アプリのインストールが完了した後に実行されます: メタデータは同期され、SDK クライアントが生成され、新しいスキーマはクエリ可能な状態になります。例 — 新規インストール時に既定のレコードをシードする:

src/logic-functions/post-install.ts

import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
  if (previousVersion) return; // fresh installs only

  const client = new CoreApiClient();
  await client.mutation({
    createPostCard: {
      __args: { data: { name: 'Welcome to Postcard', content: 'Your first card!' } },
      id: true,
    },
  });
};

export default definePostInstallLogicFunction({
  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
  name: 'post-install',
  description: 'Seeds a welcome post card after install.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: false,
  shouldRunSynchronously: false,
  handler,
});

shouldRunSynchronously フラグは実行モデルを制御します:

false (既定) — メッセージキューに投入され（retryLimit: 3）、ワーカーによって実行される。ジョブがキューに投入されるとすぐにインストールのレスポンスが返ります。 長時間実行される処理に使用 — 大規模データセットのシーディング、低速なサードパーティ API など。
true — インストールフロー中にインラインで実行される。ハンドラーが終了するまでインストールリクエストはブロックされます。スローされたエラーは POST_INSTALL_ERROR として呼び出し元に伝播します（再試行なし）。 高速かつ、レスポンス前に完了している必要がある処理に使用します。 この時点ではマイグレーションはすでに適用済みであるため、失敗してもスキーマ変更はロールバックされず、エラーが表面化するだけです。

definePreInstallLogicFunction

ワークスペースのメタデータマイグレーションが適用される前に実行されます

メタデータマイグレーションの前、以前のスキーマに対して実行されます — マイグレーションで失われるデータをバックアップしたり、リスクの高いアップグレードを拒否したりするのに適した場所です。実行前に、サーバーは純粋に追加のみの「簡易同期」を実行し、新しいバージョンのプレインストール関数だけを登録します。あなたのハンドラーが実行される際には、それ以外 — 以前のバージョンのオブジェクト、フィールド、データ — には一切手を触れません。プレインストールは常に同期的であり、インストールをブロックします。ハンドラーがスローした場合、スキーマ変更が行われる前にインストールは中止され、ワークスペースは一貫した状態のまま前のバージョンに留まります。これは意図的な設計です。プレインストールは、リスクの高いアップグレードを拒否できる最後の機会です。例 — マイグレーションでレガシーフィールドが削除される前に、その値をコピーする:

src/logic-functions/pre-install.ts

import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
    return;
  }

  const client = new CoreApiClient();
  const { postCards } = await client.query({
    postCards: {
      __args: { filter: { notes: { isNot: null } } },
      edges: { node: { id: true, notes: true } },
    },
  });

  // Copy legacy `notes` into `description` before the migration drops the
  // column. If this fails, the upgrade aborts and the workspace stays on v1.
  for (const { node } of postCards.edges) {
    await client.mutation({
      updatePostCard: {
        __args: { id: node.id, data: { description: node.notes } },
        id: true,
      },
    });
  }
};

export default definePreInstallLogicFunction({
  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  name: 'pre-install',
  description: 'Backs up legacy notes into description before the v2 migration.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: true,
  handler,
});

概要

アプリ

API

セルフホスト

貢献

ひと目でわかる概要

両方のフックに共通する動作

​ひと目でわかる概要

​両方のフックに共通する動作

ひと目でわかる概要

両方のフックに共通する動作