Realtime Quickstart

Upstash Realtime lets you emit events from your workflow and subscribe to them in real-time on your frontend.

How It Works

Upstash Realtime is powered by Upstash Redis and provides a clean, 100% type-safe API for publishing and subscribing to events:

Your frontend can subscribe to events
When you emit an event, it’s instantly delivered to live subscribers on the frontend
You can also replay events that happened in the past

This guide shows you how to integrate Upstash Workflow with Upstash Realtime to display real-time progress updates in your frontend.

Setup

1. Install Packages

npm install @upstash/workflow @upstash/realtime @upstash/redis zod

2. Configure Upstash Realtime

Create a Realtime instance in lib/realtime.ts:

lib/realtime.ts

import { InferRealtimeEvents, Realtime } from "@upstash/realtime";
import { Redis } from "@upstash/redis";
import z from "zod/v4";

const redis = Redis.fromEnv();

const schema = {
  workflow: {
    runFinish: z.object({}),
    stepFinish: z.object({
      stepName: z.string(),
      result: z.unknown().optional(),
    }),
  },
};

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

3. Create a Realtime Middleware

Create a custom middleware that will emit events to Realtime at lib/middleware.ts:

lib/middleware.ts

import { WorkflowMiddleware } from "@upstash/workflow";
import { realtime } from "./realtime";

export const realtimeMiddleware = new WorkflowMiddleware({
  name: "realtime-events",
  callbacks: {
    afterExecution: async ({ context, stepName, result }) => {
      const channel = realtime.channel(context.workflowRunId);
      await channel.emit("workflow.stepFinish", {
        stepName,
        result,
      });
    },
    runCompleted: async ({ context }) => {
      const channel = realtime.channel(context.workflowRunId);
      await channel.emit("workflow.runFinish", {});
    },
  },
});

Key points:

The afterExecution callback is triggered after each workflow step completes
The runCompleted callback is triggered when the entire workflow finishes
We use context.workflowRunId to create a unique channel for each workflow run
Events are automatically emitted without needing to manually call emit inside your workflow steps

4. Create a Realtime Endpoint

Create an API route at app/api/realtime/route.ts to handle Realtime connections:

app/api/realtime/route.ts

import { handle } from "@upstash/realtime";
import { realtime } from "@/lib/realtime";

export const GET = handle({ realtime });

This endpoint enables Server-Sent Events (SSE) connections for real-time updates.

5. Add the Realtime Provider

Wrap your application in the RealtimeProvider by updating your root layout at app/layout.tsx:

app/layout.tsx

"use client";

import { RealtimeProvider } from "@upstash/realtime/client";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <RealtimeProvider>{children}</RealtimeProvider>
      </body>
    </html>
  );
}

6. Create a Typed Client Hook

Create a typed useRealtime hook at lib/realtime-client.ts:

lib/realtime-client.ts

"use client";

import { createRealtime } from "@upstash/realtime/client";
import type { RealtimeEvents } from "./realtime";

export const { useRealtime } = createRealtime<RealtimeEvents>();

Building the Workflow

1. Create the Workflow Endpoint

Create your workflow at app/api/workflow/route.ts:

app/api/workflow/route.ts

import { serve } from "@upstash/workflow/nextjs";
import { realtimeMiddleware } from "@/lib/middleware";

type WorkflowPayload = {
  userId: string;
  action: string;
};

export const { POST } = serve<WorkflowPayload>(
  async (context) => {
    const { userId, action } = context.requestPayload;

    await context.run("validate-data", async () => {
      return { valid: true, userId, action };
    });

    await context.run("process-action", async () => {
      // Your business logic here
      return { processed: true, userId, action };
    });

    return { success: true, workflowRunId: context.workflowRunId };
  },
  {
    middlewares: [realtimeMiddleware],
  }
);

Key points:

Import the realtimeMiddleware from @/lib/middleware
Pass the middleware in the middlewares array to the serve function
The middleware automatically emits events after each step and when the workflow completes

2. Create a Trigger Endpoint

Create an endpoint to trigger workflows at app/api/trigger/route.ts:

app/api/trigger/route.ts

import { NextRequest, NextResponse } from "next/server";
import { Client } from "@upstash/workflow";

export const workflowClient = new Client({
  token: process.env.QSTASH_TOKEN,
  baseUrl: process.env.QSTASH_URL,
});

