Spiceflow is a lightweight, type-safe API framework for building web services using modern web standards. Read the source code on GitHub.

Features

• Type safe schema based validation via Zod
• Can easily generate OpenAPI spec based on your routes
• Native support for Fern to generate docs and SDKs (see example docs here)
• Support for Model Context Protocol to easily wire your app with LLMs
• Type safe RPC client generation
• Simple and intuitive API
• Uses web standards for requests and responses
• Supports async generators for streaming via server sent events
• Modular design with .use() for mounting sub-apps
• Base path support

Installation

npm install spiceflow zod

Basic Usage

Objects returned from route handlers are automatically serialized to JSON

Notice that Spiceflow also has legacy methods for .port, .get etc. that use a different API with positional arguments. Using .route is preferred

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow()
  .route({
    method: 'POST',
    path: '/hello',
    handler() {
      return 'Hello, World!'
    },
  })
  .route({
    method: 'POST',
    path: '/echo',
    async handler({ request }) {
      const body = await request.json()
      return { echo: body }
    },
  })

app.listen(3000)

Never declare app and add routes separately, that way you lose the type safety. Instead always append routes with .route in a single expression.

// This is an example of what NOT to do when using Spiceflow

import { Spiceflow } from 'spiceflow'

// DO NOT declare the app separately and add routes later
const app = new Spiceflow()

// Do NOT do this! Defining routes separately will lose type safety
app.route({
  method: 'GET',
  path: '/hello',
  handler() {
    return 'Hello, World!'
  },
})
// Do NOT do this! Adding routes separately like this will lose type safety
app.route({
  method: 'POST',
  path: '/echo',
  async handler({ request }) {
    const body = await request.json()
    return body
  },
})

Returning JSON

Spiceflow automatically serializes objects returned from handlers to JSON, so you don't need to wrap them in a Response object:

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/user',
    handler() {
      // Return object directly - no need for new Response()
      return { id: 1, name: 'John', email: 'john@example.com' }
    },
  })
  .route({
    method: 'POST',
    path: '/data',
    async handler({ request }) {
      const body = await request.json()
      // Objects are automatically serialized to JSON
      return {
        received: body,
        timestamp: new Date().toISOString(),
        processed: true,
      }
    },
  })

Type Safety for RPC

To maintain type safety when using the RPC client, it's recommended to throw Response objects for errors and return objects directly for success cases. This pattern ensures that the returned value types are properly inferred:

import { Spiceflow } from 'spiceflow'
import { z } from 'zod'

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/users/:id',
    params: z.object({
      id: z.string(),
    }),w
    response: z.object({
      id: z.string(),
      name: z.string(),
      email: z.string(),
    }),
    handler({ params }) {
      const user = getUserById(params.id)

      if (!user) {
        // Throw Response for errors to maintain type safety
        throw new Response('User not found', { status: 404 })
      }

      // Return object directly for success - type will be properly inferred
      return {
        id: user.id,
        name: user.name,
        email: user.email,
      }
    },
  })
  .route({
    method: 'POST',
    path: '/users',
    request: z.object({
      name: z.string(),
      email: z.string().email(),
    }),
    response: z.object({
      id: z.string(),
      name: z.string(),
      email: z.string(),
    }),
    async handler({ request }) {
      const body = await request.json()

      if (await userExists(body.email)) {
        // Throw Response for errors
        throw new Response('User already exists', { status: 409 })
      }

      const newUser = await createUser(body)

      // Return object directly - RPC client will have proper typing
      return {
        id: newUser.id,
        name: newUser.name,
        email: newUser.email,
      }
    },
  })

// RPC client usage with proper type inference
import { createSpiceflowClient } from 'spiceflow/client'

const client = createSpiceflowClient<typeof app>('http://localhost:3000')

async function example() {
  // TypeScript knows data is { id: string, name: string, email: string } | undefined
  const { data, error } = await client.users({ id: '123' }).get()

  if (error) {
    console.error('Error:', error) // Error handling
    return
  }

  // data is properly typed here
  console.log('User:', data.name, data.email)
}

With this pattern:

• Success responses: Return objects directly for automatic JSON serialization and proper type inference
• Error responses: Throw Response objects to maintain the error/success distinction in the RPC client
• Type safety: The RPC client will correctly infer the return type as the success object type

Comparisons

Elysia

This project was born as a fork of Elysia with several changes:

• Use Zod instead of Typebox
• Do not compile user code with aot and eval, Elysia is very difficult to contribue to because the app is generated by compiling the user routes with new Function(), which also causes several bugs
• Better async generator support by using SSE

Hono

This project shares many inspirations with Hono with many differences

• First class OpenAPI support, you don't need to change anything to produce an OpenAPI spec, just add the openapi plugin to automaitcally export your openapi schema on /openapi
• Much simpler framework, everything is done with native Request and Response objects instead of framework specific utilities
• Support for async generators
• Adding schemas to your routes is easier and does not require using validator functions, which slow down TypeScript inference
• The generated RPC client has much faster type inference, intellisense in VSCode appears in milliseconds instead of seconds
• Spiceflow uses whatwg Request and Response instead of custom utilities like c.text and c.req

