Stepflow Documentation

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

Installation

pnpm add @stepflowjs/adapter-hono

Usage

Standalone Routes

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

import { Hono } from "hono";
import { Stepflow } from "@stepflowjs/core";
import { createStepflowRoutes } from "@stepflowjs/adapter-hono";

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

const app = new Hono();

// Mount Stepflow routes
app.route("/api/stepflow", createStepflowRoutes(stepflow));

export default app;

Middleware

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

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

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

const app = new Hono();

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

export default app;

Configuration

The createStepflowRoutes 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`	`HonoAuthConfig`	Authorization configuration
`healthCheck`	`() => Promise<boolean>`	Custom health check function
`onAuthFailure`	`Function`	Callback when authorization fails

Authorization Example

import { createStepflowRoutes, createApiKeyAuth } from "@stepflowjs/adapter-hono";

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

Hono-specific Context

When writing custom auth handlers for Hono, the extra property in the AuthContext contains the Hono Context object.

const customAuth = (ctx) => {
  const c = ctx.extra; // Hono Context
  const user = c.get("user");

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

Hono Adapter