hono

# Hono Skill Build Hono web applications. This skill provides inline API knowledge for AI. Use `npx hono request` to test endpoints. If the `hono-docs` MCP server is configured, prefer its tools for the latest documentation over the inline reference. ## Hono CLI Usage ### Request Testing Test endpoints without starting an HTTP server. Uses `app.request()` internally. ```bash # GET request npx hono request [file] -P /path # POST request with JSON body npx hono request [file] -X POST -P /api/users -d '{"name": "test"}' ``` **Note:** Do not pass credentials directly in CLI arguments. Use environment variables for sensitive values. `hono request` does not support Cloudflare Workers bindings (KV, D1, R2, etc.). When bindings are required, use `workers-fetch` instead: ```bash npx workers-fetch /path npx workers-fetch -X POST -H "Content-Type:application/json" -d '{"name":"test"}' /api/users ``` --- ## Hono API Reference ### App Constructor ```ts import { Hono } from "hono"; const app = new Hono(); // With TypeScript generics type Env = { Bindings: { DATABASE: D1Database; KV: KVNamespace }; Variables: { user: User }; }; const app = new Hono<Env>(); ``` ### Routing Methods ```ts app.get("/path", handler); app.post("/path", handler); app.put("/path", handler); app.delete("/path", handler); app.patch("/path", handler); app.options("/path", handler); app.all("/path", handler); // all HTTP methods app.on("PURGE", "/path", handler); // custom method app.on(["PUT", "DELETE"], "/path", handler); // multiple methods ``` ### Routing Patterns ```ts // Path parameters app.get("/user/:name", (c) => { const name = c.req.param("name"); return c.json({ name }); }); // Multiple params app.get("/posts/:id/comments/:commentId", (c) => { const { id, commentId } = c.req.param(); }); // Optional parameters app.get("/api/animal/:type?", (c) => c.text("Animal!")); // Wildcards app.get("/wild/*/card", (c) => c.text("Wildcard")); // Regexp constraints app.get("/post/:date{[0-9]+}/:title{[a-z]+}", (c) => { const { date, title } = c.req.param(); }); // Chained routes app.get("/endpoint", (c) => c.text("GET")) .post((c) => c.text("POST")) .delete((c) => c.text("DELETE")); ``` ### Route Grouping ```ts // Using route() const api = new Hono(); api.get("/users", (c) => c.json([])); const app = new Hono(); app.route("/api", api); // mounts at /api/users // Using basePath() const app = new Hono().basePath("/api"); app.get("/users", (c) => c.json([])); // GET /api/users ``` ### Error Handling ```ts app.notFound((c) => c.json({ message: "Not Found" }, 404)); app.onError((err, c) => { console.error(err); return c.json({ message: "Internal Server Error" }, 500); }); ``` --- ## Context (c) ### Response Methods ```ts c.text("Hello"); // text/plain c.json({ message: "Hello" }); // application/json c.html("<h1>Hello</h1>"); // text/html c.redirect("/new-path"); // 302 redirect c.redirect("/new-path", 301); // 301 redirect c.body("raw body", 200, headers); // raw response c.notFound(); // 404 response ``` ### Headers & Status ```ts c.status(201); c.header("X-Custom", "value"); c.header("Cache-Control", "no-store"); ``` ### Variables (request-scoped data) ```ts // In middleware c.set("user", { id: 1, name: "Alice" }); // In handler const user = c.get("user"); // or const user = c.var.user; ``` ### Environment (Cloudflare Workers) ```ts const value = await c.env.KV.get("key"); const db = c.env.DATABASE; c.executionCtx.waitUntil(promise); ``` ### Renderer ```ts app.use(async (c, next) => { c.setRenderer((content) => c.html( <html><body>{content}</body></html> ) ) await next() }) app.get('/', (c) => c.render(<h1>Hello</h1>)) ``` --- ## HonoRequest (c.req) ```ts c.req.param("id"); // path parameter c.req.param(); // all path params as object c.req.query("page"); // query string parameter c.req.query(); // all query params as object c.req.queries("tags"); // multiple values: ?tags=A&tags=B → ['A', 'B'] c.req.header("Authorization"); // request header c.req.header(); // all headers (keys are lowercase) // Body parsing await c.req.json(); // parse JSON body await c.req.text(); // parse text body await c.req.formData(); // parse as FormData await c.req.parseBody(); // parse multipart/form-data or urlencoded await c.req.arrayBuffer(); // parse as ArrayBuffer await c.req.blob(); // parse as Blob // Validated data (used with validator middleware) c.req.valid("json"); c.req.valid("query"); c.req.valid("form"); c.req.valid("param"); // Properties c.req.url; // full URL string c.req.path; // pathname c.req.method; // HTTP method c.req.raw; // underlying Request object ``` --- ## Middleware ### Using Built-in Middleware ```ts import { cors } from "hono/cors"; import { logger } from "hono/logger"; import { basicAuth } from "hono/basic-auth"; import { prettyJSON } from "hono/pretty-json"; import { secureHeaders } from "hono/secure-headers"; import { etag } from "hono/etag"; import { compress } from "hono/compress"; import { poweredBy } from "hono/powered-by"; import { timing } from "hono/timing"; import { cache } from "hono/cache"; import { bearerAuth } from "hono/bearer-auth"; import { jwt } from "hono/jwt"; import { csrf } from "hono/csrf"; import { ipRestriction } from "hono/ip-restriction"; import { bodyLimit } from "hono/body-limit"; import { requestId } from "hono/request-id"; import { methodOverride } from "hono/method-override"; import { trailingSlash, trimTrailingSlash } from "hono/trailing-slash"; // Registration app.use(logger()); // all routes app.use("/api/*", cors()); // specific path app.post("/api/*", basicAuth({ username: "admin", password: "secret" })); ``` ### Custom Middleware ```ts // Inline app.use(async (c, next) => { const start = Date.now(); await next(); const elapsed = Date.now() - start; c.res.headers.set("X-Response-Time", `${elapsed}ms`); }); // Reusable with createMiddleware import { createMiddleware } from "hono/factory"; const auth = createMiddleware(async (c, next) => { const token = c.req.header("Authorization"); if (!token) return c.json({ error: "Unauthorized" }, 401); await next(); }); app.use("/api/*", auth); ``` ### Middleware Execution Order Middleware executes in registration order. `await next()` calls the next middleware/handler, and code after `next()` runs on the way back: ``` Request → mw1 before → mw2 before → handler → mw2 after → mw1 after → Response ``` ```ts app.use(async (c, next) => { // before handler await next(); // after handler }); ``` --- ## Validation Validation targets: `json`, `form`, `query`, `header`, `param`, `cookie`. ### Zod Validator ```ts import { zValidator } from "@hono/zod-validator"; import { z } from "zod"; const schema = z.object({ title: z.string().min(1), body: z.string(), }); app.post("/posts", zValidator("json", schema), (c) => { const data = c.req.valid("json"); // fully typed return c.json(data, 201); }); ``` ### Valibot / Standard Schema Validator ```ts import { sValidator } from "@hono/standard-validator"; import * as v from "valibot"; const schema = v.object({ name: v.string(), age: v.number() }); app.post("/users", sValidator("json", schema), (c) => { const data = c.req.valid("json"); return c.json(data, 201); }); ``` --- ## JSX ### Setup In `tsconfig.json`: ```json { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "hono/jsx" } } ``` Or use pragma: `/** @jsxImportSource hono/jsx */` **Important:** Files using JSX must have a `.tsx` extension. Rename `.ts` to `.tsx` or the compiler will fail. ### Components ```tsx import type { PropsWithChildren } from "hono/jsx"; const Layout = (props: PropsWithChildren) => ( <html> <head> <title>My App</title> </head> <body>{props.children}</body> </html> ); const UserCard = ({ name }: { name: string }) => (