workflow 5.0.0-beta.34 → 5.0.0-beta.36

package/docs/migration-guides/migrating-from-temporal.mdx

@@ -1,317 +0,0 @@
----
-title: Migrating from Temporal
-description: Move a Temporal TypeScript workflow to the Workflow SDK by replacing Activities, Workers, Signals, and Child Workflows with Workflows, Steps, Hooks, and start()/getRun().
-type: guide
-summary: Translate a Temporal app into the Workflow SDK with side-by-side code examples.
-prerequisites:
-  - /docs/getting-started/next
-  - /docs/foundations/workflows-and-steps
-related:
-  - /docs/foundations/starting-workflows
-  - /docs/foundations/errors-and-retries
-  - /docs/foundations/hooks
-  - /docs/foundations/streaming
-  - /docs/deploying/world/vercel-world
----
-
-<CopyPrompt
-  text="Refactor this Temporal TypeScript code to Workflow SDK. Run `npm i workflow`. Replace Temporal workflow functions with exported async functions containing `&quot;use workflow&quot;`. Replace Activities with helper functions containing `&quot;use step&quot;`. Replace timers with `sleep()` from `workflow`. Replace Signals with `defineHook()` plus `resumeHook()` from `workflow/api`, or `createWebhook()` when an HTTP callback URL is needed. Replace Child Workflows with `start(childWorkflow, args)` and coordinate completion with hooks or `getRun()`. Remove Temporal workers; instead expose API routes or server functions that call `start()` and `getRun()` from `workflow/api`. Preserve idempotency and retries with normal errors, `RetryableError`, and `FatalError`, then add a verification path for each migrated workflow."
-/>
-
-<Callout type="info">
-Install the Workflow SDK migration skill:
-
-```bash
-npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
-```
-</Callout>
-
-## Why migrate to the Workflow SDK
-
-- Streaming is built in. Durable progress writes go to named streams via `getWritable({ namespace })`, and clients read them directly. No separate WebSocket, SSE, or progress-polling layer to operate.
-- Infrastructure and orchestration live in a single deployment. There is no separate Worker fleet or Temporal Server to run. The runtime, step logic, and orchestration share the app's observability and log aggregation.
-- TypeScript-first developer experience. Workflows and steps live in the same file with plain `await` control flow, `try/catch`, and `Promise.all`.
-- Agent-first tooling. A first-class CLI (`npx workflow`), [`@workflow/ai` integration for durable AI agents](/docs/ai), and a bundled Claude skill for AI-assisted authoring.
-- Per-step retry controls. `RetryableError`, `FatalError`, and `maxRetries` live at the step boundary instead of an Activity-level retry policy configured elsewhere.
-
-## What changes when you leave Temporal
-
-Temporal requires operating a control plane (Temporal Server or Cloud), a Worker fleet, Activity modules wired through `proxyActivities`, and Task Queues. The workflow code is durable; the surrounding infrastructure is substantial.
-
-The Workflow SDK runs on managed infrastructure. Write `"use workflow"` functions that orchestrate `"use step"` functions in the same file, in plain TypeScript. There are no Workers, Task Queues, or separate Activity modules. Durable replay, automatic retries, and event history are handled by the runtime.
-
-Workflow functions must still be deterministic — no `Date.now()`, `Math.random()`, direct network I/O, or wall-clock branches inside `"use workflow"`. Move any such logic into a step, as you do today with Activities.
-
-Migration removes infrastructure and collapses indirection. Business logic stays as regular async TypeScript.
-
-## Concept mapping
-
-| Temporal | Workflow SDK | Migration note |
-| --- | --- | --- |
-| Workflow Definition / Workflow Execution | `"use workflow"` function / run started with `start()` | Keep orchestration code in the workflow function. |
-| Activity | `"use step"` function | Put side effects and Node.js access in steps. |
-| Worker + Task Queue | Managed execution | No worker fleet or polling loop to operate. |
-| Signal | `createHook()` or `createWebhook()` | Use hooks for typed resume signals; webhooks for HTTP callbacks. |
-| Query | `getWritable({ namespace: 'status' })` stream | Durably stream status updates from the workflow. Clients read from the stream instead of polling a database. |
-| Update | `createHook()` + `resumeHook()` (one-way) | Temporal Updates return a value to the caller; hooks do not. If the Update returns data, either write the result to a named stream via `getWritable()` and have the caller read from it, or keep an HTTP read route that fetches the workflow's current state. |
-| Child Workflow | `start()` plus a `"use step"` wrapper around `getRun()` | Spawn a child run and return the `Run` object so observability can deep-link into child runs. |
-| Activity retry policy | Step retries, `RetryableError`, `FatalError`, `maxRetries` | Retries live at the step boundary. |
-| Event History | Workflow event log / run timeline | Same durable replay; built-in observability UI replaces Temporal Web. Search attributes and visibility APIs have no direct equivalent — filter by run status and timestamps instead. |
-
-## Translate your first workflow
-
-### Minimal translation
-
-Start with the directive change. The Temporal definition proxies activities through a module; the Workflow SDK version puts the directive inline.
-
-{/* @skip-typecheck: Temporal SDK types not available */}
-```typescript title="workflows/order.ts (Temporal)"
-import * as wf from '@temporalio/workflow';
-import type * as activities from './activities';
-
-const { chargePayment } = wf.proxyActivities<typeof activities>({
-  startToCloseTimeout: '5 minutes',
-});
-
-export async function processOrder(orderId: string) {
-  await chargePayment(orderId);
-  return { orderId, status: 'completed' };
-}
-```
-
-```typescript title="workflows/order.ts (Workflow SDK)"
-export async function processOrder(orderId: string) {
-  'use workflow'; // [!code highlight]
-  await chargePayment(orderId);
-  return { orderId, status: 'completed' };
-}
-```
-
-**What changed:** `proxyActivities` and the activity module disappear. The orchestrator is plain async TypeScript marked with `"use workflow"`.
-
-### Adding a step
-
-Side effects move into a colocated `"use step"` function:
-
-```typescript title="workflow/workflows/order.ts"
-async function chargePayment(orderId: string) {
-  'use step'; // [!code highlight]
-  await fetch(`https://example.com/api/orders/${orderId}/charge`, {
-    method: 'POST',
-  });
-}
-```
-
-Additional steps (`loadOrder`, `reserveInventory`) follow the same shape and can be called from the workflow in sequence.
-
-### Starting the run
-
-Replace Worker + Task Queue wiring with a single `start()` call from an API route:
-
-```typescript title="app/api/orders/route.ts"
-import { start } from 'workflow/api';
-import { processOrder } from '@/workflows/order';
-
-export async function POST(request: Request) {
-  const { orderId } = (await request.json()) as { orderId: string };
-  const run = await start(processOrder, [orderId]); // [!code highlight]
-  return Response.json({ runId: run.runId });
-}
-```
-
-## Wait for an external signal
-
-### Minimal translation
-
-Temporal needs a signal definition, a handler, and a `condition()` guard. The Workflow SDK collapses all three into a single `createHook()` + `await`.
-
-{/* @skip-typecheck: Temporal SDK types not available */}
-```typescript title="temporal/workflows/refund.ts"
-export const approveRefund = wf.defineSignal<[boolean]>('approveRefund');
-
-export async function refundWorkflow(refundId: string) {
-  let approved: boolean | undefined;
-  wf.setHandler(approveRefund, (v) => { approved = v; });
-  await wf.condition(() => approved !== undefined);
-  return { refundId, approved };
-}
-```
-
-```typescript title="workflow/workflows/refund.ts"
-import { createHook } from 'workflow';
-
-export async function refundWorkflow(refundId: string) {
-  'use workflow';
-  using approval = createHook<{ approved: boolean }>({
-    token: `refund:${refundId}:approval`, // [!code highlight]
-  });
-  const { approved } = await approval; // [!code highlight]
-  return { refundId, approved };
-}
-```
-
-The workflow suspends durably at `await approval` until resumed. No polling, no handler registration.
-
-Requires TypeScript 5.2+ for the `using` keyword. On older TypeScript, assign the hook to a `const` and call `resumeHook()` from the consuming code path.
-
-### Resuming from an API route
-
-Any HTTP caller can resume by token:
-
-```typescript title="app/api/refunds/[refundId]/approve/route.ts"
-import { resumeHook } from 'workflow/api';
-
-export async function POST(request: Request, { params }: { params: Promise<{ refundId: string }> }) {
-  const { refundId } = await params;
-  const body = (await request.json()) as { approved: boolean };
-  await resumeHook(`refund:${refundId}:approval`, body); // [!code highlight]
-  return Response.json({ ok: true });
-}
-```
-
-<Callout type="info">
-Temporal Queries expose in-memory workflow state on demand. In the Workflow SDK, the equivalent is a durable stream: call `getWritable({ namespace: 'status' })` from inside the workflow to write status updates, and have clients read from the end of that stream to get the current state. Hooks are the write channel for resuming a paused workflow with new data.
-</Callout>
-
-## Spawn a child workflow
-
-### Minimal translation
-
-In v5, call `start()` directly from the workflow to spawn a child run. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to await the child result. Return the `Run` object (not a plain `runId` string) so workflow observability can deep-link into child runs.
-
-```typescript title="workflow/workflows/parent.ts"
-import { start } from 'workflow/api';
-
-export async function parentWorkflow(item: string) {
-  'use workflow';
-  const child = await start(childWorkflow, [item]); // [!code highlight]
-  return { childRunId: child.runId };
-}
-```
-
-### Awaiting the child's return value
-
-A second step fetches the run and awaits `returnValue`:
-
-```typescript title="workflow/workflows/parent.ts"
-import { getRun } from 'workflow/api';
-
-async function collectResult(runId: string) {
-  'use step';
-  const run = getRun(runId);
-  return (await run.returnValue) as { item: string; result: string }; // [!code highlight]
-}
-```
-
-Call `start()` and then `collectResult()` from the parent in sequence: `const result = await collectResult(child.runId)`. To fan out, call `start()` inside a loop, then `Promise.all` the `collectResult` calls.
-
-<Callout type="warn">
-Activity retry policy moves to the step boundary. Use `maxRetries`, `RetryableError`, and `FatalError` on each step instead of a single workflow-wide retry block.
-
-Temporal's per-activity timeouts (`startToCloseTimeout`, `scheduleToCloseTimeout`, `heartbeatTimeout`) have no direct Workflow SDK equivalent. Enforce per-step deadlines inside the step using `AbortSignal.timeout(ms)` (e.g. on `fetch`), or wrap the call from the workflow in `Promise.race(step(), sleep('5m'))` to bail out after a bounded duration.
-
-Temporal's retry policy knobs (`initialInterval`, `backoffCoefficient`, `maximumInterval`, `nonRetryableErrorTypes`) don't port 1:1 — only `maxRetries` is configurable at the step boundary. Classify retryability with `RetryableError` (retryable) and `FatalError` (terminal) instead of listing error types, and control the delay between attempts with `new RetryableError(msg, { retryAfter: '5s' })`.
-
-Set `maxRetries` as a property assignment on the step function:
-
-```typescript
-async function chargePayment(orderId: string) {
-  "use step";
-  // ...
-}
-chargePayment.maxRetries = 5;
-```
-
-See [/docs/foundations/errors-and-retries](/docs/foundations/errors-and-retries) for full retry docs.
-</Callout>
-
-## What you stop operating
-
-- **Temporal Server or Cloud.** Durable state lives in the managed event log.
-- **Worker fleet.** The runtime schedules execution; workflows run where the app runs.
-- **Task Queues.** No queue routing to configure or monitor.
-- **Activity modules and `proxyActivities`.** Steps live next to the workflow that calls them.
-- **Custom progress transport.** `getWritable()` streams updates from steps.
-
-Suspended workflows (on `sleep()` or a hook) consume no compute until resumed.
-
-## Step-by-step first migration
-
-Pick one Temporal workflow and migrate it end-to-end before touching the rest. The steps below describe the smallest viable path.
-
-### Step 1: Install the Workflow SDK
-
-Add the runtime. The Next.js integration ships as a subpath (`workflow/next`) of the same package.
-
-```bash
-pnpm add workflow
-```
-
-### Step 2: Collapse Activities into step functions
-
-Delete the `activities/` module and the `proxyActivities` call. Each former Activity becomes a plain async function with `"use step"` on the first line, living next to the orchestrator.
-
-```ts title="workflows/order.ts"
-async function loadOrder(id: string) {
-  "use step"; // [!code highlight]
-  return fetch(`/api/orders/${id}`).then((r) => r.json());
-}
-```
-
-### Step 3: Mark the orchestrator with `"use workflow"`
-
-Keep the existing control flow: `await`, `try/catch`, `Promise.all`. The directive turns the function into a durable replay target.
-
-```ts
-export async function processOrder(orderId: string) {
-  "use workflow"; // [!code highlight]
-  const order = await loadOrder(orderId);
-  // ...
-}
-```
-
-### Step 4: Replace Signals with hooks
-
-Swap `defineSignal` + `setHandler` for `createHook()`. Callers `resumeHook(token, payload)` instead of `handle.signal(signalDef, payload)` on a `WorkflowHandle` obtained from `client.workflow.getHandle(workflowId)`.
-
-### Step 5: Start runs from an API route or server action
-
-Delete the Worker bootstrap. Launch runs from an API route or server action with `start()`:
-
-```ts title="app/api/orders/route.ts"
-import { start } from "workflow/api";
-import { processOrder } from "@/workflows/order";
-
-export async function POST(req: Request) {
-  const { orderId } = await req.json();
-  const run = await start(processOrder, [orderId]);
-  return Response.json({ runId: run.runId });
-}
-```
-
-### Step 6: Retire the Temporal infrastructure
-
-Remove the Worker process, `@temporalio/*` dependencies, and the Temporal Server or Cloud connection. Verify the run in the built-in observability UI (`npx workflow web`) before shipping.
-
-## Features without a 1:1 equivalent
-
-- **Search attributes / visibility queries.** Temporal's search attribute system has no direct analog. Filter runs by status and timestamps via `getRun()` / observability UI.
-- **Event history archival.** Temporal archives histories to S3/GCS for long-term retention. Workflow SDK event logs are durable, but retention depends on the integration you are using. For example, see [Vercel Workflow Storage Retention](https://vercel.com/docs/workflows/pricing#storage-retention) for Vercel.
-- **Per-activity timeouts (`startToCloseTimeout`, `scheduleToCloseTimeout`, `heartbeatTimeout`).** Implement deadlines inside the step with `AbortSignal.timeout(ms)`, or wrap the call in `Promise.race(step(), sleep(...))` from the workflow.
-- **Rich retry policy (`initialInterval`, `backoffCoefficient`, `maximumInterval`, `nonRetryableErrorTypes`).** Only `maxRetries` is configurable. Classify retryability with `RetryableError`/`FatalError`; control delay between attempts via `new RetryableError(msg, { retryAfter: '5s' })`.
-- **Workers + task queues.** Managed deployments replace workers; self-hosted deployments still need a `World` implementation (see [/docs/deploying/building-a-world](/docs/deploying/building-a-world)).
-
-## Quick-start checklist
-
-- Move orchestration into a `"use workflow"` function.
-- Convert each Activity into a `"use step"` function.
-- Remove Worker and Task Queue code. Start workflows from the app with `start()`.
-- Replace Signals with `createHook()` or `createWebhook()` for HTTP callers.
-- Use `start()` directly for child workflows, and wrap `getRun()` in a `"use step"` function when collecting results. Return the `Run` object from `start()` so observability can deep-link into child runs.
-- Set retry policy per step with `maxRetries`, `RetryableError`, and `FatalError`.
-- Use `getStepMetadata().stepId` as the idempotency key for external side effects.
-- Stream status and progress from steps with `getWritable({ namespace: 'status' })`, and have clients read from the stream instead of polling.
-- Deploy the app and verify runs end-to-end in the built-in observability UI.
-
----
-*Verified against `workflow@5.0.0-beta.1` and `@temporalio/workflow@1.16` on 2026-04-16.*

package/docs/migration-guides/migrating-from-trigger-dev.mdx

@@ -1,332 +0,0 @@
----
-title: Migrating from trigger.dev
-description: Move a trigger.dev v3 TypeScript app to the Workflow SDK by replacing task(), schemaTask(), wait.for / wait.forToken, triggerAndWait, and metadata streams with Workflows, Steps, Hooks, and start() / getRun().
-type: guide
-summary: Translate a trigger.dev v3 app into the Workflow SDK with side-by-side code examples.
-prerequisites:
-  - /docs/getting-started/next
-  - /docs/foundations/workflows-and-steps
-related:
-  - /docs/foundations/starting-workflows
-  - /docs/foundations/errors-and-retries
-  - /docs/foundations/hooks
-  - /docs/foundations/streaming
-  - /docs/deploying/world/vercel-world
----
-
-<CopyPrompt
-  text="Convert this trigger.dev setup to Workflow SDK. Run `npm i workflow`. Replace each `task()` or job entrypoint with an exported async workflow function containing `&quot;use workflow&quot;`. Replace trigger.dev task bodies that do side effects with `&quot;use step&quot;` helper functions. Replace waits/delays with `sleep()` from `workflow`. Replace external triggers or resume points with `defineHook()`/`resumeHook()` or `createWebhook()`. Replace run creation/status calls with `start()` and `getRun()` from `workflow/api`. Replace metadata/progress streaming with `getWritable()` from `workflow` when the UI needs live updates. Preserve retry semantics with normal errors, `RetryableError`, and `FatalError`, then add a local verification that starts the migrated workflow and checks the expected result or stream."
-/>
-
-<Callout type="info">
-Install the Workflow SDK migration skill:
-
-```bash
-npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
-```
-</Callout>
-
-## Why migrate to the Workflow SDK?
-
-- Streaming is built in via named streams (`getWritable()` and `getWritable({ namespace })`). Durable status writes replace `metadata.stream()` and `metadata.set()`, and clients read from the end of the stream for current status.
-- Orchestration and infrastructure live in a single deployment. There is no separate trigger.dev cloud or self-hosted worker fleet to operate.
-- TypeScript-first DX: plain async/await control flow, no `task()` factory, no `schemaTask()` wrapper for payloads you already type with TypeScript.
-- Agent-first tooling: the `npx workflow` CLI, `@workflow/ai` for durable AI agents, and a Claude skill for generating workflows.
-- Retry policy is per step. Throw `RetryableError` to retry with a delay, or `FatalError` to stop. There is no central task-level retry config.
-
-## What changes when you leave trigger.dev?
-
-trigger.dev v3 defines durable work with `task()` or `schemaTask()` from `@trigger.dev/sdk` (trigger.dev v3), deploys tasks to the trigger.dev cloud or a self-hosted instance, and triggers runs via `tasks.trigger()`. A separate worker fleet picks up runs, applies retry policies, and routes `wait.for`, `wait.forToken`, and `metadata.stream` calls through the platform.
-
-The Workflow SDK replaces that with `"use workflow"` functions that orchestrate `"use step"` functions in plain TypeScript. There is no task registry, separate deploy target, or SDK client. Durable replay, retries, and event history ship with the runtime.
-
-Migration collapses the task abstraction into plain async functions. Business logic stays the same.
-
-## Concept mapping
-
-| trigger.dev | Workflow SDK | Migration note |
-| --- | --- | --- |
-| `task({ id, run })` | `"use workflow"` function started with `start()` | No factory or id registry. |
-| `schemaTask({ schema, run })` | Typed function + `"use workflow"` | Validate inputs at the call site. |
-| Inline `run` body | `"use step"` function | Side effects move into named steps. |
-| `logger` / `metadata.set` | `console` + `getWritable({ namespace: 'status' })` | Logs flow through the run timeline. Status writes go on a named stream. |
-| `wait.for({ seconds \| minutes \| hours \| days })` / `wait.until({ date })` | `sleep()` | Import from `workflow`. |
-| `wait.forToken({ timeout })` | `createHook()` + `Promise.race` with `sleep()` | Hooks carry a typed token. |
-| `tasks.trigger()` / `triggerAndWait()` | `start()` and `getRun(runId).returnValue` | Call `start()` directly; wrap `getRun()` collection in a `"use step"` function. |
-| `batch.triggerAndWait()` | `Promise.all(runIds.map(collectResult))` | Fan out via standard concurrency. |
-| `AbortTaskRunError` | `FatalError` | Stops retries immediately. |
-| `retry.onThrow` / `retry.fetch` | `RetryableError`, `FatalError`, `maxRetries` | Retry count lives on the step via `myStep.maxRetries = N` (default 3). Control delay between attempts by throwing `new RetryableError(msg, { retryAfter: '5s' })` — there is no built-in exponential helper; compute the delay yourself based on `getStepMetadata().attempt` if you need one. |
-| `metadata.stream()` / Realtime | `getWritable()` / `getWritable({ namespace })` | For granular business status (progress updates, current-stage messages), prefer writing to `getWritable({ namespace: 'status' })` from a step and reading from the end of the named stream on the client. Use `getRun(runId).status` for terminal/lifecycle state only. |
-| Self-hosted worker + dashboard | Managed execution + built-in UI | No worker fleet to operate. |
-
-## Translate your first workflow
-
-<Callout type="warn">
-trigger.dev's `task.run` body has full Node.js access. The SDK's `'use workflow'` body runs in a sandboxed VM — side effects (I/O, `Date.now()`, `Math.random()`, DB, fetch) must live inside `'use step'` functions. Orchestration stays in the workflow body.
-</Callout>
-
-Start with the shell. trigger.dev wraps the handler in `task()`; the Workflow SDK marks the function with a directive.
-
-```typescript title="trigger/order.ts (trigger.dev)"
-import { task } from '@trigger.dev/sdk';
-
-export const processOrder = task({
-  id: 'process-order',
-  run: async (payload: { orderId: string }) => {
-    return { orderId: payload.orderId, status: 'completed' };
-  },
-});
-```
-
-```typescript title="trigger/order.ts (Workflow SDK)"
-export async function processOrder(orderId: string) {
-  'use workflow'; // [!code highlight]
-  return { orderId, status: 'completed' };
-}
-```
-
-**What changed:** the `task()` factory and its `id` field disappear. The function is a plain export tagged with `"use workflow"`.
-
-### Add a step
-
-The body of `run` becomes one or more `"use step"` functions.
-
-```typescript title="workflow/workflows/order.ts"
-async function loadOrder(orderId: string) {
-  'use step'; // [!code highlight]
-  const res = await fetch(`https://example.com/api/orders/${orderId}`);
-  return res.json() as Promise<{ id: string }>;
-}
-```
-
-Call it from the workflow with a plain `await`. Each additional side effect (`reserveInventory`, `chargePayment`) follows the same shape.
-
-### Start the run
-
-trigger.dev dispatches with `tasks.trigger<typeof processOrder>('process-order', { orderId })`. The Workflow SDK calls `start()` directly:
-
-```typescript title="app/api/orders/route.ts"
-import { start } from 'workflow/api';
-import { processOrder } from '@/workflows/order';
-
-export async function POST(request: Request) {
-  const { orderId } = (await request.json()) as { orderId: string };
-  const run = await start(processOrder, [orderId]); // [!code highlight]
-  return Response.json({ runId: run.runId });
-}
-```
-
-No id lookup, no API key, no separate worker. `start()` returns a handle immediately.
-
-## Wait for an external signal
-
-`wait.forToken()` becomes `createHook()` plus `await`.
-
-{/* @skip-typecheck: trigger.dev SDK types not available */}
-```typescript title="workflow/workflows/refund.ts (trigger.dev, abbreviated)"
-// import { wait } from '@trigger.dev/sdk';
-const token = await wait.createToken({ timeout: '7d' });
-const approval = await wait.forToken<{ approved: boolean }>(token.id).unwrap();
-// External system resumes with: await wait.completeToken(token.id, { approved: true });
-```
-
-{/* @skip-typecheck: snippet without imports */}
-```typescript title="workflow/workflows/refund.ts (Workflow SDK)"
-using approval = createHook<{ approved: boolean }>({ // [!code highlight]
-  token: `refund:${refundId}:approval`,
-});
-const payload = await approval;
-```
-
-**What changed:** the platform-issued opaque token becomes an app-owned string. The caller that resumes the run supplies that same string, so there is no token lookup. (trigger.dev also exposes `token.url` for external callers; the SDK analog is `createWebhook().url`).
-
-### Resume from an API route
-
-There are two shapes of resume, and `wait.forToken` can map to either:
-
-- **Server-side resume (known token):** `createHook<T>({ token: 'business-token' })` + `resumeHook(token, payload)` from an API route. Use this when your app knows the token shape and controls the resume call.
-- **Third-party callback URL (generated token):** `createWebhook({ respondWith: 'default' })` + pass `webhook.url` to the external system. The external system hits the URL to resume.
-
-See [`/docs/foundations/hooks`](/docs/foundations/hooks) for both surfaces.
-
-trigger.dev completes a token with `wait.completeToken(tokenId, { approved })`. The SDK equivalent is `resumeHook`:
-
-```typescript title="app/api/refunds/[refundId]/approve/route.ts"
-import { resumeHook } from 'workflow/api';
-
-export async function POST(request: Request, { params }: { params: Promise<{ refundId: string }> }) {
-  const { refundId } = await params;
-  const { approved } = (await request.json()) as { approved: boolean };
-  await resumeHook(`refund:${refundId}:approval`, { approved }); // [!code highlight]
-  return Response.json({ ok: true });
-}
-```
-
-### Add a timeout and branch on the payload
-
-trigger.dev's `timeout: '7d'` option maps to a `Promise.race()` with `sleep()`:
-
-{/* @skip-typecheck: continuation snippet */}
-```typescript title="workflow/workflows/refund.ts"
-const result = await Promise.race([
-  approval.then((p) => ({ type: 'decision' as const, approved: p.approved })),
-  sleep('7d').then(() => ({ type: 'timeout' as const })), // [!code highlight]
-]);
-
-if (result.type === 'timeout') return { refundId, status: 'timed-out' };
-if (!result.approved) return { refundId, status: 'rejected' };
-return { refundId, status: 'approved' };
-```
-
-<Callout type="info">
-A hook is an inbound write channel. The caller that knows the token resumes the run with a typed payload. For granular business status (progress updates, current-stage messages), prefer writing to `getWritable({ namespace: 'status' })` from a step and reading from the end of the named stream on the client. Use `getRun(runId).status` for terminal/lifecycle state only.
-</Callout>
-
-## Spawn a child workflow
-
-`triggerAndWait()` splits into spawn and collect. In v5, call `start()` directly from the workflow to spawn the child. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to collect the result.
-
-You can return either the full `Run` object (enables deep-linking) or just `run.runId` (simpler). The runtime serializes `Run` to its `runId` in the event log either way.
-
-Await the result in a step, then orchestrate both from the parent:
-
-```typescript title="workflow/workflows/parent.ts"
-import { getRun, start } from 'workflow/api';
-
-async function collectResult(runId: string) {
-  'use step';
-  const run = getRun(runId);
-  return (await run.returnValue) as { item: string; result: string }; // [!code highlight]
-}
-
-export async function parentWorkflow(item: string) {
-  'use workflow';
-  const child = await start(childWorkflow, [item]); // [!code highlight]
-  return await collectResult(child.runId);
-}
-```
-
-To fan out, call `start()` inside a loop, then `Promise.all` the `collectResult` calls. That replaces `batch.triggerAndWait()`.
-
-`Promise.all` rejects on first failure; use `Promise.allSettled` if you need batch-mode error tolerance similar to trigger.dev's `{ ok, output, error }` per-run result.
-
-## What you stop operating
-
-Dropping the trigger.dev SDK removes several moving parts:
-
-- **No task registry or `id` strings.** Workflow files carry directive annotations and export plain functions.
-- **No `@trigger.dev/sdk` client or API key.** `start()` launches runs directly from API routes or server actions.
-- **No worker fleet or self-hosted instance.** The runtime schedules execution inside the app's deploy target.
-- **No separate Realtime channel.** `getWritable()` streams updates from steps over the run's durable stream.
-- **No dashboard account.** The built-in observability UI (`npx workflow web`) reads the same event log the runtime writes.
-
-Workflows suspended on `sleep()` or a hook consume no compute until resumed.
-
-## Step-by-step first migration
-
-Pick one trigger.dev task and migrate it end-to-end before touching the rest. The steps below describe the smallest viable path.
-
-### Step 1: Install the Workflow SDK
-
-Add the runtime. Framework integrations (Next.js, Nitro, Nuxt, SvelteKit, Astro, Nest) are subpath exports of the same `workflow` package, e.g. `workflow/next` — no additional install needed.
-
-```bash
-pnpm add workflow
-```
-
-### Step 2: Convert `task()` to a `"use workflow"` export
-
-Drop the factory call and the `id`. Move the handler body up and replace the payload object with typed function arguments.
-
-```ts title="workflows/order.ts"
-// Before (trigger.dev)
-// export const processOrder = task({
-//   id: "process-order",
-//   run: async ({ orderId }: { orderId: string }) => { ... },
-// });
-
-// After (Workflow SDK)
-export async function processOrder(orderId: string) {
-  "use workflow"; // [!code highlight]
-  // ...
-}
-```
-
-### Step 3: Convert the task body into `"use step"` named functions
-
-Each side effect becomes a named function with `"use step"` on the first line. The workflow calls them with a plain `await`. `schemaTask()` validation moves to the call site: validate with zod before calling `start()`.
-
-```ts
-async function loadOrder(id: string) {
-  "use step"; // [!code highlight]
-  return fetch(`/api/orders/${id}`).then((r) => r.json());
-}
-```
-
-### Step 4: Replace `wait.*` with hooks and `sleep`
-
-- `wait.for({ seconds | minutes | hours | days })` / `wait.until({ date })` → `sleep('5m')` or `sleep(date)` from `workflow`.
-- `wait.forToken(token)` → `createHook({ token })` + `await`. Complete it with `resumeHook(token, payload)` from an API route.
-- `wait.forToken({ timeout })` → `Promise.race([hook, sleep(timeout)])`.
-- `triggerAndWait(payload)` → call `start(child, [payload])` from the workflow and return the `Run` object, then read the result with a step that calls `getRun(runId).returnValue`.
-
-### Step 5: Start runs from the app
-
-Delete the trigger.dev client setup. Launch runs directly from an API route or server action:
-
-```ts title="app/api/orders/route.ts"
-import { start } from "workflow/api";
-import { processOrder } from "@/workflows/order";
-
-export async function POST(req: Request) {
-  const { orderId } = await req.json();
-  const run = await start(processOrder, [orderId]);
-  return Response.json({ runId: run.runId });
-}
-```
-
-### Step 6: Retire trigger.dev infrastructure
-
-Remove the `@trigger.dev/sdk` dependency, the `trigger.config.ts` file, the `trigger/` directory, and any self-hosted worker deployment. Delete dashboard API keys from the environment. Verify the run in `npx workflow web` before shipping.
-
-## Retries on steps
-
-Retry count lives on the step function itself. Set it as a property on the step:
-
-```typescript
-async function chargePayment(orderId: string) {
-  "use step";
-  // ...
-}
-chargePayment.maxRetries = 5;
-```
-
-Throw `new RetryableError(msg, { retryAfter: '5s' })` to control delay between attempts, or `FatalError` to stop retries immediately. See [`/docs/foundations/errors-and-retries`](/docs/foundations/errors-and-retries).
-
-## Features without a 1:1 equivalent
-
-- **`schedules.task()` / cron triggers.** The SDK has no built-in scheduler. Trigger runs from Vercel Cron or a system cron calling `start()`.
-- **Concurrency keys / queue concurrency limits.** No direct analog. Enforce limits inside steps (semaphores, external coordinator) or debounce at the publisher.
-- **`machine` presets / custom images.** Machine specs are per-task in trigger.dev; in the SDK, function resources are per-deployment (configure via your hosting platform).
-- **Realtime / `subscribeToRun`.** Use `getRun(runId).getReadable()` plus named `getWritable()` streams for live progress.
-- **`onFailure` lifecycle hook.** No equivalent. Handle cleanup in the workflow body with a try/catch + compensation-stack pattern.
-- **Trigger.dev dashboard.** Workflow SDK ships `npx workflow web` for local inspection and the Vercel Observability tab for deployed runs.
-
-## Quick-start checklist
-
-- Replace `task({ id, run })` with a `"use workflow"` function; launch it with `start()`.
-- Convert each task body into named `"use step"` functions.
-- Swap `wait.for` / `wait.until` for `sleep()` from `workflow`.
-- Swap `wait.forToken` for `createHook()` (internal) or `createWebhook()` (HTTP).
-- Model `wait.forToken` timeouts as `Promise.race()` between the hook and `sleep()`.
-- Replace `triggerAndWait()` with direct `start()` calls and a `"use step"` wrapper around `getRun()` when collecting results.
-- Replace `batch.triggerAndWait()` with `Promise.all` over the collected child `Run` handles.
-- Move `schemaTask` validation to the call site; pass typed arguments into the workflow.
-- Replace `AbortTaskRunError` with `FatalError`; model retries per step with `RetryableError` and `maxRetries`.
-- Use `getStepMetadata().stepId` as the idempotency key for external side effects.
-- Replace `metadata.stream()` and Realtime with `getWritable()`.
-- Remove the `@trigger.dev/sdk` dependency, `trigger.config.ts`, and any self-hosted worker.
-- Deploy and verify runs end-to-end with the built-in observability UI.
-
----
-*Verified against `workflow@5.0.0-beta.1` and `@trigger.dev/sdk` v3 on 2026-04-16.*