Rouzer

Rouzer is a small TypeScript HTTP framework for projects that can share one route tree between server and client code. The route tree defines URL patterns, named actions, request validation, and response contracts once, then Rouzer uses it to build a fetch-compatible router and a typed fetch client.

Rouzer also includes a chainable middleware layer for request-scoped state, host/runtime data, background work, response callbacks, and adapter helpers that turn a router into a Fetch API handler.

Use It When

Use Rouzer when:

• your server and client can import the same TypeScript route module
• you want Zod validation before client requests and before server handlers
• a fetch-compatible handler fits your runtime or adapter
• named resource/action calls are a better fit than generated SDK classes

Consider another tool when you need OpenAPI-first schemas, generated clients for other languages, server-side response validation for every handler return, or a framework that owns rendering, deployment, and data loading.

Install

pnpm add rouzer zod

Rouzer requires ESM, Zod v4 or newer, a Fetch API implementation for clients, and a fetch-compatible server or adapter for routers.

import {
  $error,
  $type,
  chain,
  createClient,
  createRouter,
  metadata,
  toFetchHandler,
} from 'rouzer'
import * as http from 'rouzer/http'
import * as ndjson from 'rouzer/ndjson'

chain, toFetchHandler, request context types, and related middleware helpers are part of the root Rouzer API.

Small Example

import * as z from 'zod'
import {
  $type,
  chain,
  createClient,
  createRouter,
  toFetchHandler,
} from 'rouzer'
import * as http from 'rouzer/http'

type Profile = {
  id: string
  name: string
  requestId: string
}

export const profiles = http.resource('profiles/:id', {
  get: http.get({
    query: z.object({
      includePosts: z.optional(z.boolean()),
    }),
    response: $type<Profile>(),
  }),
})

export const routes = { profiles }

const requestInfo = chain().use(ctx => ({
  requestId: ctx.request.headers.get('x-request-id') ?? 'local',
}))

const router = createRouter({ basePath: 'api/' })
  .use(requestInfo)
  .use(routes, {
    profiles: {
      get(ctx) {
        return {
          id: ctx.path.id,
          name: 'Ada',
          requestId: ctx.requestId,
        }
      },
    },
  })

const fetchHandler = toFetchHandler(router)

const client = createClient({
  baseURL: 'https://example.com/api/',
  routes,
})

const profile = await client.profiles.get(
  { id: '42', includePosts: false },
  { headers: { 'x-request-id': 'docs' } }
)

The shared routes object drives the handler map and the generated client. The middleware output becomes part of the handler context, while the route schema adds typed ctx.path, ctx.query, ctx.body, and ctx.headers values.

Core Concepts

Route contracts live in shared TypeScript modules. Use rouzer/http resources for path-scoped namespaces and actions such as http.get, http.post, and http.patch for concrete HTTP operations.

Routers are chainable request handlers. createRouter() returns a handler; .use(middleware) appends middleware and .use(routes, handlers) attaches a route tree.

Handlers mirror the route tree. Rouzer validates the matched request before the handler runs, then lets the handler return JSON data, a custom Response, declared status helpers, or a response-plugin value such as an NDJSON stream.

Clients mirror the same route tree. createClient({ baseURL, routes }) returns typed action functions with flat route input objects and optional per-request RequestInit options.

Response markers are type contracts. $type<T>(), $error<T>(), and ndjson.$type<T>() shape handler and client types, but they do not re-validate handler return values at the server boundary.

Documentation

• Documentation map
• Framework concepts
• Route contracts
• Middleware and request context
• Routers and handlers
• Typed client
• Responses, errors, and plugins
• NDJSON streaming
• Runtime and adapters
• Patterns, constraints, and migrations
• Migration from v5 to v6

Runnable examples:

• Basic shared-route example
• Typed status response example
• NDJSON response-stream example

Published declarations provide exact signatures for every public export, including the rouzer/http and rouzer/ndjson subpaths. Public TSDoc in src/ owns symbol-level behavior and option details.