Next.js

This guide provides detailed, step-by-step instructions on how to use and deploy Upstash Workflow with Next.js. You can also explore the source code for a detailed, end-to-end example and best practices.

​

Prerequisites

1. An Upstash QStash API key.
2. Node.js and npm (another package manager) installed.

If you haven’t obtained your QStash API key yet, you can do so by signing up for an Upstash account and navigating to your QStash dashboard.

​

Step 1: Installation

First, install the Workflow SDK in your Next.js project:

npm install @upstash/workflow

npm install @upstash/workflow

pnpm install @upstash/workflow

bun add @upstash/workflow

​

Step 2: Configure Environment Variables

Create a .env.local file in your project root and add your QStash token. This token is used to authenticate your application with the QStash service.

touch .env.local

Upstash Workflow is powered by QStash, which requires access to your endpoint to execute workflows. When your app is deployed, QStash will use the app’s URL. However, for local development, you have two main options: use a local QStash server or set up a local tunnel.

​

Option 1: Local QStash Server

To start the local QStash server, run:

npx @upstash/qstash-cli dev

Once the command runs successfully, you’ll see QSTASH_URL and QSTASH_TOKEN values in the console. Add these values to your .env.local file:

QSTASH_URL="http://127.0.0.1:8080"
QSTASH_TOKEN=<QSTASH_TOKEN>

This approach allows you to test workflows locally without affecting your billing. However, runs won’t be logged in the Upstash Console.

​

Option 2: Local Tunnel

Alternatively, you can set up a local tunnel. For this option:

1. Copy the QSTASH_TOKEN from the Upstash Console.
2. Update your .env.local file with the following:

QSTASH_TOKEN="***"
UPSTASH_WORKFLOW_URL=<UPSTASH_WORKFLOW_URL>

• Replace *** with your actual QStash token.
• Set UPSTASH_WORKFLOW_URL to the public URL provided by your local tunnel.

Here’s where you can find your QStash token:

Using a local tunnel connects your endpoint to the production QStash, enabling you to view workflow logs in the Upstash Console.

​

Step 3: Create a Workflow Endpoint

A workflow endpoint allows you to define a set of steps that, together, make up a workflow. Each step contains a piece of business logic that is automatically retried on failure, with easy monitoring via our visual workflow dashboard.

To define a workflow endpoint in a Next.js project, navigate into the Next.js app/api directory and create a new folder, for example called workflow. Inside this folder, create a route.ts file that contains your workflow:

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")
    })
  }
)

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")
    })
  }
)

import { serve } from "@upstash/workflow/nextjs";
import { NextRequest } from "next/server";

export const POST = async (request: NextRequest) => {
  // do something with the native request object
  const { POST: handler } = serve(async (context) => {
    // Your workflow steps
  });

  return await handler(request);
}

import { servePagesRouter } from "@upstash/workflow/nextjs";

const { handler } = servePagesRouter<string>(
  async (context) => {
    await context.run("initial-step", () => {
      console.log("initial step ran")
    })

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

import type { NextApiRequest, NextApiResponse } from "next";
import { servePagesRouter } from "@upstash/workflow/nextjs";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // do something with the native request object
  const { handler } = servePagesRouter(
    async (context) => {
      // Your workflow steps
    }
  )

  await handler(req, res)
}

​

Step 4: Run the Workflow Endpoint

After defining the endpoint, you can trigger your workflow by starting your app:

npm run dev

Then, make a POST request to your workflow endpoint. For each workflow run, a unique workflow run ID is returned:

curl -X POST https://localhost:3000/api/workflow

# result: {"workflowRunId":"wfr_xxxxxx"}

In Nextjs Pages, always send content-type: text/plain header.

See the documentation on starting a workflow for other ways you can start your workflow.

If you are using a local tunnel, you can use this ID to track the workflow run and see its status in your QStash workflow dashboard. All steps are listed with their statuses, headers, and body for a detailed overview of your workflow from start to finish. Click on a step to see its detailed logs.

​

Step 5: Deploying to Production

When deploying your Next.js application with Upstash Workflow to production, there are a few key points to keep in mind:

1. Environment Variables: Make sure that all necessary environment variables are set in your Vercel project settings. For example, your QSTASH_TOKEN and any other configuration variables your workflow might need.

2. Remove Local Development Settings: In your production code, you can remove or conditionally exclude any local development settings. For example, if you used local tunnel for local development

3. Deployment: Deploy your Next.js application to Vercel, AWS Amplify or other platforms as you normally would. These platforms will automatically detect and build your Next.js application.

4. Verify Workflow Endpoint: After deployment, verify that your workflow endpoint is accessible by making a POST request to your production URL:

   Terminal

   Copy

   Ask AI

   curl -X POST https://<YOUR-PRODUCTION-URL>/api/workflow
   

5. Monitor in QStash Dashboard: Use the QStash dashboard to monitor your production workflows. You can track workflow runs, view step statuses, and access detailed logs.

6. Set Up Alerts: Consider setting up alerts in Sentry or other monitoring tools to be notified of any workflow failures in production.

​

Next Steps

1. Learn how to protect your workflow endpoint from unauthorized access by securing your workflow endpoint.

2. Explore the source code for a detailed, end-to-end example and best practices.

3. For setting up and testing your workflows in a local environment, check out our local development guide.