bun-hono-integration

Bun Hono Integration

Hono is a fast, lightweight web framework optimized for Bun.

Quick Start

bun create hono my-app
cd my-app
bun install
bun run dev

Basic Setup

import { Hono } from "hono";

const app = new Hono();

app.get("/", (c) => c.text("Hello Hono!"));

app.get("/json", (c) => c.json({ message: "Hello" }));

export default app;

Routing

import { Hono } from "hono";

const app = new Hono();

// HTTP methods
app.get("/users", (c) => c.json([]));
app.post("/users", (c) => c.json({ created: true }));
app.put("/users/:id", (c) => c.json({ updated: true }));
app.delete("/users/:id", (c) => c.json({ deleted: true }));

// All methods
app.all("/any", (c) => c.text("Any method"));

// Path parameters
app.get("/users/:id", (c) => {
  const id = c.req.param("id");
  return c.json({ id });
});

// Multiple parameters
app.get("/posts/:postId/comments/:commentId", (c) => {
  const { postId, commentId } = c.req.param();
  return c.json({ postId, commentId });
});

// Wildcards
app.get("/files/*", (c) => {
  const path = c.req.path;
  return c.text(`File: ${path}`);
});

// Regex-like patterns
app.get("/user/:id{[0-9]+}", (c) => c.json({ id: c.req.param("id") }));

export default app;

Route Groups

import { Hono } from "hono";

const app = new Hono();

// Group routes
const api = new Hono();
api.get("/users", (c) => c.json([]));
api.get("/posts", (c) => c.json([]));

app.route("/api/v1", api);

// Basepath
const app2 = new Hono().basePath("/api/v2");
app2.get("/users", (c) => c.json([])); // /api/v2/users

export default app;

Request Handling

app.post("/submit", async (c) => {
  // URL and method
  console.log(c.req.url);
  console.log(c.req.method);

  // Headers
  const auth = c.req.header("Authorization");

  // Query params
  const page = c.req.query("page");
  const { limit, offset } = c.req.query();

  // Body parsing
  const json = await c.req.json();
  const text = await c.req.text();
  const form = await c.req.formData();
  const arrayBuffer = await c.req.arrayBuffer();

  // Parsed body (with validator)
  const body = c.req.valid("json");

  return c.json({ received: true });
});

Response Types

app.get("/responses", (c) => {
  // Text
  return c.text("Hello");

  // JSON
  return c.json({ data: "value" });

  // HTML
  return c.html("<h1>Hello</h1>");

  // Redirect
  return c.redirect("/other", 302);

  // Not Found
  return c.notFound();

  // Custom response
  return c.body("Raw body", 200, {
    "Content-Type": "text/plain",
  });

  // Status
  return c.json({ error: "Not found" }, 404);

  // Headers
  c.header("X-Custom", "value");
  return c.json({ ok: true });
});

Middleware

import { Hono } from "hono";

const app = new Hono();

// Global middleware
app.use("*", async (c, next) => {
  console.log(`${c.req.method} ${c.req.url}`);
  await next();
});

// Path-specific middleware
app.use("/api/*", async (c, next) => {
  const auth = c.req.header("Authorization");
  if (!auth) {
    return c.json({ error: "Unauthorized" }, 401);
  }
  await next();
});

// Multiple middleware
app.use("/admin/*", authMiddleware, adminMiddleware);

app.get("/api/data", (c) => c.json({ data: "protected" }));

export default app;

Built-in Middleware

import { Hono } from "hono";
import { cors } from "hono/cors";
import { logger } from "hono/logger";
import { basicAuth } from "hono/basic-auth";
import { bearerAuth } from "hono/bearer-auth";
import { compress } from "hono/compress";
import { etag } from "hono/etag";
import { secureHeaders } from "hono/secure-headers";

const app = new Hono();

// CORS
app.use("*", cors());
app.use("/api/*", cors({
  origin: "https://example.com",
  allowMethods: ["GET", "POST"],
}));

// Logger
app.use("*", logger());

// Basic Auth
app.use("/admin/*", basicAuth({
  username: "admin",
  password: "secret",
}));

// Bearer Token
app.use("/api/*", bearerAuth({
  token: "my-token",
}));

// Compression
app.use("*", compress());

// ETag
app.use("*", etag());

// Security headers
app.use("*", secureHeaders());

export default app;

Validation with Zod

import { Hono } from "hono";
import { zValidator } from "@hono/zod-validator";
import { z } from "zod";

const app = new Hono();

const userSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  age: z.number().min(0).optional(),
});

app.post(
  "/users",
  zValidator("json", userSchema),
  (c) => {
    const user = c.req.valid("json");
    // user is typed and validated
    return c.json({ created: user });
  }
);

// Query validation
const querySchema = z.object({
  page: z.string().regex(/^\d+$/).optional(),
  limit: z.string().regex(/^\d+$/).optional(),
});

app.get(
  "/items",
  zValidator("query", querySchema),
  (c) => {
    const { page, limit } = c.req.valid("query");
    return c.json({ page, limit });
  }
);

export default app;

Context Variables

import { Hono } from "hono";

type Variables = {
  userId: string;
  isAdmin: boolean;
};

const app = new Hono<{ Variables: Variables }>();

app.use("*", async (c, next) => {
  c.set("userId", "123");
  c.set("isAdmin", true);
  await next();
});

app.get("/profile", (c) => {
  const userId = c.get("userId");
  const isAdmin = c.get("isAdmin");
  return c.json({ userId, isAdmin });
});

export default app;

Error Handling

import { Hono } from "hono";
import { HTTPException } from "hono/http-exception";

const app = new Hono();

// Throw HTTP error
app.get("/error", (c) => {
  throw new HTTPException(401, { message: "Unauthorized" });
});

// Global error handler
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return err.getResponse();
  }
  console.error(err);
  return c.json({ error: "Internal Server Error" }, 500);
});

// Not found handler
app.notFound((c) => {
  return c.json({ error: "Not Found" }, 404);
});

export default app;

RPC Mode (Type-safe Client)

// server.ts
import { Hono } from "hono";
import { hc } from "hono/client";

const app = new Hono()
  .get("/users", (c) => c.json([{ id: 1, name: "Alice" }]))
  .post("/users", async (c) => {
    const body = await c.req.json();
    return c.json({ created: body });
  });

export type AppType = typeof app;
export default app;

// client.ts
import { hc } from "hono/client";
import type { AppType } from "./server";

const client = hc<AppType>("http://localhost:3000");

// Type-safe calls
const res = await client.users.$get();
const users = await res.json(); // Typed!

const created = await client.users.$post({
  json: { name: "Bob" },
});

Common Errors

Error	Cause	Fix
Route not found	Wrong path	Check route registration
Body already read	Double parsing	Read body once
Validator error	Invalid input	Check schema definition
Middleware order	Wrong execution	Register middleware first

When to Load References

Load references/middleware-list.md when:

• Complete middleware reference
• Custom middleware patterns

Load references/openapi.md when:

• OpenAPI/Swagger integration
• API documentation generation