> ## Documentation Index > Fetch the complete documentation index at: https://upstash-partnerstash.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Realtime Quickstart [**Upstash Realtime**](/realtime/overall/quickstart) 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 ```bash theme={null} npm install @upstash/workflow @upstash/realtime @upstash/redis zod ``` ### 2. Configure Upstash Realtime Create a Realtime instance in `lib/realtime.ts`: ```typescript theme={null} 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 ``` ### 3. Create a Realtime Endpoint Create an API route at `app/api/realtime/route.ts` to handle Realtime connections: ```typescript title="app/api/realtime/route.ts" theme={null} 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. ### 4. Add the Realtime Provider Wrap your application in the `RealtimeProvider` by updating your root layout at `app/layout.tsx`: ```tsx title="app/layout.tsx" theme={null} "use client" import { RealtimeProvider } from "@upstash/realtime/client" export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ### 5. Create a Typed Client Hook Create a typed `useRealtime` hook at `lib/realtime-client.ts`: ```typescript title="lib/realtime-client.ts" theme={null} "use client" import { createRealtime } from "@upstash/realtime/client" import type { RealtimeEvents } from "./realtime" export const { useRealtime } = createRealtime() ``` *** ## Building the Workflow ### 1. Create the Workflow Endpoint Create your workflow at `app/api/workflow/route.ts`: ```typescript title="app/api/workflow/route.ts" theme={null} import { serve } from "@upstash/workflow/nextjs" import { realtime } from "@/lib/realtime" type WorkflowPayload = { userId: string action: string } export const { POST } = serve(async (context) => { const { userId, action } = context.requestPayload const workflowRunId = context.workflowRunId const channel = realtime.channel(workflowRunId) await context.run("validate-data", async () => { const result = { valid: true, userId, action } // emit step completion await channel.emit("workflow.stepFinish", { stepName: "validate-data", result, }) return result }) // emit run completion await context.run("run-finish", () => channel.emit("workflow.runFinish", {})) return { success: true, workflowRunId } }) ``` **Key points:** * We use `realtime.channel(workflowRunId)` to create a unique channel per workflow run * Emit events after each step completes * Emit events inside `context.run` steps to ensure that they are emitted only once * Events are emitted to separate event names like `workflow.stepFinish` and `workflow.runFinish` ### 2. Create a Trigger Endpoint Create an endpoint to trigger workflows at `app/api/trigger/route.ts`: ```typescript title="app/api/trigger/route.ts" theme={null} 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`: ```typescript theme={null} "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(null) const [steps, setSteps] = useState([]) 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((data) => [...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 ```tsx theme={null} "use client" import { useWorkflow } from "@/hooks/useWorkflow" export default function WorkflowPage() { const { trigger, steps, isRunFinished } = useWorkflow() return (

{isRunFinished &&

✅ Workflow Finished!

}

Workflow Steps:

{steps.map((step, index) => (

{step.stepName} {Boolean(step.result) && : {JSON.stringify(step.result)}}

))}

) } ``` ## How It All Works Together 1. **User triggers workflow**: The frontend calls `/api/trigger`, which returns a `workflowRunId` 2. **Frontend subscribes**: Using the `workflowRunId`, the frontend subscribes to the Realtime channel 3. **Workflow executes**: The workflow runs as a background job, emitting events at each step 4. **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](https://github.com/upstash/workflow-js/tree/main/examples/upstash-realtime). ## Next Steps * Learn about [human-in-the-loop workflows with Realtime](./human-in-the-loop) * Explore [Realtime features](/realtime/overall/quickstart) * Check out [Workflow configuration options](/workflow/howto/configure)