Skip to content

Commit 3d44478

Browse files
committed
In PR #1584 (migration-guides branch), make two changes to the migration guides:
1. Move migration guides to a top-level "Migration Guides" nav section: - Create docs/content/docs/migration-guides/ directory - Move the 3 migrating-from-*.mdx files from getting-started/ into migration-guides/ - Create migration-guides/meta.json with title "Migration Guides" listing temporal, inngest, aws-step-functions - Add "migration-guides" between "errors" and "api-reference" in docs/content/docs/meta.json - Remove the 3 migration entries from getting-started/meta.json 2. Replace all "Vercel Workflow" language with "Workflow SDK" across docs and skills: - In all 3 MDX migration guides: replace "Vercel Workflow" with "the Workflow SDK" or "Workflow SDK" in frontmatter, headings, table headers, and body text - Replace "shipping on Vercel" with neutral phrasing, "Vercel-managed execution" with "managed execution", "Vercel's infrastructure" with neutral phrasing - Replace Vercel-specific pricing paragraphs with generic "Efficient resource usage" bullet - Replace "Deploy to Vercel first..." checklist items with neutral deployment guidance - Keep vercel-world prerequisite links (real package name) - Rename skills/migrating-to-vercel-workflow/ to skills/migrating-to-workflow-sdk/ - Update all skill SKILL.md, evals/, and references/ files to replace "Vercel Workflow" with "Workflow SDK" - Update runtime-targets.md section headers from "Non-Vercel" to "Self-hosted"
1 parent 0040be7 commit 3d44478

19 files changed

+83
-77
lines changed

docs/content/docs/getting-started/meta.json

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,7 @@
99
"nitro",
1010
"nuxt",
1111
"sveltekit",
12-
"vite",
13-
"migrating-from-temporal",
14-
"migrating-from-inngest",
15-
"migrating-from-aws-step-functions"
12+
"vite"
1613
],
1714
"defaultOpen": true
1815
}

docs/content/docs/meta.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
"testing",
1111
"deploying",
1212
"errors",
13+
"migration-guides",
1314
"api-reference"
1415
]
1516
}
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"title": "Migration Guides",
3+
"pages": [
4+
"migrating-from-temporal",
5+
"migrating-from-inngest",
6+
"migrating-from-aws-step-functions"
7+
]
8+
}

docs/content/docs/getting-started/migrating-from-aws-step-functions.mdx renamed to docs/content/docs/migration-guides/migrating-from-aws-step-functions.mdx

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
title: Migrating from AWS Step Functions
3-
description: Move an AWS Step Functions state machine to Vercel Workflow by replacing JSON state definitions, Task states, Choice/Wait/Parallel states, Retry/Catch blocks, and .waitForTaskToken callbacks with Workflows, Steps, Hooks, and idiomatic TypeScript control flow.
3+
description: Move an AWS Step Functions state machine to the Workflow SDK by replacing JSON state definitions, Task states, Choice/Wait/Parallel states, Retry/Catch blocks, and .waitForTaskToken callbacks with Workflows, Steps, Hooks, and idiomatic TypeScript control flow.
44
type: guide
5-
summary: Translate an AWS Step Functions state machine into Vercel Workflow with side-by-side code and a realistic order-processing saga.
5+
summary: Translate an AWS Step Functions state machine into the Workflow SDK with side-by-side code and a realistic order-processing saga.
66
prerequisites:
77
- /docs/getting-started/next
88
- /docs/foundations/workflows-and-steps
@@ -18,13 +18,13 @@ related:
1818

1919
With AWS Step Functions, you define workflows as JSON state machines using Amazon States Language (ASL). Each state — Task, Choice, Wait, Parallel, Map — is a node in a declarative graph. You wire Lambda functions as task handlers, configure Retry/Catch blocks per state, and manage callback patterns through `.waitForTaskToken`. The execution engine is powerful, but the authoring experience is configuration-heavy and detached from your application code.
2020

