Spiceflow

1.18.0 verified Mon Apr 27 auth: no javascript

Spiceflow is a TypeScript-first API framework for building type-safe RPC web applications. Version 1.18.0 is the current stable release. It provides a simple, composable API for defining routes, middleware, and error handling with full end-to-end type safety via inferred request and response schemas. Key differentiators include automatic OpenTelemetry integration, server timing headers, type-safe form data parsing, and support for Cloudflare Workers, Vercel, and Node.js environments. It is compatible with the Model Context Protocol SDK and ships its own TypeScript definitions. Release cadence is frequent, with multiple pre-release versions.

Common errors

error require is not defined ↓

cause Using CommonJS require() in an ESM-only package (e.g., Cloudflare Workers).

fix

Replace require() with import statements. For Cloudflare Workers, ensure your build process outputs ESM.

error TypeError: Cannot destructure property 'Spiceflow' of ... ↓

cause Default import used instead of named import.

fix

Change 'import Spiceflow from "spiceflow"' to 'import { Spiceflow } from "spiceflow"'.

error Module not found: Can't resolve 'spiceflow' in ... ↓

cause Missing dependency or incorrect import path when using subpath exports that don't exist.

fix

Install spiceflow: 'npm install spiceflow'. Ensure you import from 'spiceflow' not 'spiceflow/subpath' unless the subpath is documented.

Warnings

breaking Spiceflow v1.19.0-rsc.x is a pre-release and may contain breaking changes compared to v1.18.0 stable. ↓

fix Pin to v1.18.0 for production stability until v1.19.0 is released as stable.

gotcha On Cloudflare Workers, using require() will throw 'require is not defined'. This was fixed in v1.19.0-rsc.7. ↓

fix Update to v1.19.0-rsc.7 or later, or avoid using require() in worker environments.

gotcha The json() helper throws a schema validation error if the returned data does not match the route's inferred response schema. ↓

fix Ensure all routes using json() return data that matches the response schema, or handle validation errors.

deprecated Using Spiceflow without registering the app type via SpiceflowRegister will cause Link and other typed helpers to fall back to string parameters. ↓

fix Register the app type with SpiceflowRegister to enable full type safety on client helpers.

Install

npm install spiceflow

yarn add spiceflow

pnpm add spiceflow

Imports

Spiceflow
wrong
```
import Spiceflow from 'spiceflow'
```
correct
```
import { Spiceflow } from 'spiceflow'
```
Spiceflow is a named export, not a default export. Always use named import syntax.
json
wrong
```
import { json } from 'spiceflow/json'
```
correct
```
import { json } from 'spiceflow'
```
The json helper is exported from the main package, not a subpath.

parseFormData

wrong

const { parseFormData } = require('spiceflow')

correct

import { parseFormData } from 'spiceflow'

Spiceflow is ESM-only; using require() will fail. Use import instead.

Quickstart

Shows how to create a basic Spiceflow app with two routes, using the json helper for typed responses and Zod for optional schema validation.

import { Spiceflow, json } from 'spiceflow';
import { z } from 'zod';

const app = new Spiceflow()
  .get('/hello', () => {
    return json({ message: 'Hello, world!' })
  })
  .post('/echo', async ({ request }) => {
    const body = await request.json();
    return json(body, { status: 201 });
  });

// Start the server (assumes Node.js or Bun)
app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});