upstash/workflow-js / skills
upstash-workflow-js
UnverifiedLightweight guidance for using the Upstash Workflow SDK to define, trigger, and manage workflows. Use this Skill whenever a user wants to create workflow endpoints, run steps, or interact with the Upstash Workflow client.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.2 KB |
| agents.md | markdown | 6.7 KB |
| basics/client.md | markdown | 4.1 KB |
| basics/context.md | markdown | 5.1 KB |
| basics/serve.md | markdown | 2.4 KB |
| features/flow-control.md | markdown | 3.9 KB |
| features/invoke.md | markdown | 2.6 KB |
| features/retries-failures-reliability.md | markdown | 6.3 KB |
| features/wait-for-event.md | markdown | 2.8 KB |
| features/webhooks.md | markdown | 2.5 KB |
| how-to/local-dev.md | markdown | 3.2 KB |
| how-to/middleware.md | markdown | 4.7 KB |
| how-to/migrations.md | markdown | 4.8 KB |
| how-to/realtime.md | markdown | 4.8 KB |
| rest-api.md | markdown | 6.6 KB |
| troubleshooting.md | markdown | 4.8 KB |
how-to/migrations.md
View on GitHub# Migration Guide for Upstash Workflow (TypeScript)
This document provides a clear, task-focused overview of migrations between Workflow versions. It highlights breaking changes, how to update your code, and common pitfalls to avoid. Code samples combine multiple parameters in each example to reduce redundancy.
## January 2026 – Major Release 1.0.0
### Agents API → moved to a separate package
The Agents API was removed from the core workflow package and placed into `@upstash/workflow-agents` so the base SDK no longer depends on large AI-related libraries.
**Key changes**:
- Must install and import `agentWorkflow` from the new package.
- Agents access now happens through an `agents` helper created per workflow invocation.
```ts
// Before
import { serve } from "@upstash/workflow/nextjs";
export const { POST } = serve(async (context) => {
const model = context.agents.openai("gpt-3.5-turbo");
const agent = context.agents.agent({
/* ... */
});
const task = context.agents.task({
/* ... */
});
});
// After
import { serve } from "@upstash/workflow/nextjs";
import { agentWorkflow } from "@upstash/workflow-agents";
export const { POST } = serve(async (context) => {
const agents = agentWorkflow(context);
const model = agents.openai("gpt-3.5-turbo");
const agent = agents.agent({
/* ... */
});
const task = agents.task({
/* ... */
});
});
```
---
### `keepTriggerConfig` and `useFailureFunction` removed
These fields were redundant—both behaviors are now always enabled.
```ts
// Before
await client.trigger({
url: "...",
retries: 3,
keepTriggerConfig: true,
useFailureFunction: true,
});
// After
await client.trigger({ url: "...", retries: 3 });
```
---
### Configuration moved from `serve()` → `client.trigger()`
Options such as `retries`, `flowControl`, `retryDelay`, and `failureUrl` no longer belong in `serve()`.
```ts
// Before
export const { POST } = serve(
async (context) => {
/* ... */
},
{
retries: 3,
retryDelay: "1000 * (1 + retried)",
flowControl: { key: "my-key", rate: 10 },
}
);
await client.trigger({ url: "..." });
// After
export const { POST } = serve(async (context) => {
/* ... */
});
await client.trigger({
url: "...",
retries: 3,
retryDelay: "1000 * (1 + retried)",
flowControl: { key: "my-key", rate: 10 },
});
```
---
### `stringifyBody` removed from `context.call` and `context.invoke`
Bodies must now be strings.
```ts
// Before
await context.call("step", {
url: "https://api.example.com",
method: "POST",
body: { key: "value" },
stringifyBody: true,
});
// After
await context.call("step", {
url: "https://api.example.com",
method: "POST",
body: JSON.stringify({ key: "value" }),
});
// Same change applies to invoke
await context.invoke("other", {
workflow: otherWorkflow,
body: JSON.stringify({ key: "value" }),
});
```
---
### Logger removed → middleware system added
Removed `WorkflowLogger` class and added `WorkflowMiddleware`. Updated `verbose` param to only allow `true` (in this case, `loggingMiddleware` will be used which prints to console).
```ts
import { loggingMiddleware, WorkflowMiddleware } from "@upstash/workflow";
const stepFinish = new WorkflowMiddleware({
name: "step-finish",
callbacks: {
afterExecution: async ({ stepName, result }) =>
console.log(`Step ${stepName} finished`, result),
},
});
export const { POST } = serve(
async (context) => {
/* ... */
},
{
middlewares: [loggingMiddleware, stepFinish],
}
);
```
---
## October 2024 – Migration from `@upstash/qstash`
### Install the new package
Replace all workflow usage from `@upstash/qstash` with `@upstash/workflow`.
### Serve import and return shape changed
Most environments now require destructuring `{ POST }`.
```ts
// Before
import { serve } from "@upstash/qstash/nextjs";
export const POST = serve(...);
// After
import { serve } from "@upstash/workflow/nextjs";
export const { POST } = serve(...);
```
### `context.call` updated
Now returns `{ status, headers, body }` and **does not fail** the workflow if the HTTP call fails.
```ts
const { status, headers, body } = await context.call("call-step", {
url: "https://example.com/api",
method: "POST",
});
```
**Pitfall**: Old runs may not contain `status` or `headers` until fully migrated.
### Errors renamed
- `QStashWorkflowError` → `WorkflowError`
- `QStashWorkflowAbort` → `WorkflowAbort`
---
## Summary of Common Mistakes
- Using `context.agents` instead of the new `agentWorkflow()` helper.
- Leaving old serve-config options (`retries`, `flowControl`, etc.).
- Forgetting to `JSON.stringify` bodies.
- Assuming `context.call` failures stop workflow execution.
- Mix-and-matching `@upstash/qstash` and `@upstash/workflow` imports.
This guide ensures smooth migration with minimal friction while highlighting where behavioral changes may break existing workflows.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |