Workflows Lab

cd apps/experiments/workflows-lab
pnpm install
pnpm dev

The Workflows Lab shows how Vercel Workflows turn ordinary async functions into durable runs. It uses the open-source Workflow SDK (workflow package): 'use workflow' for the orchestrator, 'use step' for retried side effects, and sleep() for pauses that consume no compute. A Route Handler calls start() from workflow/api so the HTTP response can return while the run continues.

FeaturesCopy Anchor Link

• Real Workflow SDK wiring. next.config.mjs wraps the Next config with withWorkflow().
• Demo order workflow. processDemoOrder reserves inventory, charges payment, sleeps 2 seconds, then sends confirmation.
• Start API. POST /api/workflows/start queues a run and returns runId when the platform is available.
• Honest degradation. Without a linked Vercel project the route returns 503 with setup requirements - it does not fake a run id.
• Educational timeline. The UI also shows a client-side step timeline so you can learn the mental model offline.

API ReferenceCopy Anchor Link

POST /api/workflows/startCopy Anchor Link

Starts processDemoOrder with an order id.

curl -X POST http://localhost:3010/api/workflows/start \
  -H 'content-type: application/json' \
  -d '{"orderId":"order_demo"}'

Implementation DetailsCopy Anchor Link

The workflow lives in apps/experiments/workflows-lab/workflows/demo-order.ts:

export async function processDemoOrder(orderId: string) {
  'use workflow';
  await reserveInventory(orderId, steps);
  await chargePayment(orderId, steps);
  await sleep('2s');
  await sendConfirmation(orderId, steps);
  return { orderId, status: 'confirmed', steps };
}

Each helper is a 'use step' function. Steps get automatic retries for thrown errors; the workflow function coordinates them and may pause with sleep without holding a warm function.

withWorkflow from workflow/next generates the internal /.well-known/workflow/ routes the runtime needs.

Use CasesCopy Anchor Link

• Multi-step onboarding or order pipelines that must survive deploys
• Agent tool loops that pause for human approval or external webhooks
• Delayed follow-ups (hours/days) without cron polling every minute

LimitationsCopy Anchor Link

• Live runs need Vercel (or vercel dev with linked OIDC). Plain next dev without credentials returns 503.
• The on-page timeline is educational only - authoritative history is in Observability - Workflows / npx workflow web.
• Sleep in the demo is 2s so you can watch it finish; production sleeps can be much longer.

Use in your projectCopy Anchor Link

1. pnpm add workflow
2. Wrap next.config with withWorkflow()
3. Export a 'use workflow' function and call start(fn, [args]) from a Route Handler

DeploymentCopy Anchor Link

Deploy on Vercel

Deploy the standalone app, trigger /api/workflows/start, then open Observability - Workflows in the project dashboard.

Local DevelopmentCopy Anchor Link

cd apps/experiments/workflows-lab
pnpm install
vercel link && vercel env pull   # OIDC for live start()
pnpm dev

Open http://localhost:3010. Unit tests:

pnpm vitest run ../experiments/workflows-lab

ConfigurationCopy Anchor Link

Vercel / Next.js Features UsedCopy Anchor Link

• Vercel Workflows
• Workflow SDK ('use workflow', 'use step', sleep, start)
• Vercel Queues (underlying durable dispatch)
• Next.js Route Handlers

Next StepsCopy Anchor Link