This guide provides step-by-step instructions on how to use and deploy Upstash Workflow with Next.js.

GitHub Repository

You can find the project source code on GitHub.

Deploy With Vercel

Deploy the project to Vercel with a single click.

​
Prerequisites

  • Node.js and npm (or another package manager) installed.
You can integrate Upstash Workflow into an existing Next.js app, or follow this guide to create a new Next.js project from scratch.

​
Step 1: Installation

Run the following command to install the Upstash Workflow SDK in your Next.js app. 
npm install @upstash/workflow

​
Step 2: Run the development server

Upstash Workflow is built on top of Upstash QStash. In a production environment, your application connects to the managed QStash servers hosted by Upstash. This ensures that requests are delivered reliably, securely, and at scale without requiring you to run and maintain your own infrastructure. For local development, you don’t need to depend on the managed QStash servers. Instead, you can run a local QStash server directly on your machine. This local server behaves just like the production version but does not require external network calls. Start the local server with: 
npx @upstash/qstash-cli dev
When the server starts, it will print the credentials. You’ll need these values in the next step to connect your Next.js app to QStash. You can enable local mode in the Upstash Workflow dashboard to use the UI while developing locally.
Enable local mode on dashboard

​
Step 3: Configure Environment Variables

Next, you need to configure your Next.js app to connect with the local QStash server by setting environment variables. In the root of your project, create a .env.local file (or update your existing one) and add the values printed by the QStash local server: 
QSTASH_URL=http://127.0.0.1:8080
QSTASH_TOKEN=eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0=
QSTASH_CURRENT_SIGNING_KEY=sig_7kYjw48mhY7kAjqNGcy6cr29RJ6r
QSTASH_NEXT_SIGNING_KEY=sig_5ZB6DVzB1wjE8S6rZ7eenA8Pdnhs
For production, replace these with your actual credentials from the Upstash Workflow dashboard.

​
Step 3: Create a Workflow Endpoint

With your environment ready, the next step is to define your first workflow endpoint. In Upstash Workflow, every workflow is exposed as an endpoint. Every endpoint you expose using the SDK’s serve() function acts as a workflow that can be triggered independently. In Next.js, these endpoints are implemented as API routes. Create the file according to your router setup:
  • App Router → put the endpoint under app/api
  • Pages Router → put the endpoint under pages/api
app/api/workflow/route.ts
import { serve } from "@upstash/workflow/nextjs"

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

    await context.run("second-step", () => {
      console.log("second step ran")
    })
  }
)

​
Step 4: Run the Workflow Endpoint

Once your endpoint is defined, the next step is to trigger a workflow run. You can start a new workflow run using the trigger() function from the Upstash Workflow SDK. 
import { Client } from "@upstash/workflow";

const client = Client()

const { workflowRunId } = await client.trigger({
    url: `http://localhost:3000/api/workflow`,
    retries: 3,
});
The trigger() function should typically be called from a server-side action (not directly in client-side code) to keep your credentials secure.
Check the Upstash Workflow dashboard to view logs of your workflow run:
Debug a workflow run on UI
Inside the trigger() call, you need to provide the URL of your workflow endpoint:To avoid hardcoding URLs, you can define a BASE_URL constant and set it based on the environment. A common pattern is to check an environment variable that only exists in production:
const BASE_URL = process.env.VERCEL_URL
  ? `https://${process.env.VERCEL_URL}`
  : `http://localhost:3000`

const { workflowRunId } = await client.trigger({
    url: `${BASE_URL}/api/workflow`,
    retries: 3,
});

​
Step 5: Deploying to Production

You now have everything you need to deploy your application to production! 🎉 Before deploying, make sure your configuration no longer relies on local development settings:
  • Workflow URL: Update the trigger() call to use your production domain (see the tip above for using a dynamic BASE_URL).
  • Credentials: Replace local QStash credentials with your production tokens.
  • Environment Variables: Verify that all required variables are set correctly in your deployment environment.

​
Next Steps

Now that you’ve created and deployed your first workflow, here are some recommended guides to continue learning:
  1. Learn the Workflow API: Dive deeper into the full API surface and advanced capabilities.
  2. Configure Workflow Runs: Learn how to configure workflow execution to fit your app’s needs.
  3. Handle Failures: Understand how to detect and recover from failed workflow runs.