export async function POST(request: NextRequest) {
  const workflowUrl = `${request.nextUrl.origin}/api/workflow`;

  const { workflowRunId } = await workflowClient.trigger({
    url: workflowUrl,
    body: {
      userId: "user-123",
      action: "process-data",
    },
  });

  return NextResponse.json({ workflowRunId });
}

Building the Frontend

1. Create a Custom Hook

Create a React hook to manage the Realtime subscription at hooks/useWorkflow.ts:

"use client";

import { useRealtime } from "@/lib/realtime-client";
import { useState, useCallback } from "react";

interface WorkflowStep {
  stepName: string;
  result?: unknown;
}

export function useWorkflow() {
  const [workflowRunId, setWorkflowRunId] = useState<string | null>(null);
  const [steps, setSteps] = useState<WorkflowStep[]>([]);
  const [isRunFinished, setIsRunFinished] = useState(false);

  useRealtime({
    enabled: Boolean(workflowRunId),
    channels: workflowRunId ? [workflowRunId] : [],
    events: ["workflow.stepFinish", "workflow.runFinish"],
    onData({ event, data }) {
      if (event === "workflow.stepFinish") {
        setSteps((prev) => [...prev, data]);
      }

      if (event === "workflow.runFinish") {
        setIsRunFinished(true);
      }
    },
  });

  const trigger = () => {
    setSteps([]);
    setIsRunFinished(false);

    const response = await fetch("/api/trigger", {
      method: "POST",
    });

    const data = await response.json();
    setWorkflowRunId(data.workflowRunId);
  };

  return {
    trigger,
    workflowRunId,
    steps,
    isRunFinished,
  };
}

Key features:

Subscribe to multiple events using the events array: ["workflow.stepFinish", "workflow.runFinish"]
The hook manages both triggering the workflow and subscribing to updates
Type-safe event handling with TypeScript

2. Use the Hook in Your Component

"use client";

import { useWorkflow } from "@/hooks/useWorkflow";

export default function WorkflowPage() {
  const { trigger, steps, isRunFinished } = useWorkflow();

  return (
    <div>
      <button onClick={trigger}>Click to Trigger Workflow</button>

      {isRunFinished && <p>✅ Workflow Finished!</p>}

      <p>Workflow Steps:</p>

      {steps.map((step, index) => (
        <div key={index}>
          <strong>{step.stepName}</strong>
          {Boolean(step.result) && <span>: {JSON.stringify(step.result)}</span>}
        </div>
      ))}
    </div>
  );
}

How It All Works Together

User triggers workflow: The frontend calls /api/trigger, which returns a workflowRunId
Frontend subscribes: Using the workflowRunId, the frontend subscribes to the Realtime channel
Workflow executes: The workflow runs as a background job, emitting events at each step
Real-time updates: As the workflow emits events, they’re instantly delivered to the frontend via Server-Sent Events

Full Example

For a complete working example with all steps, error handling, and UI components, check out the Upstash Realtime example on GitHub.

Next Steps

Learn about human-in-the-loop workflows with Realtime
Explore Realtime features
Check out Workflow configuration options

Getting Started

Core Concepts

Features

Agents

API Reference

Resources

How It Works

Setup

1. Install Packages

2. Configure Upstash Realtime

3. Create a Realtime Middleware

4. Create a Realtime Endpoint

5. Add the Realtime Provider

6. Create a Typed Client Hook

Building the Workflow

1. Create the Workflow Endpoint

2. Create a Trigger Endpoint

Building the Frontend

1. Create a Custom Hook

2. Use the Hook in Your Component

How It All Works Together

Full Example

Next Steps

​How It Works

​Setup

​1. Install Packages

​2. Configure Upstash Realtime

​3. Create a Realtime Middleware

​4. Create a Realtime Endpoint

​5. Add the Realtime Provider

​6. Create a Typed Client Hook

​Building the Workflow

​1. Create the Workflow Endpoint

​2. Create a Trigger Endpoint

​Building the Frontend

​1. Create a Custom Hook

​2. Use the Hook in Your Component

​How It All Works Together

​Full Example

​Next Steps

How It Works

Setup

1. Install Packages

2. Configure Upstash Realtime

3. Create a Realtime Middleware

4. Create a Realtime Endpoint

5. Add the Realtime Provider

6. Create a Typed Client Hook

Building the Workflow

1. Create the Workflow Endpoint

2. Create a Trigger Endpoint

Building the Frontend

1. Create a Custom Hook

2. Use the Hook in Your Component

How It All Works Together

Full Example

Next Steps