Stepflow Documentation

The Next.js adapter provides route handlers for the Next.js App Router.

Installation

pnpm add @stepflowjs/adapter-nextjs

Usage

The adapter provides a createStepflowHandlers function that returns individual handlers for each Stepflow route. You should export these from your route.ts files.

1. Create a Stepflow instance

// lib/stepflow.ts
import { Stepflow } from "@stepflowjs/core";
import { MemoryStorageAdapter } from "@stepflowjs/storage-memory";

export const stepflow = new Stepflow({
  storage: new MemoryStorageAdapter(),
});

2. Set up Route Handlers

You need to create several route files to handle the different Stepflow endpoints.

Trigger Handler

app/api/stepflow/trigger/[workflowId]/route.ts

import { stepflow } from "@/lib/stepflow";
import { createStepflowHandlers } from "@stepflowjs/adapter-nextjs";

const { triggerHandler } = createStepflowHandlers(stepflow);
export const POST = triggerHandler;

Run Status Handler

app/api/stepflow/runs/[runId]/route.ts

import { stepflow } from "@/lib/stepflow";
import { createStepflowHandlers } from "@stepflowjs/adapter-nextjs";

const { runHandler } = createStepflowHandlers(stepflow);
export const GET = runHandler;

SSE Stream Handler

app/api/stepflow/runs/[runId]/stream/route.ts

import { stepflow } from "@/lib/stepflow";
import { createStepflowHandlers } from "@stepflowjs/adapter-nextjs";

const { streamHandler } = createStepflowHandlers(stepflow);
export const GET = streamHandler;

Notify Handler

app/api/stepflow/notify/[eventId]/route.ts

import { stepflow } from "@/lib/stepflow";
import { createStepflowHandlers } from "@stepflowjs/adapter-nextjs";

const { notifyHandler } = createStepflowHandlers(stepflow);
export const POST = notifyHandler;

Health Handler

app/api/stepflow/health/route.ts

import { stepflow } from "@/lib/stepflow";
import { createStepflowHandlers } from "@stepflowjs/adapter-nextjs";

const { healthHandler } = createStepflowHandlers(stepflow);
export const GET = healthHandler;

Configuration

The createStepflowHandlers function accepts an options object:

Option	Type	Description
`endpoints`	`EndpointOption`	Preset or fine-grained endpoint configuration
`auth`	`NextAuthConfig`	Authorization configuration
`healthCheck`	`() => Promise<boolean>`	Custom health check function
`onAuthFailure`	`Function`	Callback when authorization fails

Authorization Example

import {
  createStepflowHandlers,
  createApiKeyAuth,
} from "@stepflowjs/adapter-nextjs";

const { triggerHandler } = createStepflowHandlers(stepflow, {
  auth: {
    global: createApiKeyAuth(process.env.STEPFLOW_API_KEY),
  },
});

Next.js-specific Context

When writing custom auth handlers for Next.js, the extra property in the AuthContext contains the original Request object.

const customAuth = async (ctx) => {
  const request = ctx.extra; // Next.js Request
  // Perform custom auth logic
  return { ok: true };
};

Next.js Adapter