AutoGineer
Generated banner for Upstash Workflow JS
Generated logo for Upstash Workflow JS

Upstash Workflow JS

UpstashOfficialCreated by Upstash

  • Skill
  • Tool integration
  • Cloud and DevOps
  • MIT
  • Medium risk
Download ZIP

From the author

Work with the @upstash/workflow TypeScript/JavaScript SDK for durable, long-running workflows in serverless functions, multi-step processes that survive timeouts, retries, and restarts (built on QStash). Use when defining a workflow endpoint with serve(), running steps with context.run, sleeping for minutes to days without holding a function open, calling external APIs with context.call, waiting for an external event or webhook, invoking other workflows, configuring retries, failure callbacks, and a DLQ, controlling concurrency, rate, and parallelism, triggering, cancelling, or inspecting runs with the Workflow client, building AI agents and orchestrators, human-in-the-loop approvals, realtime updates, local development with the QStash dev server, adding middleware, or migrating workflows safely. Also use when the user asks for durable execution, step functions, saga or orchestration patterns, background jobs with checkpoints, or long-running tasks on Vercel, Next.js, Cloudflare Workers, or other serverless
— the description by Upstash

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Upstash Workflow SDK enables developers to create reliable, multi-step workflows within serverless environments. By leveraging QStash, it allows functions to survive timeouts, retries, and restarts, effectively managing long-running processes that span minutes or days without keeping the underlying function execution active. It supports complex orchestration patterns, including step-by-step execution, external API calls, event waiting, human-in-the-loop approvals, and sophisticated flow control.

What it does

  • Exposes serverless endpoints for durable workflow execution.
  • Manages multi-step processes that persist across function restarts and timeouts.
  • Provides tools for flow control, including concurrency, rate limiting, and parallelism.
  • Supports advanced patterns like cross-workflow invocation and waiting for external events.
  • Enables local development and testing via the QStash dev server.
  • Facilitates human-in-the-loop workflows and real-time updates.

When to use it

  • When building long-running tasks that exceed standard serverless function execution limits.
  • When implementing saga or orchestration patterns in a distributed system.
  • When you need reliable background jobs with built-in checkpointing and retries.
  • When building AI agents or orchestrators that require stateful, multi-step execution.
  • When integrating human approval steps into automated backend processes.

Advantages

  • Eliminates the need to hold serverless functions open for long durations.
  • Built-in support for retries, failure callbacks, and dead-letter queues.
  • Seamless integration with popular serverless platforms like Vercel and Cloudflare Workers.
  • Simplifies complex state management for asynchronous operations.

Usage examples

“How do I define a basic two-step workflow using the Upstash SDK?”
The agent provides a code snippet using the serve() function and context.run() to define sequential steps that persist across execution.
“How can I trigger a workflow from my existing backend code?”
The agent demonstrates initializing the Workflow Client with a QStash token and using the trigger() method to initiate the workflow URL.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/upstash/upstash-workflow-js/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip upstash-workflow-js.zip -d .agents/skills

Documentation by Upstash

Upstash Workflow SDK

Bundled docs and source

Before writing or debugging SDK code, check node_modules/@upstash/workflow/docs/ for bundled docs and node_modules/@upstash/workflow/src/ for readable TypeScript source. Read and search the relevant files when present; otherwise use the references in this skill.

Quick Start

The Upstash Workflow SDK lets you expose serverless workflow endpoints and run them reliably using QStash under the hood.

Install:

npm install @upstash/workflow

Define a simple workflow endpoint:

import { serve } from "@upstash/workflow";

export const { POST } = serve(async (context) => {
  await context.run("step-1", () => console.log("step 1"));
  await context.run("step-2", () => console.log("step 2"));
});

Trigger it from your backend:

import { Client } from "@upstash/workflow";

const client = new Client({ token: process.env.QSTASH_TOKEN! });
await client.trigger({ url: "https://your-app.com/api/workflow" });

Other Skill Files

These files contain the full documentation. Use them for details, patterns, and advanced behavior.

  • basics:

    • basics/serve – How to expose workflow endpoints.

    • basics/context – Full API for workflow context (steps, waits, webhooks, events, invoke, etc.).

    • basics/client – Using the Workflow client to trigger, cancel, inspect, and notify runs.

  • features:

    • features/invoke – Cross‑workflow invocation.

    • features/reliability – Retries, failure callbacks, and DLQ.

    • features/flow-control – Rate limits, concurrency, and parallelism.

    • features/wait-for-event – Notify and wait-for-event patterns.

    • features/webhooks – Webhook creation and consumption.

  • how to:

    • how-to/local-dev – Local QStash dev server (auto via QSTASH_DEV=true) and tunneling.

    • how-to/realtime – Realtime and human‑in‑the‑loop workflows.

    • how-to/migrations – Migrating workflows safely.

    • how-to/middleware – Adding middleware to workflows.

  • other files:

    • rest-api – Low-level REST endpoints for interacting with QStash/Workflow.

    • troubleshooting – Common debugging and environment issues.

    • agents – Using Workflow with agents, orchestrators, and automation patterns.

