Server

Katman gives you two ways to run your API: serve() for a quick Node.js server, and handler() for any runtime that supports the Fetch API (Bun, Deno, Cloudflare Workers, etc.).

serve()

The simplest way to get a server running. One call, and you have an HTTP server with automatic port selection, optional API docs, and WebSocket support:

import { katman } from "katman"
import { z } from "zod"

const k = katman({
  context: (req) => ({ db: getDB() }),
})

const appRouter = k.router({
  health: k.query(() => ({ status: "ok" })),
})

k.serve(appRouter, {
  port: 3000,
})

Run it with npx tsx src/server.ts and you'll see:

Katman server running at http://127.0.0.1:3000

All options

k.serve(appRouter, {
  port: 3000,               // auto-finds next available if busy
  hostname: "0.0.0.0",      // bind to all interfaces
  scalar: true,             // API docs at /reference
  ws: true,                 // WebSocket RPC on the same port
  http2: {                  // HTTP/2 with TLS
    cert: "./certs/cert.pem",
    key: "./certs/key.pem",
  },
})

Automatic port selection

If your requested port is already in use, serve() finds the next available one in the 3000-3100 range. You never need to handle EADDRINUSE yourself.

handler()

For runtimes other than Node.js, or when you want to plug Katman into an existing server, use handler(). It returns a standard Fetch API function: (Request) => Promise<Response>.

const handle = k.handler(appRouter)
// handle is: (request: Request) => Promise<Response>

This works everywhere the Web Fetch API exists:

const handle = k.handler(appRouter)

Bun.serve({
port: 3000,
fetch: handle,
})

const handle = k.handler(appRouter)

Deno.serve({ port: 3000 }, handle)

const handle = k.handler(appRouter)

export default {
fetch: handle,
}

Content negotiation

Both serve() and handler() inspect the Accept header and respond in the format the client prefers:

The server also checks Content-Type on incoming POST requests to decode the body correctly. No configuration needed on the server side — it all happens automatically.

Scalar API docs

Katman can generate an OpenAPI 3.1.0 spec from your router and serve an interactive API reference powered by Scalar:

k.serve(appRouter, {
  port: 3000,
  scalar: true,
})

This gives you two extra routes:

• /reference — interactive API documentation UI
• /openapi.json — the raw OpenAPI specification

The spec is generated once at startup, so there is no per-request cost.

Customizing the docs

Pass an options object instead of true:

k.serve(appRouter, {
  scalar: {
    title: "My API",
    description: "Built with Katman",
    version: "2.0.0",
    servers: [{ url: "https://api.example.com" }],
    contact: { email: "[email protected]" },
    security: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
  },
})

Adding metadata to procedures

The generated docs pull information from your procedure definitions. Add route metadata to make the docs more useful:

const listUsers = k.query({
  input: z.object({ limit: z.number().optional() }),
  route: {
    summary: "List all users",
    description: "Returns a paginated list of users, ordered by creation date.",
    tags: ["users"],
  },
  resolve: ({ input, ctx }) => ctx.db.users.findMany({ take: input.limit }),
})

The route field accepts:

HTTP/2

For production deployments that benefit from multiplexing and header compression, pass TLS certificates:

k.serve(appRouter, {
  port: 443,
  http2: {
    cert: "./certs/cert.pem",
    key: "./certs/key.pem",
  },
})

Output:

Katman server running at https://127.0.0.1:443
  HTTP/2 enabled (with HTTP/1.1 fallback)

HTTP/2 requires TLS. Older clients that don't support HTTP/2 automatically fall back to HTTP/1.1 on the same port.

WebSocket support

Enable bidirectional RPC alongside the HTTP server:

k.serve(appRouter, {
  port: 3000,
  ws: true,
})

Katman server running at http://127.0.0.1:3000
  WebSocket RPC at ws://127.0.0.1:3000

HTTP and WebSocket share the same port. The server detects WebSocket upgrade requests and routes them accordingly. See the WebSocket protocol page for the message format and how to connect from the client.

Lifecycle hooks

Katman fires hooks at key points during request processing. Register them in the hooks option when creating the instance:

const k = katman({
  context: (req) => ({ db: getDB() }),
  hooks: {
    request: ({ path, input }) => {
      console.log(`--> ${path}`)
    },
    response: ({ path, output, durationMs }) => {
      console.log(`<-- ${path} (${durationMs.toFixed(1)}ms)`)
    },
    error: ({ path, error }) => {
      console.error(`ERR ${path}:`, error)
    },
    "serve:start": ({ url, port, hostname }) => {
      console.log(`Server ready at ${url}`)
    },
  },
})

You can also add or remove hooks after the instance is created:

// Add a hook
k.hook("error", ({ error }) => reportToSentry(error))

// Remove a hook
k.removeHook("error", myHookFn)

callable()

For server-side code where you need to call a procedure directly — without HTTP, serialization, or the client proxy. Useful in scripts, cron jobs, and seed files.

import { callable } from "katman"

const getUsers = k.query(
  z.object({ limit: z.number().optional() }),
  ({ input, ctx }) => ctx.db.users.findMany({ take: input.limit }),
)

const getUsersFn = callable(getUsers, {
  context: () => ({ db: getDB() }),
})

// Direct call — compiled pipeline, no HTTP
const users = await getUsersFn({ limit: 10 })

The compiled pipeline (guards, wraps, validation) runs exactly as it would through serve() or handler(). The only difference is there's no network involved.

What's next?

• Client — connect to your server from the browser or another service
• Middleware — guards and wraps that run inside your request pipeline
• Fastify integration — mount Katman inside an existing Fastify app
• Plugins — add CORS, logging, rate limiting, and tracing
• Protocols — learn about JSON, MessagePack, devalue, and WebSocket