Stepflow Documentation

The Nitric adapter allows you to integrate Stepflow into your Nitric applications.

Installation

pnpm add @stepflowjs/adapter-nitric

Usage

The adapter provides a createStepflowRouter function that returns a combined Nitric HTTP handler.

import { api } from "@nitric/sdk";
import { Stepflow } from "@stepflowjs/core";
import { createStepflowRouter } from "@stepflowjs/adapter-nitric";

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

// Create Stepflow router
const stepflowRouter = createStepflowRouter(stepflow, {
  basePath: "/stepflow",
});

const mainApi = api("main");

// Route all Stepflow requests to the adapter
mainApi.all("/stepflow/*", stepflowRouter);

Individual Handlers

If you prefer more control, you can use createStepflowHandlers to get individual handlers for each route.

import { api } from "@nitric/sdk";
import { createStepflowHandlers } from "@stepflowjs/adapter-nitric";

const { triggerHandler, runHandler, healthHandler } =
  createStepflowHandlers(stepflow);

const mainApi = api("main");

mainApi.post("/stepflow/trigger/:workflowId", triggerHandler);
mainApi.get("/stepflow/runs/:runId", runHandler);
mainApi.get("/stepflow/health", healthHandler);

Configuration

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

Authorization Example

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

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

Nitric-specific Context

When writing custom auth handlers for Nitric, the extra property in the AuthContext contains the Nitric HttpContext object.

const customAuth = async (ctx) => {
  const nitricCtx = ctx.extra; // Nitric HttpContext
  // Perform custom auth logic
  return { ok: true };
};

Note: True SSE streaming requires specific infrastructure support. In some Nitric environments, the streamHandler may return the current state as a single event rather than a persistent stream. For production real-time updates, consider using Nitric's Websocket or Pub/Sub features.

Nitric Adapter