trigger-dev-tasks

Trigger.dev タスクエキスパート

本番環境に対応したバックグラウンドジョブシステムの構築を専門とする、Trigger.dev のエキスパート開発者です。Trigger.dev にデプロイされたタスクは Node.js 21 以降で実行され、@trigger.dev/sdk パッケージを使用します。

重要なルール

1. 必ず @trigger.dev/sdk を使用してください — @trigger.dev/sdk/v3 や、非推奨の client.defineJob パターンは使用しないでください
2. node-fetch は使用しないでください — 組み込みの fetch 関数を使用してください
3. すべてのタスクをエクスポートしてください — サブタスクも含め、すべてのタスクをエクスポートする必要があります
4. 待機／トリガー呼び出しを Promise.all でラップしないでください — triggerAndWait、batchTriggerAndWait、および wait.* の呼び出しは、Promise.all や Promise.allSettled でラップできません

基本的なタスクパターン

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

export const processData = task({
  id: "process-data",
  retry: {
    maxAttempts: 10,
    factor: 1.8,
    minTimeoutInMs: 500,
    maxTimeoutInMs: 30_000,
  },
  run: async (payload: { userId: string; data: any[] }) => {
    console.log(`Processing ${payload.data.length} items`);
    return { processed: payload.data.length };
  },
});

スキーマタスク（バリデーション付き）

import { schemaTask } from "@trigger.dev/sdk";
import { z } from "zod";

export const validatedTask = schemaTask({
  id: "validated-task",
  schema: z.object({
    name: z.string(),
    email: z.string().email(),
  }),
  run: async (payload) => {
    // Payload is automatically validated and typed
    return { message: `Hello ${payload.name}` };
  },
});

タスクのトリガー

バックエンドコードから（依存関係の漏出を防ぐため、型のみをインポート）

import { tasks } from "@trigger.dev/sdk";
import type { processData } from "./trigger/tasks";

const handle = await tasks.trigger<typeof processData>("process-data", {
  userId: "123",
  data: [{ id: 1 }],
});

タスク内から

export const parentTask = task({
  id: "parent-task",
  run: async (payload) => {
    // Trigger and wait - returns Result object, NOT direct output
    const result = await childTask.triggerAndWait({ data: "value" });
    if (result.ok) {
      console.log("Output:", result.output);
    } else {
      console.error("Failed:", result.error);
    }

    // Or unwrap directly (throws on error)
    const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
  },
});

冪等性（リトライ時に重要）

別のタスク内からタスクをトリガーする場合は、必ず冪等性キーを使用してください。

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

export const paymentTask = task({
  id: "process-payment",
  run: async (payload: { orderId: string }) => {
    // Scoped to current run - survives retries
    const key = await idempotencyKeys.create(`payment-${payload.orderId}`);

    await chargeCustomer.trigger(payload, {
      idempotencyKey: key,
      idempotencyKeyTTL: "24h",
    });
  },
});

トリガーオプション

await myTask.trigger(payload, {
  delay: "1h",           // Delay execution
  ttl: "10m",            // Cancel if not started within TTL
  idempotencyKey: key,
  queue: "my-queue",
  machine: "large-1x",   // micro, small-1x, small-2x, medium-1x, medium-2x, large-1x, large-2x
  maxAttempts: 3,
  tags: ["user_123"],    // Max 10 tags
  debounce: {            // Consolidate rapid triggers
    key: "unique-key",
    delay: "5s",
    mode: "trailing",    // "leading" (default) or "trailing"
  },
});

デバウンス

複数のトリガーを単一の実行にまとめます。

// Rapid triggers with same key = single execution
await myTask.trigger({ userId: "123" }, {
  debounce: {
    key: "user-123-update",
    delay: "5s",
  },
});

// Trailing mode: use payload from LAST trigger
await myTask.trigger({ data: "latest" }, {
  debounce: {
    key: "my-key",
    delay: "10s",
    mode: "trailing",
  },
});

ユースケース：ユーザーアクティビティの更新、Webhook の重複排除、検索インデックス作成、通知のバッチ処理。

バッチトリガー

1 バッチあたり最大 1,000 件、ペイロードは 3MB までです。

const results = await myTask.batchTriggerAndWait([
  { payload: { userId: "1" } },
  { payload: { userId: "2" } },
]);

for (const result of results) {
  if (result.ok) console.log(result.output);
}

マシンプリセット

プリセット	vCPU	メモリ
micro	0.25	0.25GB
small-1x	0.5	0.5GB
small-2x	1	1GB
medium-1x	1	2GB
medium-2x	2	4GB
large-1x	4	8GB
large-2x	8	16GB

設計原則

1. 複雑なワークフローは、個別にリトライでき、冪等性を確保できるサブタスクに分割してください
2. 過度に複雑にしないでください — 多数のサブタスクに分割するより、単一のタスク内で Promise.allSettled を使うほうが適切な場合もあります（各タスクには専用のプロセスが割り当てられ、ミリ秒単位で課金されます）
3. 必ずリトライを設定してください — 操作に応じて適切な maxAttempts を設定してください
4. 冪等性キーを使用してください — 特に決済や重要な操作では必須です
5. 関連するサブタスクをまとめてください — 1 つの親タスクからしか使われないサブタスクは、同じファイルにまとめ、エクスポートしないでください
6. ロガーを使用してください — logger.info()、logger.error() などで、実行の重要な時点をログに記録してください

参考ドキュメント

特定のトピックの詳細については、次のファイルをお読みください。

• basic-tasks.md — タスクの基本、トリガー、待機
• advanced-tasks.md — タグ、キュー、並行性、メタデータ、エラー処理
• scheduled-tasks.md — Cron スケジュール、宣言型と命令型
• realtime.md — リアルタイムサブスクリプション、ストリーム、React フック
• config.md — trigger.config.ts、ビルド拡張機能（Prisma、Playwright、FFmpeg など）