What you write
is what runs.

HTTP framework for Bun

What you write
is what runs.

Lifecycle hooks in fixed slots, controllers that take their dependencies as arguments, and types inferred from the schema to the handler. No decorators, no container, no dependencies.

Get startedbun add @tetsujs/core

app.ts

import { controller, createApp, httpError, route } from "@tetsujs/core";
import { z } from "zod";

const users = controller("Users", ({ repo }: { repo: UserRepository }) => ({
  get: route({
    method: "GET",
    path: "/users/:id",
    schema: { params: z.object({ id: z.coerce.number() }) },
    handler: (ctx) => {
      const user = repo.find(ctx.params.id);
id: number
      if (!user) throw httpError(404, "USER_NOT_FOUND");
      return user;
    },
  }),
}));

Bun.serve({ ...createApp({ routes: users({ repo }) }) });

Caught before it runs

The compiler knows what the framework knows.

✕Hook without its user✕Undeclared status✕Path Bun never matches✕NULL from a left join

const latestOrder = hook.beforeHandle(
  (ctx: Requires<{ user: User }>) => ({ order: orders.listFor(ctx.user.id)[0] }),
);

route({
  method: "GET",
  path: "/orders/latest",
  hooks: { beforeHandle: [latestOrder] },
Error ts(2322)  ― Hook requires context 'user' which is not provided by path, schema or preceding hooks
  handler: (ctx) => ctx.order,
});

const UserDto = z.object({ id: z.number(), name: z.string() });

route({
  method: "POST",
  path: "/users",
  schema: { response: { 200: UserDto } },
  handler: (ctx) => {
    ctx.out.status = 201;
Error ts(2322)  ― Type '201' is not assignable to type '200'.
    return repo.create({ name: "Ada", email: "ada@example.com" });
  },
});

