spiceflow

type safe API and React Server Components framework for Node, Bun, and Cloudflare



Spiceflow is a type-safe API framework and full-stack React RSC framework focused on absolute simplicity. It works across all JavaScript runtimes: Node.js, Bun, and Cloudflare Workers. Read the source code on [GitHub](https://github.com/remorses/spiceflow). ## Features - Full-stack React framework with React Server Components (RSC), server actions, layouts, and automatic client code splitting - Works everywhere: Node.js, Bun, and Cloudflare Workers with the same code - Type safe schema based validation via Zod - Type safe fetch client with full inference on path params, query, body, and response - Simple and intuitive API using web standard Request and Response - Can easily generate OpenAPI spec based on your routes - Support for [Model Context Protocol](https://modelcontextprotocol.io/) to easily wire your app with LLMs - Supports async generators for streaming via server sent events - Modular design with `.use()` for mounting sub-apps - Built-in [OpenTelemetry](https://opentelemetry.io/) tracing with zero overhead when disabled ## Installation ```bash npm install spiceflow@rsc ``` ## AI Agents To let your AI coding agent know how to use spiceflow, run: ```bash npx -y skills add remorses/spiceflow ``` ## Basic Usage API routes return JSON automatically. React pages use `.page()` and `.layout()` for server-rendered UI with client interactivity: ```tsx import { Spiceflow } from 'spiceflow' import { Counter } from './counter' const app = new Spiceflow() .get('/api/hello', () => { return { message: 'Hello, World!' } }) .layout('/*', async ({ children }) => { return ( {children} ) }) .page('/', async () => { return (

Home

) }) .page('/about', async () => { return

About

}) app.listen(3000) ``` Always define a root `.layout('/*', ...)` and put the document shell with ``, ``, and `` there. More specific layouts should not render another shell - they should only return shared parent UI like sidebars, nav, wrappers, or section chrome. If a nested layout also renders ``, the shell repeats and you end up nesting full HTML documents inside each other. Only add scoped layouts when many pages share the same parent components. Wildcard layouts also match their base path, so `/app/*` wraps both `/app` and `/app/settings`, and `/docs/*` wraps both `/docs` and `/docs/getting-started`. ```tsx const app = new Spiceflow() .layout('/*', async ({ children }) => { return ( {children} ) }) .layout('/app/*', async ({ children }) => { return
{children}
}) .layout('/docs/*', async ({ children }) => { return
{children}
}) .page('/app', async () => { return

App home

}) .page('/app/settings', async () => { return

App settings

}) .page('/docs', async () => { return

Docs home

}) .page('/docs/getting-started', async () => { return

Getting started

}) ``` ```tsx // counter.tsx 'use client' import { useState } from 'react' export function Counter() { const [count, setCount] = useState(0) return } ``` If you need to shut the server down later, `listen()` always returns an object with `port`, `server`, and `stop()`: ```ts const listener = await app.listen(3000) console.log(`Listening on port ${listener.port}`) await listener.stop() ``` > In Vite dev and during prerender, Spiceflow skips starting a real server. `listen()` still returns an object, but `port` and `server` are `undefined` and `stop()` is a noop, so cleanup code can stay unconditional. > React pages require Vite and the spiceflow Vite plugin. See [nodejs-example/vite.config.ts](nodejs-example/vite.config.ts) for setup. API-only apps don't need Vite. > Use `.route()` instead of `.get()`/`.post()` when you want to pass Zod schemas for validation — it accepts `request`, `response`, `query`, and `params` schemas. ## Returning JSON Spiceflow automatically serializes objects returned from handlers to JSON, so you don't need to wrap them in a `Response` object: ```ts import { Spiceflow } from 'spiceflow' const app = new Spiceflow() .get('/user', () => { // Return object directly - no need for new Response() return { id: 1, name: 'John', email: 'john@example.com' } }) .post('/data', async ({ 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 fetch client, **throw Response objects for errors** and **return objects directly for success cases**. The fetch client returns `Error | Data` directly — use `instanceof Error` to narrow the type: ```ts import { Spiceflow } from 'spiceflow' import { z } from 'zod' const app = new Spiceflow() .route({ method: 'GET', path: '/users/:id', query: z.object({ q: z.string(), }), response: z.object({ id: z.string(), name: z.string(), email: z.string(), }), handler({ params }) { const user = getUserById(params.id) if (!user) { throw new Response('User not found', { status: 404 }) } 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 new Response('User already exists', { status: 409 }) } const newUser = await createUser(body) return { id: newUser.id, name: newUser.name, email: newUser.email, } }, }) export type App = typeof app ``` ```ts // client.ts import { createSpiceflowFetch } from 'spiceflow/client' import type { App } from './server' const safeFetch = createSpiceflowFetch('http://localhost:3000') // Path params are type-safe — TypeScript requires { id: string } const user = await safeFetch('/users/:id', { params: { id: '123' }, query: { q: 'something' }, }) if (user instanceof Error) { console.error('Error:', user.message) return } // user is typed as { id: string, name: string, email: string } console.log('User:', user.name, user.email) // Body is type-safe — TypeScript requires { name: string, email: string } const newUser = await safeFetch('/users', { method: 'POST', body: { name: 'John', email: 'john@example.com' }, }) if (newUser instanceof Error) return newUser console.log('Created:', newUser.id) ``` With this pattern: - **Success responses**: Return objects directly for automatic JSON serialization and proper type inference - **Error responses**: Throw `Response` objects — the fetch client returns a `SpiceflowFetchError` with `status`, `value`, and `response` properties - **Type safety**: The fetch client gives you full type safety on **path params**, **query params**, **request body**, and **response data** — all inferred from your route definitions ## 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](https://github.com/elysiajs/elysia/pull/773) - 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 ```ts 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 ```ts 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(), }), async handler({ request, params }) { const typedJson = await request.json() // this body will have the correct type return { id: Number(params.id), name: typedJson.name } }, }) ``` ## Type-Safe Fetch Client `createSpiceflowFetch` provides a type-safe `fetch(path, options)` interface for calling your Spiceflow API. It gives you full type safety on **path params**, **query params**, **request body**, and **response data** — all inferred from your route definitions. Export the app type from your server code: ```ts // 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: ```ts // client.ts import { createSpiceflowFetch } from 'spiceflow/client' import type { App } from './server' const safeFetch = createSpiceflowFetch('http://localhost:3000') // GET request — returns Error | Data, check with instanceof Error const greeting = await safeFetch('/hello') if (greeting instanceof Error) return greeting console.log(greeting) // 'Hello, World!' — TypeScript knows the type // POST with typed body — TypeScript requires { name: string, email: string } const user = await safeFetch('/users', { method: 'POST', body: { name: 'John', email: 'john@example.com' }, }) if (user instanceof Error) return user console.log(user.id, user.name, user.email) // fully typed // Path params — type-safe, TypeScript requires { id: string } const foundUser = await safeFetch('/users/:id', { params: { id: '123' }, }) if (foundUser instanceof Error) return foundUser console.log(foundUser.id) // typed as string // Query params — typed from the route's Zod schema const searchResults = await safeFetch('/search', { query: { q: 'hello', page: 1 }, }) if (searchResults instanceof Error) return searchResults console.log(searchResults.results, searchResults.query) // fully typed // Streaming — async generator routes return an AsyncGenerator const stream = await safeFetch('/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](https://errore.org) 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: ```ts const safeFetch = createSpiceflowFetch(app) const greeting = await safeFetch('/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/*`. A wildcard route also matches the parent path without a trailing segment — `/files/*` matches both `/files/foo` and `/files`. - **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: ```ts 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 ``` ## Chaining Routes for Type Safety Never declare app and add routes separately — that way you lose the type safety. Instead always append routes in a single chained expression: ```ts // 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.get('/hello', () => { return 'Hello, World!' }) // Do NOT do this! Adding routes separately like this will lose type safety app.post('/echo', async ({ request }) => { const body = await request.json() return body }) ``` ## 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: ```ts 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) } } ``` ## Type-Safe Path Building The `href` 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. ```ts 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.href('/users/:id', { id: '123' }) // Result: '/users/123' // Building URLs with required parameters const userPostPath = app.href('/users/:id/posts/:postId', { id: '456', postId: 'abc', }) // Result: '/users/456/posts/abc' ``` ### Query Parameters When a route has a `query` schema, `href` 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: ```ts 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.href('/search', { q: 'hello', page: 1 }) // Result: '/search?q=hello&page=1' app.href('/users/:id', { id: '42', fields: 'name' }) // Result: '/users/42?fields=name' // @ts-expect-error - 'invalid' is not a known query key app.href('/search', { invalid: 'x' }) ``` ### Standalone `createHref` If you need a path builder on the client side where you can't import server app code, use `createHref` with the `App` type: ```ts import { createHref } from 'spiceflow' import type { App } from './server' // import only the type, not the runtime app const href = createHref() href('/users/:id', { id: '123' }) // Result: '/users/123' href('/search', { q: 'hello', page: 1 }) // Result: '/search?q=hello&page=1' ``` The returned function has the same type safety as `app.href` — 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 `createHref()` without passing any value. ### OAuth Callback Example The `href` 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: ```ts 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.href('/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 `href` with type checking - Required parameters like `provider` and `userId` must be provided - The resulting URL is guaranteed to be properly formatted ## Mounting Sub-Apps ```ts 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 For standalone API servers (without Vite), set the base path in the constructor: ```ts 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 ``` ### Base Path with Vite (RSC apps) When using Spiceflow as a full-stack RSC framework with Vite, configure the base path via Vite's `base` option instead of the constructor: ```ts // vite.config.ts import { defineConfig } from 'vite' import { spiceflowPlugin } from 'spiceflow/vite' export default defineConfig({ base: '/my-app', plugins: [spiceflowPlugin({ entry: 'src/main.tsx' })], }) ``` The base path must be an absolute path starting with `/`. CDN URLs and relative paths are not supported. Do not set `basePath` in the Spiceflow constructor when using Vite — Spiceflow will throw an error if both are set. The Vite `base` option is the single source of truth. **What gets the base path auto-prepended:** - `Link` component `href` — `` automatically renders as ``. If the href already includes the base prefix, it is not added again (`` stays as-is). To disable auto-prepending entirely, use the `rawHref` prop: `` — useful when your path legitimately starts with the same string as the base - `redirect()` Location header — `redirect("/login")` sends `Location: /my-app/login` - `router.push()` and `router.replace()` — `router.push("/settings")` navigates to `/my-app/settings` - `router.pathname` — returns the path **without** the base prefix (e.g. `/dashboard`, not `/my-app/dashboard`) - Static asset URLs (`