Files

how-to/realtime.md

Realtime Workflow Integration (TypeScript)

This Skill provides guidance for building real‑time and human‑in‑the‑loop workflows using Upstash Workflow + Upstash Realtime. It covers event schemas, workflow patterns, emitting/receiving updates, and handling interactive pauses.

Key capabilities:

  • Emit strongly typed workflow events.

  • Subscribe to live updates in the frontend.

  • Implement pause/resume workflows using waitForEvent and notify.

Core Concepts

Realtime schema design

Define all workflow event types in one schema. Keep event definitions minimal and stable.

// lib/realtime.ts
const schema = {
  workflow: {
    // Completion events
    runFinish: z.object({}),
    stepFinish: z.object({ stepName: z.string(), result: z.unknown().optional() }),

    // Human‑in‑the‑loop events
    waitingForInput: z.object({ eventId: z.string(), message: z.string() }),
    inputResolved: z.object({ eventId: z.string() }),
  },
};

export const realtime = new Realtime({ schema, redis });
export type RealtimeEvents = InferRealtimeEvents<typeof realtime>;

Common mistakes:

  • Forgetting to wrap events under a namespace (e.g. workflow.*).

Emitting Events Inside Workflows

Emit inside context.run() whenever possible to avoid duplicate emissions on retries.

// app/api/workflow/route.ts
export const { POST } = serve(async (context) => {
  const channel = realtime.channel(context.workflowRunId);

  // Emit step updates
  await context.run("validate", async () => {
    const result = { ok: true };
    await channel.emit("workflow.stepFinish", { stepName: "validate", result });
    return result;
  });

  // Final event
  await context.run("finish", () => channel.emit("workflow.runFinish", {}));
});

Pitfall:

  • Emitting events outside of context.run() risks duplicate delivery if retries happen.

Human‑in‑the‑Loop Workflows

Use waitForEvent() with unique eventId values and emit a waitingForInput event immediately.

// Step that pauses for human input
const eventId = `approval-${context.workflowRunId}`;

const [{ eventData, timeout }] = await Promise.all([
  context.waitForEvent("wait-for-approval", eventId, { timeout: "5m" }),
  context.run("notify-wait", () =>
    channel.emit("workflow.waitingForInput", {
      eventId,
      message: "Waiting for approval...",
    })
  ),
]);

if (timeout) return { success: false, reason: "timeout" };

await context.run("resolved", () => channel.emit("workflow.inputResolved", { eventId }));

Important details:

  • Always handle timeout: otherwise the workflow may appear stuck.

  • Emit inputResolved so the UI can clear any pending state.

  • Use deterministic eventId prefixes per action/approval.

Notify Endpoint (User Response)

The frontend sends input back to the workflow using client.notify().

// app/api/notify/route.ts
export async function POST(req: NextRequest) {
  const { eventId, eventData } = await req.json();

  await workflowClient.notify({ eventId, eventData }); // resumes workflow
  return NextResponse.json({ success: true });
}

Common mistakes:

  • Sending the wrong eventId → workflow never resumes.

  • Sending eventData that doesn’t match the awaited type.

Realtime Subscription in the Frontend

Use a single hook to consume all workflow‑related events and manage state.

// lib/realtime-client.ts & useWorkflow hooks
useRealtime({
  enabled: !!workflowRunId,
  channels: [workflowRunId],
  events: [
    "workflow.stepFinish",
    "workflow.runFinish",
    "workflow.waitingForInput",
    "workflow.inputResolved",
  ],
  onData({ event, data }) {
    switch (event) {
      case "workflow.stepFinish":
        setSteps((prev) => [...prev, data]);
        break;
      case "workflow.waitingForInput":
        setWaitingState(data);
        break;
      case "workflow.inputResolved":
        setWaitingState((prev) => (prev?.eventId === data.eventId ? null : prev));
        break;
      case "workflow.runFinish":
        setIsRunFinished(true);
    }
  },
});

Pitfalls:

  • Forgetting to clear waiting state on inputResolved.

  • Forgetting to reset state on re‑trigger.

Triggering the Workflow

One simple endpoint triggers both basic and human‑in‑the‑loop flows.

// app/api/trigger/route.ts
export async function POST(req: NextRequest) {
  const workflowUrl = `${req.nextUrl.origin}/api/workflow`; // or /human-in-loop
  const { workflowRunId } = await workflowClient.trigger({
    url: workflowUrl,
    body: { userId: "123", action: "process" },
  });
  return NextResponse.json({ workflowRunId });
}

Recommended Patterns

  • Use one channel per workflow run (workflowRunId).

  • Always place event emissions inside context.run().

  • Use stable eventId formats for all interactive steps.

  • Subscribe to only the events your UI needs.

  • Reset UI state before every new trigger.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Medium risk

  • Possible data-exfiltration endpoints

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Upstash
Publisher
Upstash (Official)
Source
upstash/skills · skills/upstash-workflow-js · commit 9f9e3e5
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Upstash or Upstash.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download upstash-workflow-js.zip