route({
  method: "GET",
  path: "/files/*/raw",
Error ts(2322)  ― A '*' must be the entire final segment: Bun's router matches '/files/*', but a wildcard anywhere else never matches any request
  handler: () => new Response("…"),
});

// queries/customer-orders.sql
//   select o.id, o.status, o.total, s.carrier, s.shipped_at
//   from orders o
//     left join shipments s on s.order_id = o.id
//   where o.customer_id = :customerId

import { customerOrders } from "./queries.generated";

for (const order of await customerOrders(db, { customerId })) {
  console.log(order.shipped_at.toISOString());
Error ts(18047)  ― 'order.shipped_at' is possibly 'null'.
}

How it reads

Plain objects, wired by hand.

Routes and validation

The body is read and checked before the handler runs. A failure is a 422 with the issues; ctx.body is what the schema returned.

const UserDto = z.object({ id: z.number(), name: z.string() });

export const createUser = route({
  method: "POST",
  path: "/users",
  schema: {
    body: z.object({ name: z.string().min(1), email: z.email() }),
    response: { 201: UserDto },
  },
  handler: (ctx) => {
    ctx.out.status = 201;
    return repo.create(ctx.body);
  },
});

Hooks

Hooks sit in fixed slots of the request, not in an onion. What a hook returns joins ctx, typed in everything after it.

const auth = hook.beforeParse(async (ctx) => {
  const user = await sessions.verify(ctx.req.headers.get("authorization"));
  if (!user) throw new HttpError(401);
  return { user };
});

const log = hook.afterResponse((ctx) => {
  console.log(ctx.req.method, ctx.route?.path, ctx.res.status);
});

export const listOrders = route({
  method: "GET",
  path: "/orders",
  hooks: { beforeParse: [auth], afterResponse: [log] },
  handler: (ctx) => orders.listFor(ctx.user.id),
});

Controllers

A controller is a name and a function from its dependencies to its routes. The application is wired by hand, in one place.

export const ordersController = controller("Orders", (orders: OrderService) => ({
  list: route({
    method: "GET",
    path: "/orders",
    handler: () => orders.listFor(1),
  }),
}));

export const usersController = controller("Users", (users: UserRepository) => ({
  get: route({
    method: "GET",
    path: "/users/:id",
    handler: (ctx) => users.find(Number(ctx.params.id)),
  }),
}));

export default createApp({
  routes: [ordersController(orders), usersController(repo)],
});

Errors

Your errors, failed validation, 404 and 405 all leave in one envelope. An onError hook on the application can replace it everywhere.

export const cancelOrder = route({
  method: "POST",
  path: "/orders/:id/cancel",
  schema: { params: z.object({ id: z.coerce.number() }) },
  handler: (ctx) => {
    const order = orders.find(ctx.params.id);
    if (!order) throw new HttpError(404);
    if (order.shipped) throw httpError(409, "ALREADY_SHIPPED", "Order already shipped");
    return orders.cancel(order);
  },
});

// 404 { "status": 404, "message": "Not Found", "error": "NOT_FOUND" }
// 409 { "status": 409, "message": "Order already shipped", "error": "ALREADY_SHIPPED" }

OpenAPI

The document is built once, at startup, from the routes you already declared: their schemas, their responses and the guards you annotated.

import { docs } from "@tetsujs/openapi";

export default createApp({
  routes: [
    usersController(repo),
    docs({ info: { title: "Users API", version: "1.0.0" } }),
  ],
});

// GET /openapi.json — the document
// GET /docs         — the page

Client

A frontend calls the API with the types its routes declare, from a contract generated from the application: no server code, no Bun.

import { createClient } from "@tetsujs/client";
import type { Api } from "./api.contract"; // generated

const api = createClient<Api>({ baseUrl: "https://api.example.com" });

const res = await api.get("/users/:id", { params: { id: 1 } });

if (res.ok) {
  console.log(res.data.name);
} else if (res.status === 404) {
  console.log(res.error.message);
}

Testing

A handler is a function: call it with a context. The whole application is served on a free port, through Bun's own router.

import { serve, testCtx } from "@tetsujs/core/testing";
import { expect, test } from "bun:test";

const request = serve(createApp({ routes: usersController(repo) }));

test("the handler, alone", () => {
  const { get } = usersController(repo);
  expect(get.handler(testCtx({ params: { id: "1" } }))).toEqual(ada);
});

test("the application, over HTTP", async () => {
  expect((await request("/users/1")).status).toBe(200);
});

Database

Migrations are SQL, and the types come from the database they build. A query is Kysely's, or a file of SQL that Postgres types; the controller takes the database as it takes any dependency.

import { controller, createApp, route } from "@tetsujs/core";
import { database } from "@tetsujs/sql";
import type { Kysely } from "kysely";
import { z } from "zod";
import { type DB, schema } from "./db.generated";
import { customerOrders } from "./queries.generated";

const ordersController = controller("Orders", (db: Kysely<DB>) => ({
  list: route({
    method: "GET",
    path: "/customers/:id/orders",
    schema: { params: z.object({ id: z.coerce.bigint() }) },
    handler: async (ctx) => {
      const orders = await customerOrders(db, { customerId: ctx.params.id });

      return orders.map((order) => ({ ...order, id: String(order.id) }));
    },
  }),
}));

const db = database(schema, { url: config.DATABASE_URL });

export default createApp({ routes: ordersController(db) });

Performance

A fraction of a microsecond over Bun itself.

Processor time per request, lower is better. The same four routes in every framework, each server and load generator in its own process. Not the fastest on every route, but close to Bun on all of them.

GET /ping

• Bun, no framework4.78 µs
• Tetsu4.95 µs +0.17
• Elysia 1.44.89 µs +0.11
• Hono 4.135.16 µs +0.38

GET /users/:id + 2 hooks

• Bun, no framework4.81 µs
• Tetsu5.09 µs +0.28
• Elysia 1.45.13 µs +0.32
• Hono 4.135.87 µs +1.06

POST /items, validated

• Bun, no framework5.85 µs
• Tetsu6.60 µs +0.75
• Elysia 1.46.31 µs +0.46
• Hono 4.136.88 µs +1.03

404

• Bun, no framework4.82 µs
• Tetsu5.13 µs +0.31
• Elysia 1.44.91 µs +0.09
• Hono 4.135.41 µs +0.59

Bun 1.4.2, Apple M5 Pro, 2026-09-27, medians of three interleaved rounds. Method and caveats

Principles

Iron, not magic.

1. Controllers without decorators

   A named function from its dependencies to its routes, called once where the application is wired.

2. Flat, and no magic

   No registry, no file scanning, no reflection, no container. Any point of the application reads top to bottom.

3. Types do not lie

   A field is on ctx exactly when it exists: the body after validation, the user after the hook that found them.

4. Explicit over DRY

   A route lists its hooks by slot, in the order they run. Similar routes repeat them instead of inheriting them.

5. The platform, not a wrapper

   Bun's router, Headers, CookieMap, the real server. No dependencies in the core.

6. Why it is built this way →

Packages

Official, versioned together.

Hooks, controllers and functions, used like your own code. Nothing is registered.

• @tetsujs/coreroutes, hooks, validation, WebSockets — the framework
• @tetsujs/openapian OpenAPI 3.1 document and docs page from the routes
• @tetsujs/clienta typed fetch client, with TanStack Query options
• @tetsujs/typeboxTypeBox schemas as DTOs, file uploads included
• @tetsujs/corsCORS headers and preflight
• @tetsujs/rate-limitrate limiting with a replaceable store
• @tetsujs/request-idrequest ids
• @tetsujs/request-logaccess and arrival logs
• @tetsujs/secure-headerssecurity headers
• @tetsujs/sseserver-sent events and streamed responses
• @tetsujs/statica built site, a single-page app or assets
• @tetsujs/lifecyclegraceful shutdown
• @tetsujs/sqlPostgres: SQL migrations, types from the database, Kysely

Start with one route.

Bun 1.4 and TypeScript 5.7 or later. Nothing else.

Get startedbun add @tetsujs/core