Next.js

GitHub Repository

You can find the project source code on GitHub.

This guide provides detailed, step-by-step instructions on how to use and deploy Upstash Workflow with Next.js. You can also explore our Next.js example 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

In October 2024, we released a new SDK, @upstash/workflow, for Upstash Workflow. If you were using @upstash/qstash for Upstash Workflow, you can refer to the migration guide for the transition.

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

• npm
• pnpm
• bun

npm install @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.

Terminal

touch .env.local

Open the environment file and add your QStash token:

.env.local

QSTASH_TOKEN=xxxxxxxxx

Replace xxxxxxxxx with your actual QStash token found here:

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:

• Minimal example
• With request object
• Minimal example (Pages Router)
• With request object (Pages Router)

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

For QStash, a tool that’s used to run workflows under the hood, you need to provide a live URL for your workflow endpoint. Here’s how to set up your workflow endpoint for local development.

Once you have a live URL, proceeed with either one of the following steps:

Setting an enviroment variable (recommended)

Set your publically accessible URL as an environment variable. This variable is only needed for local development and doesn’t need to be set in production:

.env.local

UPSTASH_WORKFLOW_URL=https://<YOUR_NGROK_OR_TUNNEL_URL>/

Using the baseUrl option

As an alternative to setting an environment variable, you can also use the baseUrl option in the serve method. This option is only needed for local development and can be omitted in production:

• App Router
• Pages Router

app/api/workflow/route.ts

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

export const { POST } = serve(
  async (context) => { ... },
  {
    // no /api/workflow, just the base URL
    baseUrl: "https://<YOUR_NGROK_OR_TUNNEL_URL>/",
  }
)

Triggering the workflow

After setting your live URL as the environment variable or baseUrl option, trigger your workflow by first starting your Next.js app:

Terminal

npm run dev

and then making a POST request to your workflow endpoint. For each workflow run, a unique workflow run ID is returned:

Terminal

curl -X POST https://<YOUR_NGROK_OR_TUNNEL_URL>/api/workflow

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

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, the baseUrl option in the serve function can be omitted in production:

   • App Router
   • Pages Router
   app/api/workflow/route.ts

   import { serve } from "@upstash/workflow/nextjs";
   
   export const { POST } = serve(
     async (context) => {
       // Your workflow steps
     },
     {
       // Conditionally set in development, but not in production
       baseUrl:
         process.env.NODE_ENV === "development"
           ? "https://<YOUR_NGROK_OR_TUNNEL_URL>/"
           : undefined,
     }
   )
   

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

   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 our Next.js example 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.