Next.js

This guide shows you how to install Workflow DevKit in a Next.js project.

Install dependencies

Install the workflow package:

npm install workflow

yarn add workflow

pnpm add workflow

Configure Next.js

Wrap your Next.js config with withWorkflow() to enable the "use workflow" and "use step" directives:

next.config.ts

import { withWorkflow } from "workflow/next";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Your Next.js config
};

export default withWorkflow(nextConfig);

The withWorkflow function configures both Turbopack and Webpack loaders to transform workflow and step functions.

Configuration Options

You can pass options to withWorkflow:

next.config.ts

export default withWorkflow(nextConfig, {
  workflows: {
    lazyDiscovery: true,  // Defer workflow discovery until needed
    local: {
      port: 3000,          // Local development port
      dataDir: '.next/workflow-data'  // Data storage directory
    }
  }
});

Update middleware (if applicable)

If your Next.js app uses middleware, exclude Workflow’s internal paths:

middleware.ts

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.well-known/workflow/).*)',
  ],
};

Enable TypeScript support (Optional)

Add the Workflow TypeScript plugin to your tsconfig.json for IntelliSense:

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "workflow"
      }
    ]
  }
}

How it works

The Next.js integration:

Configures Turbopack and Webpack loaders to transform workflow files
Discovers workflows from pages/, app/, src/pages/, and src/app/ directories
Generates route handlers at .well-known/workflow/v1/* endpoints
Uses deferred entries in Next.js 16.1+ for optimized builds
Automatically configures local storage in development
Integrates with Vercel’s infrastructure in production

Example workflow

workflows/user-signup.ts

import { sleep } from "workflow";

export async function handleUserSignup(email: string) {
  "use workflow";

  const user = await createUser(email);
  await sendWelcomeEmail(user);
  await sleep("1 day");
  await sendFollowUpEmail(user);

  return { userId: user.id };
}

async function createUser(email: string) {
  "use step";
  return { id: crypto.randomUUID(), email };
}

async function sendWelcomeEmail(user: { id: string; email: string }) {
  "use step";
  console.log(`Sending welcome email to ${user.email}`);
}

async function sendFollowUpEmail(user: { id: string; email: string }) {
  "use step";
  console.log(`Sending follow-up email to ${user.email}`);
}

Triggering workflows

Start workflows from API routes or Server Actions:

app/api/signup/route.ts

import { start } from "workflow/api";
import { handleUserSignup } from "@/workflows/user-signup";

export async function POST(request: Request) {
  const { email } = await request.json();
  await start(handleUserSignup, [email]);
  return Response.json({ message: "Workflow started" });
}

Getting Started

Installation

Core Concepts

Building AI Agents

How It Works

Deployment

Observability

Testing

Error Reference

Configuration Options

How it works

Example workflow

Triggering workflows

Next steps

Core Concepts

API Reference

​Configuration Options

​How it works

​Example workflow

​Triggering workflows

​Next steps

Core Concepts

API Reference

Configuration Options

How it works

Example workflow

Triggering workflows

Next steps