Requests and Responses

POST Request with Body Schema

import { z } from 'zod'
import { Spiceflow } from 'spiceflow'

new Spiceflow().route({
  method: 'POST',
  path: '/users',
  request: z.object({
    name: z.string(),
    email: z.string().email(),
  }),
  async handler({ request }) {
    const body = await request.json() // here body has type { name: string, email: string }
    return `Created user: ${body.name}`
  },
})

Notice that to get the body of the request, you need to call request.json() to parse the body as JSON. Spiceflow does not parse the Body automatically, there is no body field in the Spiceflow route argument, instead you call either request.json() or request.formData() to get the body and validate it at the same time. This works by wrapping the request in a SpiceflowRequest instance, which has a json() and formData() method that parse the body and validate it. The returned data will have the correct schema type instead of any.

Response Schema

import { z } from 'zod'
import { Spiceflow } from 'spiceflow'

new Spiceflow().route({
  method: 'GET',
  path: '/users/:id',
  request: z.object({
    name: z.string(),
  }),
  response: z.object({
    id: z.number(),
    name: z.string(),
  }),
  params: z.object({
    id: z.string(),
  }),
  async handler({ request, params }) {
    const typedJson = await request.json() // this body will have the correct type
    return { id: Number(params.id), name: typedJson.name }
  },
})

Generate RPC Client

import { createSpiceflowClient } from 'spiceflow/client'
import { Spiceflow } from 'spiceflow'
import { z } from 'zod'

// Define the app with multiple routes and features
const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/hello/:id',
    handler({ params }) {
      return `Hello, ${params.id}!`
    },
  })
  .route({
    method: 'POST',
    path: '/users',
    async handler({ request }) {
      const body = await request.json() // here body has type { name?: string, email?: string }
      return `Created user: ${body.name}`
    },
    request: z.object({
      name: z.string().optional(),
      email: z.string().email().optional(),
    }),
  })
  .route({
    method: 'GET',
    path: '/stream',
    async *handler() {
      yield 'Start'
      await new Promise((resolve) => setTimeout(resolve, 1000))
      yield 'Middle'
      await new Promise((resolve) => setTimeout(resolve, 1000))
      yield 'End'
    },
  })

// Create the client
const client = createSpiceflowClient<typeof app>('http://localhost:3000')

// Example usage of the client
async function exampleUsage() {
  // GET request
  const { data: helloData, error: helloError } = await client
    .hello({ id: 'World' })
    .get()
  if (helloError) {
    console.error('Error fetching hello:', helloError)
  } else {
    console.log('Hello response:', helloData)
  }

  // POST request
  const { data: userData, error: userError } = await client.users.post({
    name: 'John Doe',
    email: 'john.doe@example.com',
  })
  if (userError) {
    console.error('Error creating user:', userError)
  } else {
    console.log('User creation response:', userData)
  }

  // Async generator (streaming) request
  const { data: streamData, error: streamError } = await client.stream.get()
  if (streamError) {
    console.error('Error fetching stream:', streamError)
  } else {
    for await (const chunk of streamData) {
      console.log('Stream chunk:', chunk)
    }
  }
}

Fetch Client (Recommended)

createSpiceflowFetch is the recommended way to interact with a Spiceflow app. It uses a familiar fetch(path, options) interface instead of the proxy-based chainable API of createSpiceflowClient. It provides the same type safety for paths, params, query, body, and responses, but with a simpler and more predictable API.

Export the app type from your server code:

// server.ts
import { Spiceflow } from 'spiceflow'
import { z } from 'zod'

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/hello',
    handler() {
      return 'Hello, World!'
    },
  })
  .route({
    method: 'POST',
    path: '/users',
    request: z.object({
      name: z.string(),
      email: z.string().email(),
    }),
    async handler({ request }) {
      const body = await request.json()
      return { id: '1', name: body.name, email: body.email }
    },
  })
  .route({
    method: 'GET',
    path: '/users/:id',
    handler({ params }) {
      return { id: params.id }
    },
  })
  .route({
    method: 'GET',
    path: '/search',
    query: z.object({ q: z.string(), page: z.coerce.number().optional() }),
    handler({ query }) {
      return { results: [], query: query.q, page: query.page }
    },
  })
  .route({
    method: 'GET',
    path: '/stream',
    async *handler() {
      yield 'Start'
      yield 'Middle'
      yield 'End'
    },
  })

export type App = typeof app

Then use the App type on the client side without importing server code:

// client.ts
import { createSpiceflowFetch } from 'spiceflow/client'
import type { App } from './server'

const f = createSpiceflowFetch<App>('http://localhost:3000')

// Returns Error | Data — check with instanceof Error
const greeting = await f('/hello')
if (greeting instanceof Error) return greeting // early return on error
console.log(greeting) // 'Hello, World!' — TypeScript knows the type

// POST with typed body
const user = await f('/users', {
  method: 'POST',
  body: { name: 'John', email: 'john@example.com' },
})
if (user instanceof Error) return user
console.log(user.id, user.name) // fully typed

// Path params — type-safe, required when path has :params
const foundUser = await f('/users/:id', {
  params: { id: '123' },
})
if (foundUser instanceof Error) return foundUser

