Skip to main content
This guide shows you how to install Workflow DevKit in a Next.js project.
1

Install dependencies

Install the workflow package:
npm install workflow
2

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
    }
  }
});
3

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/).*)',
  ],
};
4

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

​
Next steps

Core Concepts

Learn about workflows and steps

API Reference

View the full Next.js API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us