Cloudflare Workers Adapter

The Cloudflare Workers adapter allows you to integrate Stepflow into your Cloudflare Workers.

Installation

pnpm add @stepflowjs/adapter-cloudflare

Usage

The adapter provides a createStepflowHandler function that returns a standard Cloudflare Workers fetch handler.

import { Stepflow } from "@stepflowjs/core";
import { createStepflowHandler } from "@stepflowjs/adapter-cloudflare";

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

// Create Stepflow handler
const stepflowHandler = createStepflowHandler(stepflow, {
  basePath: "/api/stepflow",
});

export default {
  async fetch(request: Request, env: any, ctx: any): Promise<Response> {
    // Route Stepflow requests to the adapter
    const response = await stepflowHandler(request);

    if (response.status !== 404) {
      return response;
    }

    // Handle other routes
    return new Response("Not found", { status: 404 });
  },
};

Configuration

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

Authorization Example

import {
  createStepflowHandler,
  createApiKeyAuth,
} from "@stepflowjs/adapter-cloudflare";

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

Cloudflare-specific Context

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

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

When running on Cloudflare Workers, it is highly recommended to use a persistent storage adapter like @stepflowjs/storage-postgres (via Neon or similar) or a custom adapter for Cloudflare D1/KV, as the default memory storage will not persist across worker invocations.