> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel/workflow/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js

> Install and configure Workflow DevKit in your Next.js application

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

<Steps>
  <Step title="Install dependencies">
    Install the `workflow` package:

    <CodeGroup>
      ```bash npm theme={null}
      npm install workflow
      ```

      ```bash yarn theme={null}
      yarn add workflow
      ```

      ```bash pnpm theme={null}
      pnpm add workflow
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure Next.js">
    Wrap your Next.js config with `withWorkflow()` to enable the `"use workflow"` and `"use step"` directives:

    ```typescript next.config.ts theme={null}
    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`:

    ```typescript next.config.ts theme={null}
    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
        }
      }
    });
    ```
  </Step>

  <Step title="Update middleware (if applicable)">
    If your Next.js app uses middleware, exclude Workflow's internal paths:

    ```typescript middleware.ts theme={null}
    export const config = {
      matcher: [
        '/((?!_next/static|_next/image|favicon.ico|.well-known/workflow/).*)',
      ],
    };
    ```
  </Step>

  <Step title="Enable TypeScript support (Optional)">
    Add the Workflow TypeScript plugin to your `tsconfig.json` for IntelliSense:

    ```json tsconfig.json theme={null}
    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "workflow"
          }
        ]
      }
    }
    ```
  </Step>
</Steps>

## 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

```typescript workflows/user-signup.ts theme={null}
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:

```typescript app/api/signup/route.ts theme={null}
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

<CardGroup cols={2}>
  <Card title="Core Concepts" href="/concepts/workflows-and-steps">
    Learn about workflows and steps
  </Card>

  <Card title="API Reference" href="/api-reference/integrations/next">
    View the full Next.js API reference
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.