# Hono — Human Primer

## 1. What is hono

Hono is a web framework built on Web Standards. It is published to npm and the repository lives at [github.com/honojs/hono](https://github.com/honojs/hono). The project was started by Yusuke Wada ([@yusukebe](https://github.com/yusukebe)) as a hobby project, and that stance has not fundamentally changed — it is built for fun and utility, not corporate mandate.

The current published version is **4.12.27** and the package describes itself as "Web framework built on Web Standards."

## 2. What can it do for you

- **Route HTTP requests fast.** The `RegExpRouter` does not use linear loops. The `hono/tiny` preset comes in under 12kB with zero dependencies.
- **Run everywhere.** The same code runs on Cloudflare Workers, Fastly Compute, Deno, Bun, AWS Lambda, Lambda@Edge, and Node.js — adapters are shipped for each target.
- **Handle middleware out of the box.** Built-in middleware includes bearer auth, body limiting, IP restriction, JSX rendering, SSG, streaming, validation helpers, and more — all exposed as separate named entrypoints (e.g. `hono/bearer-auth`, `hono/body-limit`).
- **Render JSX server-side.** Hono ships its own JSX runtime (`hono/jsx`, `hono/jsx/dom`, `hono/jsx/streaming`) so you can write component-style views without pulling in React.
- **Type everything.** First-class TypeScript support throughout. Generics on `new Hono<{ Variables, Bindings }>()` let you type environment bindings (e.g. Cloudflare KV, R2) and per-request variables.
- **Validate with third-party libraries.** The built-in validator middleware is deprecated; the recommended path is Zod, TypeBox, or similar.

## 3. What is it made of (the components)

The knowledge base identifies **7 components**:

| Component | Role |
|---|---|
| **hono** | The core framework — router, context, middleware pipeline, adapters |
| **jsx** | Hono's own JSX runtime and DOM reconciler; depends on `hono` |
| **routers** | Benchmarking suite comparing Hono's RegExpRouter and TrieRouter against external routers (find-my-way, express, koa-router, koa-tree-router, trek-router, @medley/router) |
| **hono-benchmark** | HTTP performance benchmarking tool comparing main vs. current versions; runs automatically on pull requests and posts results as PR comments |
| **query-param** | Utilities and benchmarks for query-string parsing |
| **webapp** | Example/demo web application; depends on `hono` |
| **utils** | Shared internal utilities |

Internal dependency edges: `jsx → hono` and `webapp → hono`.

External runtime dependencies pulled in across the repo include `memoirist`, `fast-querystring`, `rou3`, `radix3`, `itty-router`, `sunder`, `preact`, `nano-jsx`, and others — mostly for benchmarking comparisons, not for Hono's own production bundle (which has zero runtime dependencies).

## 4. How it works

**Routing** is the core. Hono ships multiple router implementations. `RegExpRouter` compiles routes into regular expressions and avoids linear per-request loops. `TrieRouter` uses a trie structure. You pick the router (or use a preset like `hono/tiny`) and Hono dispatches incoming `Request` objects through a middleware chain to produce a `Response` — both are standard Web API types.

**Middleware pipeline** follows a standard `next()`-style chain. Each handler receives a context object `c` and calls `next()` to pass control forward.

**Context (`c`)** exposes `c.req` (a `HonoRequest` wrapping the standard `Request`), `c.env` for platform bindings, and `c.get`/`c.set` for typed per-request variables.

**Adapters** wrap the core for each runtime. Importing from `hono/bun`, `hono/deno`, `hono/aws-lambda`, `hono/vercel`, etc. gives you the glue code for that platform.

**JSX** is handled by Hono's own runtime. It supports server-side streaming (`hono/jsx/streaming`) and a client-side DOM reconciler (`hono/jsx/dom`). The JSX Renderer Middleware (`hono/jsx-renderer`) defaults `docType` to `true` as of v4.

**Build output** ships both ESM (`dist/index.js`) and CJS (`dist/cjs/index.js`) with TypeScript declarations at `dist/types/`.

## 5. How do I install and use it

**Install the repo for development:**

```bash
git clone git@github.com:honojs/hono.git && cd hono && bun install --frozen-lockfile
```

**Scaffold a new project:**

```bash
npm create hono@latest
```

**Run the example web apps:**

```bash
npm run start          # default webapp
npm run start:hono     # Hono example
npm run start:itty-router
npm run start:sunder
```

**Test:**

```bash
npm run test           # TypeScript check + vitest
npm run test:bun
npm run test:deno
npm run test:node
npm run test:all       # all runtimes
```

**Benchmark routers:**

```bash
npm run bench:node
npm run bench:bun
```

**HTTP benchmark (requires Bun v1.0+ and `bombardier`):**

```bash
cd benchmarks/http-server
bun run benchmark.ts
```

**Build:**

```bash
npm run build
npm run watch   # incremental
```

**Lint and format (contributor workflow):**

```bash
bun run format:fix && bun run lint:fix
```

**Migrating from Deno `deno.land/x`:** As of v4.4.0, publish moved to JSR. Replace imports:

```ts
// Before
import { Hono } from 'https://deno.land/x/hono/mod.ts'
// After
import { Hono } from 'jsr:@hono/hono'
```

## 6. Honest scope and limits

- **Zero production dependencies** is a design goal for the core bundle, but the monorepo pulls in many external packages for benchmarking and testing purposes.
- **The built-in Validator Middleware is deprecated.** Use Zod, TypeBox, or another third-party library instead.
- **Some middleware has been removed entirely.** `graphql-server` and `mustache` middleware are obsolete and should not be used.
- **Breaking changes exist across major versions.** `c.req` changed type to `HonoRequest` in v3; Generics on `new Hono()` changed shape in v3; `FC` in `hono/jsx` no longer passes `children` automatically (use `PropsWithChildren`). Consult the migration guide before upgrading across major versions.
- **The project is hobby-driven by design.** The maintainer has been explicit that it started for fun and that stance has not changed — set community expectations accordingly.
- **702 public symbols and 1035 indexed passages** make this a substantial API surface; the middleware and adapter ecosystem is broad but each piece is a separate entrypoint, so you only pay for what you import.
