Stepflow Documentation

The Express adapter allows you to integrate Stepflow into your Express applications. It supports both standalone routers and middleware.

Installation

pnpm add @stepflowjs/adapter-express

Usage

Standalone Router

You can create a dedicated Express Router for Stepflow routes and mount it to your main application.

import express from "express";
import { Stepflow } from "@stepflowjs/core";
import { createStepflowRouter } from "@stepflowjs/adapter-express";

const stepflow = new Stepflow({
  /* config */
});

const app = express();

// Mount Stepflow router
app.use("/api/stepflow", createStepflowRouter(stepflow));

app.listen(3000);

Middleware

Alternatively, you can use the Stepflow middleware to handle routes automatically.

import express from "express";
import { Stepflow } from "@stepflowjs/core";
import { createStepflowMiddleware } from "@stepflowjs/adapter-express";

const stepflow = new Stepflow({
  /* config */
});

const app = express();

// Use middleware
app.use(
  createStepflowMiddleware(stepflow, {
    basePath: "/api/stepflow",
  }),
);

app.listen(3000);

Configuration

The createStepflowRouter and createStepflowMiddleware functions accept an options object:

Option	Type	Description
`basePath`	`string`	Prefix for all routes (e.g., `"/api/stepflow"`)
`endpoints`	`EndpointOption`	Preset or fine-grained endpoint configuration
`auth`	`ExpressAuthConfig`	Authorization configuration
`healthCheck`	`() => Promise<boolean>`	Custom health check function
`onAuthFailure`	`Function`	Callback when authorization fails

Authorization Example

import {
  createStepflowRouter,
  createApiKeyAuth,
} from "@stepflowjs/adapter-express";

const router = createStepflowRouter(stepflow, {
  auth: {
    global: createApiKeyAuth(process.env.STEPFLOW_API_KEY),
    health: () => ({ ok: true }), // Public health check
  },
});

Express-specific Context

When writing custom auth handlers for Express, the extra property in the AuthContext contains the Express Response object.

const customAuth = (ctx) => {
  const res = ctx.extra; // Express Response
  const user = res.locals.user;

  if (!user) return { ok: false, message: "User not found in locals" };
  return { ok: true };
};

Express Adapter