最初の Workflow を作る

ターミナルを開き、create cloudflare (C3) CLI ツールを実行して Worker プロジェクトを作成します。

npm create cloudflare@latest -- my-workflow

yarn create cloudflare my-workflow

pnpm create cloudflare@latest my-workflow

セットアップでは、次のオプションを選びます。

• What would you like to start with? では、Hello World example を選びます。
• Which template would you like to use? では、Worker only を選びます。
• Which language do you want to use? では、TypeScript を選びます。
• Do you want to use git for version control? では、Yes を選びます。
• Do you want to deploy your application? では、No を選びます（デプロイ前にいくつか変更します）。

新しいプロジェクトディレクトリへ移動します。

cd my-workflow

新しいファイル src/workflow.ts を作成します。

import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";
import type { WorkflowEvent } from "cloudflare:workers";

type Params = { name?: string };
type IPResponse = { result: { ipv4_cidrs: string[] } };

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		const data = await step.do("fetch data", async () => {
			const response = await fetch(
				"https://api.cloudflare.com/client/v4/ips",
			);
			return await response.json<IPResponse>();
		});

		await step.sleep("pause", "20 seconds");

		const result = await step.do(
			"process data",
			{ retries: { limit: 3, delay: "5 seconds", backoff: "linear" } },
			async () => {
				return {
					name: event.payload.name ?? "World",
					ipCount: data.result.ipv4_cidrs.length,
				};
			},
		);

		return result;
	}
}

Workflow は WorkflowEntrypoint を継承し、run メソッドを実装します。このコードでは、Workflow を起動するイベントに型が付くよう、Params 型を 型パラメーター として渡しています。

step オブジェクトは、Workflows API の中核です。Workflow 内の耐久性のあるステップを定義するメソッドを提供します。

• step.do(name, callback) - コードを実行し、結果を永続化します。Workflow が中断または再試行されても、完了済みの処理をやり直さず、最後に成功したステップから再開します。コールバックはシリアライズ可能なデータを返します。JavaScript の Workflows では、大きなバイナリ出力向けに ReadableStream<Uint8Array> も含められます。
• step.sleep(name, duration) - 指定した時間（例: "10 seconds"、"1 hour"）Workflow を一時停止します。

ストリームを返す場合は、未使用でロックされていない新しい ReadableStream<Uint8Array> を返します。BYOB ストリームと BYOB リーダーはサポートされていません。

失敗時の扱いをカスタマイズするには、step.do() に 再試行の設定 を渡せます。ストリームの要件、制限、sleepUntil や waitForEvent などの追加メソッドは、step API 全体 を参照してください。

コードを別ステップに分けるかは、「一部分だけ失敗したときに、このコード全体をやり直したいか」で判断します。外部 API の呼び出し、データベースのクエリ、ストレージからのファイル読み取りなどは、別ステップが向いています。あとのステップが失敗しても、すでに取得したデータを使ってその地点から再試行でき、余分な API 呼び出しやデータベースクエリを避けられます。

Workflow のロジックの定義については、Rules of Workflows を参照してください。

Workers プロジェクトと Workflow の Wrangler 設定ファイル である wrangler.jsonc を開き、workflows 設定を追加します。

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-workflow",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"observability": {
		"enabled": true
	},
	"workflows": [
		{
			"name": "my-workflow",
			"binding": "MY_WORKFLOW",
			"class_name": "MyWorkflow"
		}
	]
}

"$schema" = "node_modules/wrangler/config-schema.json"
name = "my-workflow"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-09-20"

[observability]
enabled = true

[[workflows]]
name = "my-workflow"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"

class_name はエクスポートしたクラスと一致させる必要があります。binding は、コード内で Workflow にアクセスする変数名です（env.MY_WORKFLOW など）。

同じ Workflow を一定間隔で自動実行したい場合は、Workflow 定義に schedules を追加します。

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-workflow",
  "main": "src/index.ts",
  // Set this to today's date
  "compatibility_date": "2026-09-20",
  "workflows": [
    {
      "name": "my-workflow",
      "binding": "MY_WORKFLOW",
      "class_name": "MyWorkflow",
      "schedules": ["0 * * * *"]
    }
  ]
}

"$schema" = "node_modules/wrangler/config-schema.json"
name = "my-workflow"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-09-20"

[[workflows]]
name = "my-workflow"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"
schedules = [ "0 * * * *" ]

一致する各 cron 式が新しい Workflow インスタンスを自動作成するため、Workflow 専用の定期実行にトップレベルの triggers.crons と別の scheduled ハンドラーは不要です。

スケジュールされたインスタンスでは、一致した cron 式とスケジュールされたトリガー時刻が event.schedule に含まれます。

Workflow のスケジュールを設定するときは、最新の Wrangler リリースを使います。ローカルの Wrangler スキーマがまだ schedules を認識しない場合は、デプロイ前に Wrangler を更新してください。

Workflow 内では、this.env 経由で bindings（KV、R2、D1 など）にもアクセスできます。Workers 内の bindings の詳細は、Bindings (env) を参照してください。

次に、bindings の型を生成します。

npx wrangler types

これで、MY_WORKFLOW binding を含む Env 型付きの worker-configuration.d.ts ファイルが作成されます。

src/index.ts を、Workflow インスタンスの開始と確認用の fetch ハンドラー に置き換えます。

export { MyWorkflow } from "./workflow";

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const instanceId = url.searchParams.get("instanceId");

		if (instanceId) {
			const instance = await env.MY_WORKFLOW.get(instanceId);
			return Response.json(await instance.status());
		}

		const instance = await env.MY_WORKFLOW.create();
		return Response.json({ instanceId: instance.id });
	},
} satisfies ExportedHandler<Env>;

ローカル開発サーバーを起動します。

npx wrangler dev

Workflow インスタンスを開始するには、新しいターミナルウィンドウを開き、次を実行します。

curl http://localhost:8787

instanceId が自動生成されます。

{ "instanceId": "abc-123-def" }

返された instanceId で状態を確認します。

curl "http://localhost:8787?instanceId=abc-123-def"

Workflow はステップを進みます。約 20 秒後（sleep の時間）に完了します。

Workflow をデプロイします。

npx wrangler deploy

本番では、デプロイした URL に対して同じ curl コマンドでテストできます。本番では、Workers、Wrangler、または Cloudflare ダッシュボードから Workflow インスタンスを起動 することもできます。

デプロイ後は、CLI で Workflow インスタンスを調べることもできます。

npx wrangler workflows instances describe my-workflow latest

instances describe の出力には、次が表示されます。

• 各ステップの状態（success、failure、running）
• ステップが出力した状態。ストリーム出力の場合、CLI は全文ではなくプレビューまたは要約を表示します
• sleep の状態（Workflow が起きる時刻を含む）
• 各ステップに関連する再試行
• エラー（例外メッセージを含む）