21-
With Vercel Workflow, you write `"use workflow"` functions that orchestrate `"use step"` functions — all in the same file, all plain TypeScript. Branching is `if`/`else`, waiting is `sleep()`, parallelism is `Promise.all()`, and retries are step-level configuration. There is no state-machine JSON to maintain, no Lambda function wiring, and no IAM roles to configure between orchestrator and compute.
21+
With the Workflow SDK, you write `"use workflow"` functions that orchestrate `"use step"` functions — all in the same file, all plain TypeScript. Branching is `if`/`else`, waiting is `sleep()`, parallelism is `Promise.all()`, and retries are step-level configuration. There is no state-machine JSON to maintain, no Lambda function wiring, and no IAM roles to configure between orchestrator and compute.
2222

2323
The migration path is mostly about **replacing declarative configuration with idiomatic TypeScript** and **collapsing the orchestrator/compute split**, not rewriting business logic.
2424

2525
## Concept mapping
2626

27-
| AWS Step Functions | Vercel Workflow | Migration note |
27+
| AWS Step Functions | Workflow SDK | Migration note |
2828
| --- | --- | --- |
2929
| State machine (ASL JSON) | `"use workflow"` function | The workflow function _is_ the state machine — expressed as async TypeScript. |
3030
| Task state / Lambda | `"use step"` function | Put side effects and Node.js access in steps. No separate Lambda deployment. |
@@ -94,7 +94,7 @@ export const handler = async (event: { id: string }) => {
9494
};
9595
```
9696

97-
### Vercel Workflow
97+
### Workflow SDK
9898

9999
```typescript
100100
// workflow/workflows/order.ts
@@ -196,7 +196,7 @@ export const handler = async (event: {
196196
};
197197
```
198198

199-
### Vercel Workflow
199+
### Workflow SDK
200200

201201
```typescript
202202
// workflow/workflows/refund.ts
@@ -348,7 +348,7 @@ A Step Functions saga requires explicit Catch blocks on each state to trigger co
348348

349349
Each Task state maps to a separate Lambda function, and the compensation chain (CancelShipment → RefundPayment → ReleaseInventory → Fail) must be wired explicitly in the state machine.
350350

351-
### Vercel Workflow version
351+
### Workflow SDK version
352352

353353
```typescript
354354
import { FatalError, getStepMetadata, getWritable } from 'workflow';
@@ -486,16 +486,16 @@ async function emitProgress(update: { stage: string; orderId: string }) {
486486

487487
## Why teams usually simplify infrastructure in this move
488488

489-
Step Functions requires you to define state machines in JSON (Amazon States Language), deploy each task as a separate Lambda function, manage IAM roles between the orchestrator and every Lambda, and configure CloudWatch, X-Ray, or third-party tooling for observability. These are powerful primitives when you need visual workflow editing or cross-service AWS orchestration — but for TypeScript-first teams shipping on Vercel, they are overhead without a corresponding benefit.
489+
Step Functions requires you to define state machines in JSON (Amazon States Language), deploy each task as a separate Lambda function, manage IAM roles between the orchestrator and every Lambda, and configure CloudWatch, X-Ray, or third-party tooling for observability. These are powerful primitives when you need visual workflow editing or cross-service AWS orchestration — but for TypeScript-first teams, they are overhead without a corresponding benefit.
490490

491-
With Vercel Workflow:
491+
With the Workflow SDK:
492492

493493
- **No state machine JSON.** The workflow function _is_ the state machine. Branching, looping, and error handling are TypeScript — not a JSON DSL with its own type system and reference syntax.
494494
- **No Lambda function wiring.** Steps run in the same deployment as your app. There are no separate functions to deploy, version, or connect with IAM policies.
495-
- **No infrastructure to provision.** There is no CloudFormation/CDK stack for the orchestrator, no Lambda concurrency limits to tune, and no Step Functions pricing tiers to navigate.
495+
- **No infrastructure to provision.** There is no CloudFormation/CDK stack for the orchestrator, no Lambda concurrency limits to tune, and no pricing tiers to navigate.
496496
- **TypeScript all the way down.** Workflow and step functions are regular TypeScript with directive annotations. State transitions are `await` calls, not `"Next"` pointers.
497497
- **Durable streaming built in.** `getWritable()` lets you push progress updates from steps without adding DynamoDB, SNS, or a WebSocket API Gateway.
498-
- **Usage-based pricing with active-CPU compute.** Workflow bills for Workflow Steps and Workflow Storage, and the functions that execute those steps continue to use standard Vercel compute pricing. If you use Fluid Compute, CPU billing pauses while code waits on I/O. When a workflow is suspended on `sleep()` or a hook, it pauses cleanly instead of keeping a worker process alive.
498+
- **Efficient resource usage.** When a workflow is suspended on `sleep()` or a hook, it pauses cleanly instead of keeping a worker process alive.
499499

500500
This is not about replacing every Step Functions feature. It is about recognizing that most TypeScript teams use a fraction of Step Functions' state-language surface and pay for the rest in configuration complexity and AWS service sprawl.
501501

@@ -512,4 +512,4 @@ This is not about replacing every Step Functions feature. It is about recognizin
512512
- Move Retry/Catch configuration down to step boundaries using default retries, `maxRetries`, `RetryableError`, and `FatalError`, with standard `try`/`catch` for error handling.
513513
- Add idempotency keys to external side effects using `getStepMetadata().stepId`.
514514
- Stream user-visible progress from steps with `getWritable()` when you previously polled DynamoDB or used SNS notifications.
515-
- Deploy to Vercel first so the guide can truthfully lean on zero-config infrastructure and built-in observability.
515+
- Deploy your app and verify workflows run end-to-end with built-in observability.

docs/content/docs/getting-started/migrating-from-inngest.mdx renamed to docs/content/docs/migration-guides/migrating-from-inngest.mdx

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
title: Migrating from Inngest
3-
description: Move an Inngest TypeScript app to Vercel Workflow by replacing createFunction, step.run(), step.sleep(), step.waitForEvent(), and step.invoke() with Workflows, Steps, Hooks, and start()/getRun().
3+
description: Move an Inngest TypeScript app to the Workflow SDK by replacing createFunction, step.run(), step.sleep(), step.waitForEvent(), and step.invoke() with Workflows, Steps, Hooks, and start()/getRun().
44
type: guide
5-
summary: Translate an Inngest app into Vercel Workflow with side-by-side code and a realistic order-processing saga.
5+
summary: Translate an Inngest app into the Workflow SDK with side-by-side code and a realistic order-processing saga.
66
prerequisites:
77
- /docs/getting-started/next
88
- /docs/foundations/workflows-and-steps
@@ -18,13 +18,13 @@ related:
1818

1919
With Inngest, you define functions using `inngest.createFunction()`, register them through a `serve()` handler, and break work into steps with `step.run()`, `step.sleep()`, and `step.waitForEvent()`. The Inngest platform manages event routing, step execution, and retries on its infrastructure.
2020

21-
With Vercel Workflow, you write `"use workflow"` functions that orchestrate `"use step"` functions — all in the same file, all plain TypeScript. There is no separate function registry, no event-driven dispatch layer, and no SDK client to configure. Durable replay, automatic retries, and step-level persistence still exist — they are built into the Vercel runtime.
21+
With the Workflow SDK, you write `"use workflow"` functions that orchestrate `"use step"` functions — all in the same file, all plain TypeScript. There is no separate function registry, no event-driven dispatch layer, and no SDK client to configure. Durable replay, automatic retries, and step-level persistence still exist — they are built into the runtime.
2222

2323
The migration path is mostly about **collapsing the SDK abstraction** and **writing plain async functions**, not rewriting business logic.
2424

2525
## Concept mapping
2626

27-
| Inngest | Vercel Workflow | Migration note |
27+
| Inngest | Workflow SDK | Migration note |
2828
| --- | --- | --- |
2929
| `inngest.createFunction()` | `"use workflow"` function started with `start()` | The workflow function itself is the entry point — no wrapper needed. |
3030
| `step.run()` | `"use step"` function | Each step is a standalone async function with full Node.js access. |
@@ -72,7 +72,7 @@ export const processOrder = inngest.createFunction(
7272
);
7373
```
7474

75-
### Vercel Workflow
75+
### Workflow SDK
7676

7777
```typescript
7878
// workflow/workflows/order.ts
@@ -141,7 +141,7 @@ export const refundWorkflow = inngest.createFunction(
141141
);
142142
```
143143

144-
### Vercel Workflow
144+
### Workflow SDK
145145

146146
```typescript
147147
// workflow/workflows/refund.ts
@@ -377,7 +377,7 @@ export const processOrderSaga = inngest.createFunction(
377377
}
378378
```
379379

380-
### Vercel Workflow version
380+
### Workflow SDK version
381381

382382
```typescript
383383
import { FatalError, getStepMetadata, getWritable } from 'workflow';
@@ -515,15 +515,15 @@ async function emitProgress(update: { stage: string; orderId: string }) {
515515

516516
## Why teams usually simplify infrastructure in this move
517517

518-
Inngest adds an event-driven orchestration layer between your app and your durable logic. You configure an Inngest client, register functions through a `serve()` handler, route work through events, and manage step execution through the Inngest platform. This is a clean model when you want event-driven fan-out across many loosely coupled functions — but for TypeScript teams shipping on Vercel, the indirection often outweighs the benefit.
518+
Inngest adds an event-driven orchestration layer between your app and your durable logic. You configure an Inngest client, register functions through a `serve()` handler, route work through events, and manage step execution through the Inngest platform. This is a clean model when you want event-driven fan-out across many loosely coupled functions — but for TypeScript teams, the indirection often outweighs the benefit.
519519

520-
With Vercel Workflow:
520+
With the Workflow SDK:
521521

522522
- **No SDK client or serve handler.** Workflow functions are regular TypeScript files with directive annotations. There is no client to configure, no function registry to maintain, and no serve endpoint to wire up.
523523
- **No event bus.** Start workflows directly with `start()` from your API routes, server actions, or app boundary. You do not need to define event schemas or route through a dispatch layer.
524524
- **TypeScript all the way down.** Steps are named async functions, not inline closures passed to `step.run()`. They are easier to test, type, and reuse.
525525
- **Durable streaming built in.** `getWritable()` lets you push progress updates from steps without adding Inngest Realtime or a separate WebSocket/SSE transport.
526-
- **Usage-based pricing with active-CPU compute.** Workflow bills for Workflow Steps and Workflow Storage, and the functions that execute those steps continue to use standard Vercel compute pricing. If you use Fluid Compute, CPU billing pauses while code waits on I/O. When a workflow is suspended on `sleep()` or a hook, it pauses cleanly instead of keeping a worker process alive.
526+
- **Efficient resource usage.** When a workflow is suspended on `sleep()` or a hook, it pauses cleanly instead of keeping a worker process alive.
527527

528528
This is not about replacing every Inngest feature. It is about recognizing that most TypeScript teams use a fraction of Inngest's event-routing surface and pay for the rest in SDK complexity and platform coupling.
529529

@@ -540,4 +540,4 @@ This is not about replacing every Inngest feature. It is about recognizing that
540540
- Move retry configuration down to step boundaries using default retries, `maxRetries`, `RetryableError`, and `FatalError`.
541541
- Add idempotency keys to external side effects using `getStepMetadata().stepId`.
542542
- Replace `step.realtime.publish()` with `getWritable()` for streaming progress to clients.
543-
- Deploy to Vercel first so the guide can truthfully lean on zero-config infrastructure and built-in observability.
543+
- Deploy your app and verify workflows run end-to-end with built-in observability.

0 commit comments

Comments
 (0)