trigger-setup

Trigger.dev を使い始める

既存のプロジェクトに Trigger.dev をセットアップします。完了時には、SDK がインストールされ、プロジェクト参照先を指定した trigger.config.ts があり、少なくとも 1 つのエクスポート済みタスクを含む /trigger ディレクトリがあり、ダッシュボードにタスクが表示されるよう trigger dev が実行されている状態になります。

最も手早い方法は、CLI のウィザードを使うことです。以下の手順をすべて自動で実行し、MCP サーバーとこれらのエージェントスキルのインストールも提案します。

npx trigger.dev@latest init

可能な場合は init を使ってください。init が適さない場合（モノレポ、既存の設定の拡張、または非対話型環境）は、後述の手動手順を実行してください。

認証にはユーザー本人の操作が必要です

CLI からアカウント作成を開始できますが、メールアドレスの確認とアクセスの認可はユーザー本人が行う必要があります。エージェントのセッションでは、CLI の処理を待ち続ける代わりに、中断後に再開できるログインを開始してください。

npx trigger.dev@latest login --email [email protected] --name "Alex Smith" --no-browser --no-wait

表示された URL をユーザーに渡し、サインインと認可を完了してもらってください。ユーザーから完了の連絡を受けたら、保存済みの認可を再開します。

npx trigger.dev@latest login --no-browser

ユーザーに代わってアカウントを作成したり、CLI アクセスを承認したりしないでください。認証が完了すると、trigger init により、ダッシュボードへ移動せずに最初の組織とプロジェクトを作成できます。セルフホスト型のインスタンスでは組織の作成が無効になっている場合があります。その場合は、まずインスタンスのダッシュボードで組織を作成するようユーザーに依頼してください。

手動セットアップ

1. 認証する（ユーザー本人による認可が必要です）

対話型のターミナルでは、次のようにします。

npx trigger.dev@latest login

エージェントまたはヘッドレスのターミナルでは、前述の中断後に再開できるフローを使用してください。セルフホストの場合は、両方のコマンドに --api-url https://your-trigger-instance.com を追加してください。

2. パッケージをインストールする

@trigger.dev/sdk は実行時依存関係、@trigger.dev/build は開発依存関係です。両方を、実行する trigger.dev CLI と同じバージョンに固定してください。バージョンが一致しない場合、dev／deploy の実行時に CLI が警告します。

npm add @trigger.dev/sdk@latest
npm add --save-dev @trigger.dev/build@latest

3. trigger.config.ts を作成する

プロジェクトのルートに作成してください（JavaScript の場合は trigger.config.mjs）。必須フィールドは project 参照先と dirs のみです。

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>", // e.g. "proj_abc123", from the dashboard
  dirs: ["./src/trigger"], // where your tasks live
  maxDuration: 3600,
  retries: {
    enabledInDev: false,
    default: { maxAttempts: 3, factor: 2, minTimeoutInMs: 1000, maxTimeoutInMs: 10000, randomize: true },
  },
});

runtime: "bun" を追加すると、Bun ランタイムを使用できます。ビルド拡張機能（prismaExtension、puppeteer、additionalFiles など）は @trigger.dev/build からインポートし、build.extensions に指定します。

4. 最初のタスクを追加する

dirs に一致するディレクトリを作成し、そのディレクトリからタスクをエクスポートしてください。すべてのタスクは名前付きエクスポートとし、プロジェクト内で一意の id を指定する必要があります。

// src/trigger/example.ts
import { task } from "@trigger.dev/sdk";

export const helloWorld = task({
  id: "hello-world",
  run: async (payload: { name: string }) => {
    return { message: `Hello ${payload.name}!` };
  },
});

5. tsconfig と gitignore を設定する

tsconfig.json の include 配列に trigger.config.ts を追加し、.gitignore に .trigger を追加してください（CLI はローカル開発状態をそこに書き込みます）。

// tsconfig.json
{ "include": ["trigger.config.ts" /* ...existing */] }

# .gitignore
.trigger

6. 環境 API キーを作成する（ユーザー本人の操作が必要です）