// Query params — typed from route schema
const searchResults = await f('/search', {
  query: { q: 'hello', page: 1 },
})
if (searchResults instanceof Error) return searchResults

// Streaming — returns AsyncGenerator for async generator routes
const stream = await f('/stream')
if (stream instanceof Error) return stream
for await (const chunk of stream) {
  console.log(chunk) // 'Start', 'Middle', 'End'
}

The fetch client returns Error | Data directly following the errore convention — use instanceof Error to check for errors with Go-style early returns, then the happy path continues with the narrowed data type. No { data, error } destructuring, no null checks. On error, the returned SpiceflowFetchError has status, value (the parsed error body), and response (the raw Response object) properties.

The fetch client supports configuration options like headers, retries, onRequest/onResponse hooks, and custom fetch.

You can also pass a Spiceflow app instance directly for server-side usage without network requests:

const f = createSpiceflowFetch(app)
const greeting = await f('/hello')
if (greeting instanceof Error) throw greeting

Path Matching - Supported Features

• Named parameters: :param - Captures dynamic segments like /users/:id or /api/:version/users/:userId
• Wildcards: * - Matches any remaining path segments like /files/* or /proxy/*
• Catch-all routes: /* - Use as a not-found handler that catches any unmatched paths

Path Matching - Unsupported Features

• Optional parameters: /:param? - Use separate routes instead - IS NOT SUPPORTED
• Named wildcards: /files/*name - Use unnamed * only - IS NOT SUPPORTED
• Partial parameters: /:param-suffix or /prefix-:param - Use full segment parameters only - IS NOT SUPPORTED
• Regex patterns: /users/(\\d+) - Use string parameters with validation in handlers - IS NOT SUPPORTED
• Multiple wildcards: /*/files/* - Use single wildcard only - IS NOT SUPPORTED

Not Found Handler

Use /* as a catch-all route to handle 404 errors. More specific routes always take precedence regardless of registration order:

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/users',
    handler() {
      return { users: [] }
    },
  })
  .route({
    method: 'GET',
    path: '/users/:id',
    handler({ params }) {
      return { id: params.id }
    },
  })
  // Catch-all for unmatched GET requests
  .route({
    method: 'GET',
    path: '/*',
    handler() {
      return new Response('Page not found', { status: 404 })
    },
  })
  // Or use .all() to catch any method
  .route({
    method: '*',
    path: '/*',
    handler({ request }) {
      return new Response(`Cannot ${request.method} ${request.url}`, {
        status: 404,
      })
    },
  })

// Specific routes work as expected
// GET /users returns { users: [] }
// GET /users/123 returns { id: '123' }
// GET /unknown returns 'Page not found' with 404 status

Storing Spiceflow in Class Instances

If you need to store a Spiceflow router as a property in a class instance, use the AnySpiceflow type:

Important: Do not use this inside route handlers to reference the parent class. The this context inside handlers always refers to the Spiceflow instance, not your class instance. Instead, capture the parent class reference in a variable outside the handlers:

import { Spiceflow, AnySpiceflow } from 'spiceflow'

export class ChatDurableObject {
  private router: AnySpiceflow
  private state: DurableObjectState

  constructor(state: DurableObjectState, env: Env) {
    this.state = state
    const self = this // Capture parent class reference - IMPORTANT!

    this.router = new Spiceflow()
      .route({
        method: 'GET',
        path: '/messages',
        async handler() {
          // Use 'self' instead of 'this' to access parent class
          // this.state would NOT work here - 'this' refers to Spiceflow instance
          const messages = (await self.state.storage.get('messages')) || []
          return { messages }
        },
      })
      .route({
        method: 'POST',
        path: '/messages',
        async handler({ request }) {
          const { message } = await request.json()
          // Use 'self' to access parent class properties
          const messages = (await self.state.storage.get('messages')) || []
          messages.push({ id: Date.now(), text: message })
          await self.state.storage.put('messages', messages)
          return { success: true }
        },
      })
  }

  fetch(request: Request) {
    return this.router.handle(request)
  }
}

Safe Path Building

The safePath method provides a type-safe way to build URLs with parameters. It helps prevent runtime errors by ensuring all required parameters are provided and properly substituted into the path.

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/users/:id',
    handler({ params }) {
      return { id: params.id }
    },
  })
  .route({
    method: 'GET',
    path: '/users/:id/posts/:postId',
    handler({ params }) {
      return { userId: params.id, postId: params.postId }
    },
  })

// Building URLs with required parameters
const userPath = app.safePath('/users/:id', { id: '123' })
// Result: '/users/123'

// Building URLs with required parameters
const userPostPath = app.safePath('/users/:id/posts/:postId', {
  id: '456',
  postId: 'abc',
})
// Result: '/users/456/posts/abc'

Query Parameters

When a route has a query schema, safePath accepts query parameters alongside path parameters in the same flat object. Query parameters are appended as a query string, and unknown keys are rejected at the type level:

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/search',
    query: z.object({ q: z.string(), page: z.coerce.number() }),
    handler({ query }) {
      return { results: [], q: query.q }
    },
  })
  .route({
    method: 'GET',
    path: '/users/:id',
    query: z.object({ fields: z.string() }),
    handler({ params, query }) {
      return { id: params.id, fields: query.fields }
    },
  })

app.safePath('/search', { q: 'hello', page: 1 })
// Result: '/search?q=hello&page=1'

app.safePath('/users/:id', { id: '42', fields: 'name' })
// Result: '/users/42?fields=name'

// @ts-expect-error - 'invalid' is not a known query key
app.safePath('/search', { invalid: 'x' })

Standalone createSafePath

If you need a path builder on the client side where you can't import server app code, use createSafePath with the typeof app generic:

import { createSafePath } from 'spiceflow'
import type { App } from './server' // import only the type, not the runtime app

const safePath = createSafePath<App>()

safePath('/users/:id', { id: '123' })
// Result: '/users/123'

safePath('/search', { q: 'hello', page: 1 })
// Result: '/search?q=hello&page=1'

The returned function has the same type safety as app.safePath — it infers paths, params, and query schemas from the app type. The app argument is optional and not used at runtime, so you can call createSafePath<App>() without passing any value.

OAuth Callback Example

The safePath method is particularly useful when building callback URLs for OAuth flows, where you need to construct URLs dynamically based on user data or session information:

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/auth/callback/:provider/:userId',
    handler({ params, query }) {
      const { provider, userId } = params
      const { code, state } = query

      // Handle OAuth callback logic here
      return {
        provider,
        userId,
        authCode: code,
        state,
      }
    },
  })
  .route({
    method: 'POST',
    path: '/auth/login',
    handler({ request }) {
      const userId = '12345'
      const provider = 'google'

      // Build the OAuth callback URL safely
      const callbackUrl = new URL(
        app.safePath('/auth/callback/:provider/:userId', {
          provider,
          userId,
        }),
        'https://myapp.com',
      ).toString()

      // Redirect to OAuth provider with callback URL
      const oauthUrl =
        `https://accounts.google.com/oauth/authorize?` +
        `client_id=your-client-id&` +
        `redirect_uri=${encodeURIComponent(callbackUrl)}&` +
        `response_type=code&` +
        `scope=openid%20profile%20email`

      return { redirectUrl: oauthUrl }
    },
  })

In this example:

• The callback URL is built safely using safePath with type checking
• Required parameters like provider and userId must be provided
• The resulting URL is guaranteed to be properly formatted

Mounting Sub-Apps

import { Spiceflow } from 'spiceflow'
import { z } from 'zod'

const mainApp = new Spiceflow()
  .route({
    method: 'POST',
    path: '/users',
    async handler({ request }) {
      return `Created user: ${(await request.json()).name}`
    },
    request: z.object({
      name: z.string(),
    }),
  })
  .use(
    new Spiceflow().route({
      method: 'GET',
      path: '/',
      handler() {
        return 'Users list'
      },
    }),
  )

Base Path

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow({ basePath: '/api/v1' })
app.route({
  method: 'GET',
  path: '/hello',
  handler() {
    return 'Hello'
  },
}) // Accessible at /api/v1/hello

Async Generators (Streaming)

Async generators will create a server sent event response.

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow().route({
  method: 'GET',
  path: '/sseStream',
  async *handler() {
    yield { message: 'Start' }
    await new Promise((resolve) => setTimeout(resolve, 1000))
    yield { message: 'Middle' }
    await new Promise((resolve) => setTimeout(resolve, 1000))
    yield { message: 'End' }
  },
})

// Server-Sent Events (SSE) format
// The server will send events in the following format:
// data: {"message":"Start"}
// data: {"message":"Middle"}
// data: {"message":"End"}

// Example response output:
// data: {"message":"Start"}
// data: {"message":"Middle"}
// data: {"message":"End"}

// Client usage example with RPC client
import { createSpiceflowClient } from 'spiceflow/client'

const client = createSpiceflowClient<typeof app>('http://localhost:3000')

async function fetchStream() {
  const response = await client.sseStream.get()
  if (response.error) {
    console.error('Error fetching stream:', response.error)
  } else {
    for await (const chunk of response.data) {
      console.log('Stream chunk:', chunk)
    }
  }
}

fetchStream()

Error Handling

import { Spiceflow } from 'spiceflow'

new Spiceflow().onError(({ error }) => {
  console.error(error)
  return new Response('An error occurred', { status: 500 })
})

Middleware

import { Spiceflow } from 'spiceflow'

new Spiceflow().use(({ request }) => {
  console.log(`Received ${request.method} request to ${request.url}`)
})

How errors are handled in Spiceflow client

The Spiceflow client provides type-safe error handling by returning either a data or error property. When using the client:

• Thrown errors appear in the error field
• Response objects can be thrown or returned
• Responses with status codes 200-299 appear in the data field
• Responses with status codes < 200 or ≥ 300 appear in the error field

The example below demonstrates handling different types of responses:

import { Spiceflow } from 'spiceflow'
import { createSpiceflowClient } from 'spiceflow/client'

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/error',
    handler() {
      throw new Error('Something went wrong')
    },
  })
  .route({
    method: 'GET',
    path: '/unauthorized',
    handler() {
      return new Response('Unauthorized access', { status: 401 })
    },
  })
  .route({
    method: 'GET',
    path: '/success',
    handler() {
      throw new Response('Success message', { status: 200 })
      return ''
    },
  })

const client = createSpiceflowClient<typeof app>('http://localhost:3000')

async function handleErrors() {
  const errorResponse = await client.error.get()
  console.log('Calling error endpoint...')
  // Logs: Error occurred: Something went wrong
  if (errorResponse.error) {
    console.error('Error occurred:', errorResponse.error)
  }

  const unauthorizedResponse = await client.unauthorized.get()
  console.log('Calling unauthorized endpoint...')
  // Logs: Unauthorized: Unauthorized access (Status: 401)
  if (unauthorizedResponse.error) {
    console.error('Unauthorized:', unauthorizedResponse.error)
  }

  const successResponse = await client.success.get()
  console.log('Calling success endpoint...')
  // Logs: Success: Success message
  if (successResponse.data) {
    console.log('Success:', successResponse.data)
  }
}

Using the client server side, without network requests

When using the client server-side, you can pass the Spiceflow app instance directly to createSpiceflowClient() instead of providing a URL. This allows you to make "virtual" requests that are handled directly by the app without making actual network requests. This is useful for testing, generating documentation, or any other scenario where you want to interact with your API endpoints programmatically without setting up a server.

Here's an example:

import { Spiceflow } from 'spiceflow'
import { createSpiceflowClient } from 'spiceflow/client'
import { openapi } from 'spiceflow/openapi'
import { writeFile } from 'node:fs/promises'

const app = new Spiceflow()
  .use(openapi({ path: '/openapi' }))
  .route({
    method: 'GET',
    path: '/users',
    handler() {
      return [
        { id: 1, name: 'John' },
        { id: 2, name: 'Jane' },
      ]
    },
  })
  .route({
    method: 'POST',
    path: '/users',
    handler({ request }) {
      return request.json()
    },
  })

// Create client by passing app instance directly
const client = createSpiceflowClient(app)

// Get OpenAPI schema and write to disk
const { data } = await client.openapi.get()
await writeFile('openapi.json', JSON.stringify(data, null, 2))
console.log('OpenAPI schema saved to openapi.json')

Modifying Response with Middleware

Middleware in Spiceflow can be used to modify the response before it's sent to the client. This is useful for adding headers, transforming the response body, or performing any other operations on the response.

Here's an example of how to modify the response using middleware:

import { Spiceflow } from 'spiceflow'

new Spiceflow()
  .use(async ({ request }, next) => {
    const response = await next()
    if (response) {
      // Add a custom header to all responses
      response.headers.set('X-Powered-By', 'Spiceflow')
    }
    return response
  })
  .route({
    method: 'GET',
    path: '/example',
    handler() {
      return { message: 'Hello, World!' }
    },
  })

Generating OpenAPI Schema

import { openapi } from 'spiceflow/openapi'
import { Spiceflow } from 'spiceflow'
import { z } from 'zod'

const app = new Spiceflow()
  .use(openapi({ path: '/openapi.json' }))
  .route({
    method: 'GET',
    path: '/hello',
    handler() {
      return 'Hello, World!'
    },
    query: z.object({
      name: z.string(),
      age: z.number(),
    }),
    response: z.string(),
  })
  .route({
    method: 'POST',
    path: '/user',
    handler() {
      return new Response('Hello, World!')
    },
    request: z.object({
      name: z.string(),
      email: z.string().email(),
    }),
  })

const openapiSchema = await (
  await app.handle(new Request('http://localhost:3000/openapi.json'))
).json()

Adding CORS Headers

import { cors } from 'spiceflow/cors'
import { Spiceflow } from 'spiceflow'

const app = new Spiceflow().use(cors()).route({
  method: 'GET',
  path: '/hello',
  handler() {
    return 'Hello, World!'
  },
})

Proxy requests

import { Spiceflow } from 'spiceflow'
import { MiddlewareHandler } from 'spiceflow/dist/types'

const app = new Spiceflow()

function createProxyMiddleware({
  target,
  changeOrigin = false,
}): MiddlewareHandler {
  return async ({ request }) => {
    const url = new URL(request.url)

    const proxyReq = new Request(
      new URL(url.pathname + url.search, target),
      request,
    )

    if (changeOrigin) {
      proxyReq.headers.set('origin', new URL(target).origin || '')
    }
    console.log('proxying', proxyReq.url)
    const res = await fetch(proxyReq)

    return res
  }
}

app.use(
  createProxyMiddleware({
    target: 'https://api.openai.com',
    changeOrigin: true,
  }),
)

// or with a basePath
app.use(
  new Spiceflow({ basePath: '/v1/completions' }).use(
    createProxyMiddleware({
      target: 'https://api.openai.com',
      changeOrigin: true,
    }),
  ),
)

app.listen(3030)

Authorization Middleware

You can handle authorization in a middleware, for example here the code checks if the user is logged in and if not, it throws an error. You can use the state to track request data, in this case the state keeps a reference to the session.

import { z } from 'zod'
import { Spiceflow } from 'spiceflow'

new Spiceflow()
  .state('session', null as Session | null)
  .use(async ({ request: req, state }, next) => {
    const res = new Response()

    const { session } = await getSession({ req, res })
    if (!session) {
      return
    }
    state.session = session
    const response = await next()

    const cookies = res.headers.getSetCookie()
    for (const cookie of cookies) {
      response.headers.append('Set-Cookie', cookie)
    }

    return response
  })
  .route({
    method: 'POST',
    path: '/protected',
    async handler({ state }) {
      const { session } = state
      if (!session) {
        throw new Error('Not logged in')
      }
      return { ok: true }
    },
  })

Non blocking authentication middleware

Sometimes authentication is only required for specific routes, and you don't want to block public routes while waiting for authentication. You can use Promise.withResolvers() to start fetching user data in parallel, allowing public routes to respond immediately while protected routes wait for authentication to complete.

The example below demonstrates this pattern - the /public route responds instantly while /protected waits for authentication:

import { Spiceflow } from 'spiceflow'

new Spiceflow()
  .state('userId', Promise.resolve(''))
  .state('userEmail', Promise.resolve(''))
  .use(async ({ request, state }, next) => {
    const sessionKey = request.headers.get('sessionKey')
    const userIdPromise = Promise.withResolvers<string>()
    const userEmailPromise = Promise.withResolvers<string>()

    state.userId = userIdPromise.promise
    state.userEmail = userEmailPromise.promise

    async function resolveUser() {
      if (!sessionKey) {
        userIdPromise.resolve('')
        userEmailPromise.resolve('')
        return
      }
      const user = await getUser(sessionKey)
      userIdPromise.resolve(user?.id ?? '')
      userEmailPromise.resolve(user?.email ?? '')
    }

    resolveUser()
  })
  .route({
    method: 'GET',
    path: '/protected',
    async handler({ state }) {
      const userId = await state.userId
      if (!userId) throw new Error('Not authenticated')
      return { message: 'Protected data' }
    },
  })
  .route({
    method: 'GET',
    path: '/public',
    handler() {
      return { message: 'Public data' }
    },
  })

async function getUser(sessionKey: string) {
  await new Promise((resolve) => setTimeout(resolve, 100))
  return sessionKey === 'valid'
    ? { id: '123', email: 'user@example.com' }
    : null
}

Model Context Protocol (MCP)

Spiceflow includes a Model Context Protocol (MCP) plugin that exposes your API routes as tools and resources that can be used by AI language models like Claude. The MCP plugin makes it easy to let AI assistants interact with your API endpoints in a controlled way.

When you mount the MCP plugin (default path is /mcp), it automatically:

• Exposes all your routes as callable tools with proper input validation
• Exposes GET routes without query/path parameters as resources
• Provides an SSE-based transport for real-time communication
• Handles serialization of requests and responses

This makes it simple to let AI models like Claude discover and call your API endpoints programmatically.

Basic MCP Usage

Here's an example:

// Import the MCP plugin and client
import { mcp } from 'spiceflow/mcp'
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'
import { Spiceflow } from 'spiceflow'
import {
  ListToolsResultSchema,
  CallToolResultSchema,
  ListResourcesResultSchema,
} from '@modelcontextprotocol/sdk/types.js'

// Create a new app with some example routes
const app = new Spiceflow()
  // Mount the MCP plugin at /mcp (default path)
  .use(mcp())
  // These routes will be available as tools
  .route({
    method: 'GET',
    path: '/hello',
    handler() {
      return 'Hello World'
    },
  })
  .route({
    method: 'GET',
    path: '/users/:id',
    handler({ params }) {
      return { id: params.id }
    },
  })
  .route({
    method: 'POST',
    path: '/echo',
    async handler({ request }) {
      const body = await request.json()
      return body
    },
  })

// Start the server
app.listen(3000)

// Example client usage:
const transport = new SSEClientTransport(new URL('http://localhost:3000/mcp'))

const client = new Client(
  { name: 'example-client', version: '1.0.0' },
  { capabilities: {} },
)

await client.connect(transport)

// List available tools
const tools = await client.request(
  { method: 'tools/list' },
  ListToolsResultSchema,
)

// Call a tool
const result = await client.request(
  {
    method: 'tools/call',
    params: {
      name: 'GET /hello',
      arguments: {},
    },
  },
  CallToolResultSchema,
)

// List available resources (only GET /hello is exposed since it has no params)
const resources = await client.request(
  { method: 'resources/list' },
  ListResourcesResultSchema,
)

Adding MCP Tools to Existing Server

If you already have an existing MCP server and want to add Spiceflow route tools to it, you can use the addMcpTools helper function:

import { addMcpTools } from 'spiceflow/mcp'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'

import { Spiceflow } from 'spiceflow'

// Your existing MCP server
const existingServer = new Server(
  { name: 'my-server', version: '1.0.0' },
  { capabilities: { tools: {}, resources: {} } },
)

// Your Spiceflow app
const app = new Spiceflow()
  .use(mcp()) // Required for MCP configuration
  .route({
    method: 'GET',
    path: '/hello',
    handler() {
      return 'Hello from Spiceflow!'
    },
  })

// Add Spiceflow tools to your existing server
const mcpServer = await addMcpTools({
  mcpServer: existingServer,
  app,
  ignorePaths: ['/mcp', '/sse'],
})

// Now your existing server has access to all Spiceflow routes as tools

Generating Fern docs and SDK

Spiceflow has native support for Fern docs and SDK generation using openapi plugin.

The openapi types also have additional types for x-fern extensions to help you customize your docs and SDK.

Here is an example script to help you generate an openapi.yml file that you can then use with Fern:

import fs from 'fs'
import path from 'path'
import yaml from 'js-yaml'
import { Spiceflow } from 'spiceflow'
import { openapi } from 'spiceflow/openapi'
import { createSpiceflowClient } from 'spiceflow/client'

const app = new Spiceflow().use(openapi({ path: '/openapi' })).route({
  method: 'GET',
  path: '/hello',
  handler() {
    return 'Hello World'
  },
})

async function main() {
  console.log('Creating Spiceflow client...')
  const client = createSpiceflowClient(app)

  console.log('Fetching OpenAPI spec...')
  const { data: openapiJson, error } = await client.openapi.get()
  if (error) {
    console.error('Failed to fetch OpenAPI spec:', error)
    throw error
  }

  const outputPath = path.resolve('./openapi.yml')
  console.log('Writing OpenAPI spec to', outputPath)
  fs.writeFileSync(
    outputPath,
    yaml.dump(openapiJson, {
      indent: 2,
      lineWidth: -1,
    }),
  )
  console.log('Successfully wrote OpenAPI spec')
}

main().catch((e) => {
  console.error('Failed to generate OpenAPI spec:', e)
  process.exit(1)
})

Then follow Fern docs to generate the SDK and docs. You will need to create some Fern yml config files.

You can take a look at the scripts/example-app.ts file for an example app that generates the docs and SDK.

Passing state during handle, passing Cloudflare env bindings

You can use bindings type safely using a .state method and then passing the state in the handle method in the second argument:

import { Spiceflow } from 'spiceflow'
import { z } from 'zod'

interface Env {
  KV: KVNamespace
  QUEUE: Queue
  SECRET: string
}

const app = new Spiceflow()
  .state('env', {} as Env)
  .route({
    method: 'GET',
    path: '/kv/:key',
    async handler({ params, state }) {
      const value = await state.env!.KV.get(params.key)
      return { key: params.key, value }
    },
  })
  .route({
    method: 'POST',
    path: '/queue',
    async handler({ request, state }) {
      const body = await request.json()
      await state.env!.QUEUE.send(body)
      return { success: true, message: 'Added to queue' }
    },
  })

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // Pass the env bindings to the app
    return app.handle(request, { state: { env } })
  },
}

Fern SDK streaming support

When you use an async generator in your app, Spiceflow will automatically add the required x-fern extensions to the OpenAPI spec to support streaming.

Here is what streaming looks like in the Fern generated SDK:

import { ExampleSdkClient } from './sdk-typescript'

const sdk = new ExampleSdkClient({
  environment: 'http://localhost:3000',
})

// Get stream data
const stream = await sdk.getStream()
for await (const data of stream) {
  console.log('Stream data:', data)
}

// Simple GET request
const response = await sdk.getUsers()
console.log('Users:', response)

Working with Cookies

Spiceflow works with standard Request and Response objects, so you can use any cookie library like the cookie npm package to handle cookies:

import { Spiceflow } from 'spiceflow'
import { parse, serialize } from 'cookie'

const app = new Spiceflow()
  .route({
    method: 'GET',
    path: '/set-cookie',
    handler({ request }) {
      // Read existing cookies from the request
      const cookies = parse(request.headers.get('Cookie') || '')

      // Create response with a new cookie
      const response = new Response(
        JSON.stringify({
          message: 'Cookie set!',
          existingCookies: cookies,
        }),
        {
          headers: {
            'Content-Type': 'application/json',
          },
        },
      )

      // Set a new cookie
      response.headers.set(
        'Set-Cookie',
        serialize('session', 'abc123', {
          httpOnly: true,
          secure: true,
          sameSite: 'strict',
          maxAge: 60 * 60 * 24 * 7, // 7 days
          path: '/',
        }),
      )

      return response
    },
  })
  .route({
    method: 'GET',
    path: '/get-cookie',
    handler({ request }) {
      // Parse cookies from the request
      const cookies = parse(request.headers.get('Cookie') || '')

      return {
        sessionId: cookies.session || null,
        allCookies: cookies,
      }
    },
  })
  .route({
    method: 'POST',
    path: '/clear-cookie',
    handler({ request }) {
      const response = new Response(
        JSON.stringify({ message: 'Cookie cleared!' }),
        {
          headers: {
            'Content-Type': 'application/json',
          },
        },
      )

      // Clear a cookie by setting it with an expired date
      response.headers.set(
        'Set-Cookie',
        serialize('session', '', {
          httpOnly: true,
          secure: true,
          sameSite: 'strict',
          expires: new Date(0),
          path: '/',
        }),
      )

      return response
    },
  })

app.listen(3000)

You can also use cookies in middleware for authentication or session handling:

import { Spiceflow } from 'spiceflow'
import { parse, serialize } from 'cookie'

const app = new Spiceflow()
  .state('userId', null as string | null)
  .use(async ({ request, state }, next) => {
    // Parse cookies from incoming request
    const cookies = parse(request.headers.get('Cookie') || '')

    // Extract user ID from session cookie
    if (cookies.session) {
      // In a real app, you'd verify the session token
      state.userId = cookies.session
    }

    const response = await next()

    // Optionally refresh the session cookie
    if (state.userId && response) {
      response.headers.set(
        'Set-Cookie',
        serialize('session', state.userId, {
          httpOnly: true,
          secure: true,
          sameSite: 'strict',
          maxAge: 60 * 60 * 24, // 24 hours
          path: '/',
        }),
      )
    }

    return response
  })
  .route({
    method: 'GET',
    path: '/profile',
    handler({ state }) {
      if (!state.userId) {
        return new Response('Unauthorized', { status: 401 })
      }

      return { userId: state.userId, message: 'Welcome back!' }
    },
  })

Background tasks with waitUntil

Spiceflow provides a waitUntil function in the handler context that allows you to schedule tasks in the background in a cross platform way. It will use the Cloudflare workers waitUntil if present. It's currently a no op in Node.js.

Basic Usage

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow().route({
  method: 'POST',
  path: '/process',
  async handler({ request, waitUntil }) {
    const data = await request.json()

    // Schedule background task
    waitUntil(
      fetch('https://analytics.example.com/track', {
        method: 'POST',
        body: JSON.stringify({ event: 'data_processed', data }),
      }),
    )

    // Return response immediately
    return { success: true, id: Math.random().toString(36) }
  },
})

Cloudflare Workers Integration

In Cloudflare Workers, waitUntil is automatically detected from the global context:

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow().route({
  method: 'POST',
  path: '/webhook',
  async handler({ request, waitUntil }) {
    const payload = await request.json()

    // Process webhook data in background
    waitUntil(
      processWebhookData(payload)
        .then(() => console.log('Webhook processed'))
        .catch((err) => console.error('Webhook processing failed:', err)),
    )

    // Respond immediately to webhook sender
    return new Response('OK', { status: 200 })
  },
})

async function processWebhookData(payload: any) {
  // Simulate time-consuming processing
  await new Promise((resolve) => setTimeout(resolve, 1000))
  // Save to database, send notifications, etc.
}

export default {
  fetch(request: Request, env: any, ctx: ExecutionContext) {
    return app.handle(request, { state: { env } })
  },
}

Next.js pages router integration

// pages/api/[...path].ts
import { getJwt } from '@app/utils/ssr' // exasmple session function
import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  // IMPORTANT! nothing should be run before calling handleNode that could read the request body!
  await mcpAuthApp.handleNode(req, res)
}

export const config = {
  api: {
    bodyParser: false,
  },
}

Custom waitUntil Function

You can also provide your own waitUntil implementation:

import { Spiceflow } from 'spiceflow'

const app = new Spiceflow({
  waitUntil: (promise) => {
    // Custom implementation for non-Cloudflare environments
    promise.catch((err) => console.error('Background task failed:', err))
  },
}).route({
  method: 'GET',
  path: '/analytics',
  async handler({ waitUntil }) {
    // Schedule analytics tracking
    waitUntil(trackPageView('/analytics'))

    return { message: 'Analytics page loaded' }
  },
})

async function trackPageView(path: string) {
  // Track page view in analytics system
  console.log(`Page view tracked: ${path}`)
}

Note: In non-Cloudflare environments, if no custom waitUntil function is provided, the default implementation is a no-op function that doesn't wait for the promises to complete.

Graceful Shutdown

The preventProcessExitIfBusy middleware prevents platforms like Fly.io from killing your app while processing long requests (e.g., AI payloads). Fly.io can wait up to 5 minutes for graceful shutdown.

import { Spiceflow, preventProcessExitIfBusy } from 'spiceflow'

const app = new Spiceflow()
  .use(
    preventProcessExitIfBusy({
      maxWaitSeconds: 300, // 5 minutes max wait (default: 300)
      checkIntervalMs: 250, // Check interval (default: 250ms)
    }),
  )
  .route({
    method: 'POST',
    path: '/ai/generate',
    async handler({ request }) {
      const prompt = await request.json()
      // Long-running AI generation
      const result = await generateAIResponse(prompt)
      return result
    },
  })

app.listen(3000)

When receiving SIGTERM during deployment, the middleware waits for all active requests to complete before exiting. Perfect for AI workloads that may take minutes to process.

When using createSpiceflowClient and getting typescript error The inferred type of 'pluginApiClient' cannot be named without a reference to '...'. This is likely not portable. A type annotation is necessary. (ts 2742)

You can resolve this issue by adding an explicing type for the client:

export const client: SpiceflowClient.Create<App> = createSpiceflowClient<App>(
  PUBLIC_URL,
  {},
)