Vytvoření prvního Workflow

npm create cloudflare@latest workflows-starter -- --template "cloudflare/workflows-starter"

1. Otevřete terminál a spusťte create cloudflare (C3), nástroj CLI pro vytvoření vašeho projektu Worker:

   npmyarnpnpm

   npm create cloudflare@latest -- my-workflow

   Při nastavení vyberte následující možnosti:

   • Pro S čím byste chtěli začít?, vyberte Hello World example.
   • Pro Jakou šablonu chcete použít?, vyberte Worker only.
   • Pro Jaký jazyk chcete použít?, vyberte TypeScript.
   • Pro Chcete používat git pro správu verzí?, vyberte Yes.
   • Pro Chcete nasadit svou aplikaci?, vyberte No (před nasazením provedeme ještě několik změn).

2. Přejděte do adresáře nového projektu:

   cd my-workflow

   Jaké soubory C3 vytvořil?

   Ve složce projektu C3 vygeneruje následující:

   • wrangler.jsonc: Váš Konfigurační soubor Wrangler.
   • src/index.ts: Minimální Worker napsaný v TypeScriptu.
   • package.json: Minimální konfigurační soubor závislostí Node.
   • tsconfig.json: Konfigurace TypeScriptu.

1. Vytvořte nový soubor src/workflow.ts:

   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 rozšiřuje WorkflowEntrypoint a implementuje run metoda. Tento kód také předává náš Params jako parametr typu aby byly události, které spouštějí náš Workflow, typované.

   step objekt je jádrem API Workflows. Poskytuje metody pro definování trvalých kroků ve vašem Workflow:

   • step.do(name, callback) - Provede kód a trvale uloží výsledek. Pokud je Workflow přerušen nebo opakován, pokračuje od posledního úspěšného kroku místo toho, aby znovu prováděl již dokončenou práci. Callback vrací serializovatelná data, včetně ReadableStream<Uint8Array> pro velké binární výstupy v JavaScript Workflows.
   • step.sleep(name, duration) - Pozastaví Workflow na danou dobu (například "10 seconds", "1 hour").

   Pokud vracíte stream, vraťte nový, neuzamčený ReadableStream<Uint8Array>. Streamy BYOB ani čtečky BYOB nejsou podporovány.

   Můžete předat konfigurace opakování na step.do() pro přizpůsobení způsobu zpracování selhání. Více informací najdete v úplné step API pro požadavky na streamy, limity a další metody, jako je sleepUntil a waitForEvent.

   Při rozhodování, zda kód rozdělit do samostatných kroků, si položte otázku: „Chci, aby se celý tento kód spustil znovu, pokud selže jen jeho část?“ Samostatné kroky se hodí zejména pro operace jako volání externích API, dotazování databází nebo čtení souborů z úložiště. Pokud pozdější krok selže, může váš Workflow pokračovat od tohoto místa s již načtenými daty, čímž se vyhne zbytečným API voláním nebo databázovým dotazům.

   Další pokyny k definování logiky Workflow najdete v Pravidla pro Workflows.

1. Otevřete wrangler.jsonc, což je váš Konfigurační soubor Wrangler pro váš projekt Workers a váš Workflow a přidejte workflows konfigurace:

   {
   	"$schema": "node_modules/wrangler/config-schema.json",
   	"name": "my-workflow",
   	"main": "src/index.ts",
   	// Set this to today's date
   	"compatibility_date": "2026-08-28",
   	"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-08-28"
   
   [observability]
   enabled = true
   
   [[workflows]]
   name = "my-workflow"
   binding = "MY_WORKFLOW"
   class_name = "MyWorkflow"

   class_name musí odpovídat vaší exportované třídě a binding je název proměnné, kterou používáte pro přístup k Workflow ve svém kódu (například env.MY_WORKFLOW).

   Pokud chcete, aby se stejný Workflow spouštěl automaticky v pravidelném intervalu, přidejte schedules do definice Workflow:

   {
     "$schema": "node_modules/wrangler/config-schema.json",
     "name": "my-workflow",
     "main": "src/index.ts",
     // Set this to today's date
     "compatibility_date": "2026-08-28",
     "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-08-28"
   
   [[workflows]]
   name = "my-workflow"
   binding = "MY_WORKFLOW"
   class_name = "MyWorkflow"
   schedules = [ "0 * * * *" ]

   Každý odpovídající cron výraz automaticky vytvoří novou instanci Workflow, takže na nejvyšší úrovni nepotřebujete triggers.crons a samostatný scheduled handler pro opakované spouštění specifické pro Workflow.

   Naplánované instance obsahují odpovídající cron výraz a naplánovaný čas spuštění na event.schedule.

   Při konfiguraci plánů Workflow používejte nejnovější verzi Wrangleru. Pokud vaše místní schéma Wrangleru nerozpoznává schedules ještě nemáte, před nasazením aktualizujte Wrangler.

   Přistupovat můžete také k vazby (například KV, R2, nebo D1) přes this.env ve vašem Workflow. Další informace o bindings ve Workers najdete v Bindings (env).

2. Nyní vygenerujte typy pro své bindingy:

   npx wrangler types

   Tím se vytvoří worker-configuration.d.ts soubor pomocí Env typ, který obsahuje vaše MY_WORKFLOW binding.

1. Nahraďte src/index.ts s obslužná rutina fetch ke spouštění instancí Workflow a kontrole jejich stavu:

   src/index.ts

   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>;

1. Spusťte místní vývojový server:

   npx wrangler dev

2. Chcete-li spustit instanci Workflow, otevřete nové okno terminálu a spusťte:

   curl http://localhost:8787

   instanceId se vygeneruje automaticky:

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

3. Zkontrolujte stav pomocí vráceného instanceId:

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

   Workflow projde svými kroky. Po přibližně 20 sekundách (doba spánku) se dokončí.

1. Nasaďte svůj Workflow:

   npx wrangler deploy

   V produkci testujte pomocí stejných příkazů curl vůči nasazené URL. Můžete také aktivovat instanci workflow v produkci pomocí Workers, Wrangler nebo dashboardu Cloudflare.

   Po nasazení můžete instance Workflow zkontrolovat také pomocí CLI:

   npx wrangler workflows instances describe my-workflow latest

   Výstup instances describe zobrazuje:

   • Stav (success, failure, running) každého kroku
   • Stav, který krok vygeneruje. U streamovaného výstupu zobrazí CLI místo celého obsahu jen náhled nebo souhrn.
   • Jakýkoli sleep stavu, včetně informace o tom, kdy se Workflow probudí
   • Opakování přiřazená ke každému kroku
   • Chyby, včetně chybových zpráv výjimek