独自のコードからトリガーする場合は、Development 環境で Trigger only アクセス権を持つ名前付き API キーを作成し、TRIGGER_SECRET_KEY に設定してください。セルフホストを利用する場合は、TRIGGER_API_URL も設定します。

# .env (or .env.local for Next.js)
TRIGGER_SECRET_KEY=tr_dev_sk_xxxxxxxx

7. 開発サーバーを実行する

npx trigger.dev@latest dev

実行したままにしてください。タスクがダッシュボードに登録されます。ユーザーはタスクのテストページからテスト実行を開始できます。初回起動時に CLI から MCP サーバーとエージェントスキルのインストールを提案されるので、両方をおすすめしてください。

アプリからトリガーする

タスクを作成したら、タスクのコードがアプリにバンドルされないよう、バックエンドコードから 型のみ をインポートしてトリガーします。タスクオブジェクトを呼び出すのではなく、ID でトリガーしてください。

import { tasks } from "@trigger.dev/sdk";
import type { helloWorld } from "@/trigger/example"; // type-only

const handle = await tasks.trigger<typeof helloWorld>("hello-world", { name: "Ada" });

この処理を実行する場所すべてで TRIGGER_SECRET_KEY を設定する必要があります。フレームワーク固有の詳細については、Next.js／Remix／Node.js のガイドを参照してください。

モノレポ

どちらのレイアウトもサポートされています。タスクを共有パッケージ（独自の trigger.config.ts を持つ @repo/tasks。workspace:* を使って利用）に配置するか、必要なアプリに Trigger.dev を直接インストールします。trigger.config.ts があるディレクトリから trigger dev を実行してください。どちらの方法でも構成を始める前に、手動セットアップのドキュメントで Turborepo の完全な例を確認してください。

よくある間違い

1. ログイン時にエージェントのセッションをブロックする。 メールの確認と認証にはユーザーが必要ですが、CLI の認証は後から再開できます。

   • 誤り：エージェントのセッションで trigger login を起動し、無期限にポーリングする。
   • 正しい方法：trigger login --email <email> --name <full-name> --no-browser --no-wait を実行して URL をユーザーに渡し、承認後に trigger login --no-browser で再開します。

2. CLI と SDK のバージョンが一致していない。 trigger.dev CLI と @trigger.dev/sdk のメジャーバージョンが異なると、開発やデプロイが失敗します。

   • 誤り：古いバージョンに固定された SDK に対して npx trigger.dev@latest dev を実行する。
   • 正しい方法：trigger.dev、@trigger.dev/sdk、@trigger.dev/build のバージョンをそろえます。

3. @trigger.dev/sdk/v3 からインポートする、または client.defineJob() を使う。 どちらも古い方法です。

   • 正しい方法：常に @trigger.dev/sdk からインポートし、task() でタスクを定義します。

4. タスクがエクスポートされていない、または dirs の外にある。 設定したディレクトリ内に名前付きエクスポートとして存在しないタスクは検出されません。

   • 正しい方法：dirs のパス配下のファイルで export const ... = task({ ... }) とします。

5. タスクのインスタンスをバックエンドのコードにインポートする。 タスクがバンドルに含まれてしまいます。

   • 誤り：ルートハンドラーで import { helloWorld } from "@/trigger/example" とする。
   • 正しい方法：import type { helloWorld } に加え、tasks.trigger<typeof helloWorld>("hello-world", payload) を使います。

6. TRIGGER_SECRET_KEY を設定し忘れる。 アプリからのトリガーはこのキーがないと失敗します。CLI にログイン済みであれば、dev サーバー自体は動作します。

参考資料

関連するスキル：

• trigger-tasks：セットアップ完了後にタスク自体を作成するためのスキルです。リトライ、待機、キュー、スケジュール済みタスク、トリガー、trigger.config.ts 全体を扱います。
• trigger-realtime：フロントエンドに実行状況をリアルタイムで表示するためのスキルです。
• trigger-authoring-chat-agent と trigger-chat-agent-advanced：AI チャットエージェントを構築するためのスキルです。

ドキュメント：

• クイックスタート
• 手動セットアップ
• 設定ファイル

バージョン

@trigger.dev/sdk 4.7.4 用に生成されています。アップグレード後は、trigger.dev のスキルインストーラーを再実行してください。