1~
2Por anos, escolher um framework web em JavaScript significava aceitar um trade-off: Express era universal mas lento e preso ao Node, Fastify era rápido mas só Node, Next.js era completo mas pesado. Quando chegaram os runtimes edge - Cloudflare Workers, Deno Deploy, Bun, Vercel Edge - esses frameworks mostraram seus limites: dependências incompatíveis, bundles enormes, APIs amarradas a `req`/`res` do Node.
3~
4[Hono](https://hono.dev) (japonês para "chama" 🔥) é a resposta moderna. Um framework de menos de 14KB, totalmente baseado em Web Standards (`Request`, `Response`, `fetch`), que roda onde houver um runtime JavaScript. O mesmo código é deployado em Cloudflare Workers, Bun, Deno, Node.js, Vercel, Netlify e AWS Lambda - sem mudanças.
5~
6## Por que Hono
7~
8Hono faz três coisas melhor do que qualquer outro:
9~
101. **Performance.** O `RegExpRouter` compila todos os padrões de rota em uma única regex, evitando os loops lineares dos routers tradicionais. Benchmarks superam 400.000 ops/s, colocando Hono entre os routers mais rápidos do ecossistema JavaScript.
112. **Portabilidade.** Web Standards significa zero dependências do Node. O mesmo `app.fetch` é exportado como default num Cloudflare Worker, passado para `Bun.serve`, montado num servidor Deno ou adaptado com `@hono/node-server`.
123. **DX TypeScript-first.** Path parameters tipados como literais, cliente RPC type-safe end-to-end, validadores que inferem tipos de entrada e saída. O autocomplete é quase telepático.
13~
14```mermaid
15graph LR
16    Client[Client] -->|Request| App[app.fetch]
17    App --> MW1[Middleware 1]
18    MW1 --> MW2[Middleware 2]
19    MW2 --> Router[RegExpRouter]
20    Router --> Handler[Route Handler]
21    Handler --> Context[c.json / c.text]
22    Context -->|Response| Client
23    App -.->|deploy| CF[Cloudflare Workers]
24    App -.->|deploy| Bun[Bun]
25    App -.->|deploy| Deno[Deno]
26    App -.->|deploy| Node[Node.js]
27    App -.->|deploy| Vercel[Vercel]
28```
29~
30## Começar
31~
32O caminho mais rápido é o starter oficial, que monta o projeto para o runtime escolhido.
33~
34```bash
35npm create hono@latest my-api
36cd my-api
37npm install
38npm run dev
39```
40~
41O starter pergunta qual template usar: `cloudflare-workers`, `bun`, `deno`, `nodejs`, `vercel`, `aws-lambda`, `nextjs` e mais. Ele escolhe configs e scripts de deploy adequados. Para experimentar rapidamente, também dá para começar com um único arquivo:
42~
43```typescript
44// src/index.ts
45import { Hono } from 'hono'
46~
47const app = new Hono()
48~
49app.get('/', (c) => c.text('Hello Hono!'))
50~
51export default app
52```
53~
54Em Cloudflare Workers isso basta. Em Bun: `Bun.serve({ fetch: app.fetch, port: 3000 })`. Em Node: `serve({ fetch: app.fetch })` de `@hono/node-server`. A superfície é idêntica.
55~
56## Routing
57~
58As rotas são declaradas com métodos de verbo HTTP e suportam parâmetros, wildcards e regex.
59~
60```typescript
61import { Hono } from 'hono'
62~
63const app = new Hono()
64~
65app.get('/', (c) => c.text('Home'))
66app.get('/posts/:id', (c) => {
67  const id = c.req.param('id') // string, tipado
68  return c.json({ id })
69})
70app.get('/posts/:id/comments/:commentId', (c) => {
71  const { id, commentId } = c.req.param()
72  return c.json({ id, commentId })
73})
74app.get('/files/*', (c) => c.text('Wildcard'))
75app.post('/posts', async (c) => {
76  const body = await c.req.json()
77  return c.json({ created: body }, 201)
78})
79```
80~
81Os parâmetros são inferidos como tipos literais: TypeScript sabe que `c.req.param('id')` retorna `string` apenas se você declarou `:id` no padrão. Errar o nome é erro de compilação.
82~
83### Agrupar rotas
84~
85`app.route()` permite compor sub-aplicações como módulos, cada uma com seu prefixo.
86~
87```typescript
88// routes/posts.ts
89import { Hono } from 'hono'
90~
91const posts = new Hono()
92posts.get('/', (c) => c.json({ posts: [] }))
93posts.get('/:id', (c) => c.json({ id: c.req.param('id') }))
94export default posts
95~
96// src/index.ts
97import { Hono } from 'hono'
98import posts from './routes/posts'
99~
100const app = new Hono()
101app.route('/posts', posts)
102```
103~
104Rotas aninhadas herdam o base path e o tipo do app raiz, então o cliente RPC enxerga toda a estrutura.
105~
106## O objeto Context
107~
108Cada handler recebe um `c` - o Context para a requisição atual. É a única API que você precisa aprender para ler entradas e produzir saídas.
109~
110```typescript
111app.post('/echo', async (c) => {
112  // Leitura
113  const userAgent = c.req.header('User-Agent')
114  const page = c.req.query('page')
115  const body = await c.req.json()
116  const env = c.env // bindings (KV, D1, secrets no Cloudflare)
117~
118  // Variáveis compartilhadas entre middleware e handler
119  c.set('requestId', crypto.randomUUID())
120  const id = c.get('requestId')
121~
122  // Resposta
123  c.header('X-Request-Id', id)
124  c.status(200)
125  return c.json({ userAgent, page, body, id })
126})
127```
128~
129Os métodos de resposta principais são `c.text`, `c.json`, `c.html`, `c.body` (raw) e `c.redirect`. Todos aceitam um status code como segundo argumento.
130~
131## Middleware: o modelo cebola
132~
133Middleware são funções `(c, next) => ...` que podem rodar código antes e depois do handler. Compostos formam o clássico modelo cebola: o primeiro middleware registrado é o primeiro a começar e o último a terminar.
134~
135```typescript
136import { Hono } from 'hono'
137import { logger } from 'hono/logger'
138import { cors } from 'hono/cors'
139import { secureHeaders } from 'hono/secure-headers'
140~
141const app = new Hono()
142~
143app.use('*', logger())
144app.use('*', secureHeaders())
145app.use('/api/*', cors({ origin: 'https://spinny.dev' }))
146~
147app.use('*', async (c, next) => {
148  const start = performance.now()
149  await next()
150  c.header('X-Response-Time', `${performance.now() - start}ms`)
151})
152```
153~
154`await next()` cede o controle ao próximo middleware. Tudo depois disso roda na fase de resposta, depois que o handler produziu um resultado. Retornar uma `Response` antes de `next()` interrompe a cadeia.
155~
156### Middleware integrados
157~
158Hono entrega um conjunto rico de middleware production-ready, importáveis de `hono/...`:
159~
160| Middleware | Para que serve |
161|-----------|---------|
162| `logger` | Logs estruturados de método, path, status, duração |
163| `cors` | CORS configurável por origin, métodos, headers |
164| `csrf` | Proteção CSRF baseada em origin |
165| `secureHeaders` | Define CSP, HSTS, X-Frame-Options |
166| `bearerAuth` / `basicAuth` | Auth Bearer/Basic out of the box |
167| `jwt` | Verifica e assina JWT com `jose` |
168| `etag` | Gera ETag e trata 304 |
169| `cache` | Cache via Web Cache API |
170| `compress` | gzip/deflate na resposta |
171| `bodyLimit` | Rejeita bodies acima de um limite |
172| `timing` | Header Server-Timing para profiling |
173~
174### Middleware custom type-safe
175~
176Para estender o `Context` com variáveis tipadas, use `createMiddleware`:
177~
178```typescript
179import { createMiddleware } from 'hono/factory'
180~
181type AuthVars = { userId: string; role: 'user' | 'admin' }
182~
183export const requireAuth = createMiddleware<{ Variables: AuthVars }>(
184  async (c, next) => {
185    const token = c.req.header('Authorization')?.replace('Bearer ', '')
186    if (!token) return c.json({ error: 'Unauthorized' }, 401)
187~
188    const payload = await verifyJwt(token)
189    c.set('userId', payload.sub)
190    c.set('role', payload.role)
191    await next()
192  }
193)
194~
195// Uso
196app.get('/me', requireAuth, (c) => {
197  const userId = c.var.userId // string, tipado
198  return c.json({ userId })
199})
200```
201~
202Após o middleware, `c.var.userId` está tipado sem nenhum cast. Isso se propaga por toda a cadeia.
203~
204## Validação com Zod
205~
206`@hono/zod-validator` integra Zod ao ciclo da requisição. Você define um schema, aplica à rota e obtém entradas já validadas e tipadas.
207~
208```typescript
209import { Hono } from 'hono'
210import { zValidator } from '@hono/zod-validator'
211import { z } from 'zod'
212~
213const createPost = z.object({
214  title: z.string().min(1).max(200),
215  body: z.string().min(1),
216  tags: z.array(z.string()).default([]),
217})
218~
219app.post(
220  '/posts',
221  zValidator('json', createPost),
222  (c) => {
223    const data = c.req.valid('json') // tipado conforme o schema
224    return c.json({ ok: true, post: data }, 201)
225  }
226)
227```
228~
229Se o body não validar, Hono responde 400 com o erro do Zod antes mesmo de chamar o handler. Você também pode validar `query`, `param`, `header`, `cookie` e `form`.
230~
231## RPC: cliente type-safe end-to-end
232~
233A feature que realmente diferencia o Hono é o **modo RPC**. Você exporta o tipo do seu app do servidor, o cliente `hc` o importa e você obtém autocomplete completo - paths, query, body, headers e response - sem codegen ou OpenAPI.
234~
235```typescript
236// server.ts
237import { Hono } from 'hono'
238import { zValidator } from '@hono/zod-validator'
239import { z } from 'zod'
240~
241const app = new Hono()
242  .get('/posts/:id', (c) =>
243    c.json({ id: c.req.param('id'), title: 'Hello' })
244  )
245  .post(
246    '/posts',
247    zValidator('json', z.object({ title: z.string(), body: z.string() })),
248    (c) => c.json({ ok: true }, 201)
249  )
250~
251export type AppType = typeof app
252export default app
253```
254~
255```typescript
256// client.ts
257import { hc } from 'hono/client'
258import type { AppType } from './server'
259~
260const client = hc<AppType>('https://api.spinny.dev')
261~
262const res = await client.posts[':id'].$get({ param: { id: '42' } })
263if (res.ok) {
264  const data = await res.json() // { id: string, title: string }
265  console.log(data.title)
266}
267~
268const created = await client.posts.$post({
269  json: { title: 'Olá', body: 'Hono é uma chama' }, // validado
270})
271```
272~
273Renomeie uma rota no servidor e o TypeScript do cliente quebra imediatamente em CI. Mesma vantagem do tRPC, mas sobre HTTP padrão, sem middleware específico e com bundle mínimo.
274~
275### Status codes discriminantes
276~
277Se você retorna status diferentes, o cliente os discrimina automaticamente.
278~
279```typescript
280.get('/posts/:id', (c) => {
281  const post = findPost(c.req.param('id'))
282  if (!post) return c.json({ error: 'not found' }, 404)
283  return c.json({ post }, 200)
284})
285```
286~
287```typescript
288const res = await client.posts[':id'].$get({ param: { id } })
289if (res.status === 404) {
290  const { error } = await res.json() // { error: string }
291}
292if (res.status === 200) {
293  const { post } = await res.json() // { post: Post }
294}
295```
296~
297## Routers e performance
298~
299Hono oferece cinco routers com trade-offs diferentes. O default é o `SmartRouter`, que ao iniciar mede qual router serve melhor suas rotas e fixa nele.
300~
301| Router | Forças | Quando usar |
302|--------|--------|-------------|
303| `RegExpRouter` | Velocidade máxima, regex compilada | Default para a maioria das APIs |
304| `TrieRouter` | Suporta todos os padrões | Padrões complexos não cobertos pelo RegExp |
305| `SmartRouter` | Escolhe o melhor automaticamente | Default recomendado |
306| `LinearRouter` | Registro ultra rápido | Workers one-shot, cold start crítico |
307| `PatternRouter` | Bundle mínimo (<15KB) | Restrições extremas de tamanho |
308~
309Para workers stateless com cold starts frequentes, `LinearRouter` evita o custo de compilação inicial e é 33x mais rápido que `find-my-way` quando se mede registro mais matching.
310~
311```typescript
312import { Hono } from 'hono'
313import { LinearRouter } from 'hono/router/linear-router'
314~
315const app = new Hono({ router: new LinearRouter() })
316```
317~
318## Deploy multi-runtime
319~
320O mesmo `export default app` muda de destino apenas trocando o arquivo de entrada.
321~
322### Cloudflare Workers
323~
324```typescript
325// src/index.ts
326import { Hono } from 'hono'
327~
328type Bindings = { MY_KV: KVNamespace; DB: D1Database }
329const app = new Hono<{ Bindings: Bindings }>()
330~
331app.get('/cache/:key', async (c) => {
332  const value = await c.env.MY_KV.get(c.req.param('key'))
333  return c.json({ value })
334})
335~
336export default app
337```
338~
339Deploy: `npx wrangler deploy`. Bindings KV/D1/R2/Queues são nativos.
340~
341### Bun
342~
343```typescript
344import { Hono } from 'hono'
345const app = new Hono()
346app.get('/', (c) => c.text('Bun + Hono'))
347~
348Bun.serve({ fetch: app.fetch, port: 3000 })
349```
350~
351### Node.js
352~
353```typescript
354import { serve } from '@hono/node-server'
355import { Hono } from 'hono'
356~
357const app = new Hono()
358app.get('/', (c) => c.text('Node + Hono'))
359~
360serve({ fetch: app.fetch, port: 3000 })
361```
362~
363### Deno
364~
365```typescript
366import { Hono } from 'jsr:@hono/hono'
367const app = new Hono()
368app.get('/', (c) => c.text('Deno + Hono'))
369Deno.serve(app.fetch)
370```
371~
372### Vercel
373~
374```typescript
375// api/[[...route]].ts
376import { Hono } from 'hono'
377import { handle } from 'hono/vercel'
378~
379const app = new Hono().basePath('/api')
380app.get('/hello', (c) => c.json({ msg: 'Hello from Vercel' }))
381~
382export const GET = handle(app)
383export const POST = handle(app)
384```
385~
386Mesmo código de negócio, mesmo routing, mesmo middleware. Só o adaptador muda.
387~
388## Exemplo prático: API REST com auth e DB
389~
390Juntando as peças. Uma API de blog em Cloudflare Workers + D1, com auth JWT, validação e RPC.
391~
392```typescript
393import { Hono } from 'hono'
394import { jwt } from 'hono/jwt'
395import { logger } from 'hono/logger'
396import { cors } from 'hono/cors'
397import { zValidator } from '@hono/zod-validator'
398import { z } from 'zod'
399~
400type Bindings = { DB: D1Database; JWT_SECRET: string }
401type Variables = { jwtPayload: { sub: string } }
402~
403const app = new Hono<{ Bindings: Bindings; Variables: Variables }>()
404~
405app.use('*', logger())
406app.use('/api/*', cors({ origin: 'https://spinny.dev', credentials: true }))
407~
408const auth = (c: any, next: any) =>
409  jwt({ secret: c.env.JWT_SECRET })(c, next)
410~
411const api = app.basePath('/api')
412~
413api.get('/posts', async (c) => {
414  const { results } = await c.env.DB
415    .prepare('SELECT id, title, created_at FROM posts ORDER BY created_at DESC LIMIT 50')
416    .all()
417  return c.json({ posts: results })
418})
419~
420api.post(
421  '/posts',
422  auth,
423  zValidator('json', z.object({
424    title: z.string().min(1).max(200),
425    body: z.string().min(1),
426  })),
427  async (c) => {
428    const { title, body } = c.req.valid('json')
429    const userId = c.var.jwtPayload.sub
430    const result = await c.env.DB
431      .prepare('INSERT INTO posts (title, body, author_id) VALUES (?, ?, ?) RETURNING id')
432      .bind(title, body, userId)
433      .first<{ id: number }>()
434    return c.json({ id: result?.id }, 201)
435  }
436)
437~
438api.onError((err, c) => {
439  console.error(err)
440  return c.json({ error: 'Internal error' }, 500)
441})
442~
443export type AppType = typeof api
444export default app
445```
446~
447Um cliente React consome com type safety total:
448~
449```typescript
450import { hc } from 'hono/client'
451import type { AppType } from '../api/src/index'
452~
453const api = hc<AppType>(import.meta.env.VITE_API_URL)
454~
455const res = await api.posts.$post({
456  json: { title: 'Hono em 2026', body: '...' },
457}, {
458  headers: { Authorization: `Bearer ${token}` },
459})
460```
461~
462## Testes
463~
464`app.request()` permite testar rotas sem subir um servidor HTTP. É o mesmo path que rodaria em produção, executado em memória.
465~
466```typescript
467import { describe, it, expect } from 'vitest'
468import app from '../src/index'
469~
470describe('GET /api/posts', () => {
471  it('retorna a lista de posts', async () => {
472    const res = await app.request('/api/posts')
473    expect(res.status).toBe(200)
474    const body = await res.json()
475    expect(body.posts).toBeInstanceOf(Array)
476  })
477})
478```
479~
480Em Cloudflare Workers, `@cloudflare/vitest-pool-workers` roda os mesmos testes dentro de um Worker real com bindings mock - máximo realismo, zero deploy.
481~
482## Melhores práticas
483~
484### 1. Encadear definições de rota
485~
486```typescript
487const app = new Hono()
488  .get('/posts', handler1)
489  .post('/posts', handler2)
490  .get('/posts/:id', handler3)
491```
492~
493O chaining mantém o tipo do `app` atualizado a cada rota, essencial para o cliente RPC. Defini-las separadas com `app.get(...)` em linhas distintas quebra a inferência.
494~
495### 2. Exporte o tipo, não a implementação
496~
497O cliente deve importar `AppType`, não o app. `import type` garante que o build do frontend não inclua código de backend.
498~
499### 3. Um router por domínio
500~
501Um sub-app para `posts`, um para `users`, um para `webhooks`. Componha com `app.route()` e cada um possui seus middleware. A estrutura escala sem mega-arquivos.
502~
503### 4. Validação na borda, sempre
504~
505Toda entrada externa (body, query, header) deve passar por `zValidator`. Não confie em dados a jusante: até um cast TypeScript sem validação runtime é um bug à espera.
506~
507### 5. Apoie-se em bindings, não em clientes globais
508~
509Em Cloudflare, acesse KV/D1/R2 via `c.env`. Sem singletons globais, sem conexões persistindo entre Workers. O modelo stateless é uma feature, não uma limitação.
510~
511### 6. Meça antes de otimizar o router
512~
513O `SmartRouter` padrão dá conta em 95% dos casos. Troque o router só após profilar e ver um gargalo real.
514~
515## Conclusão
516~
517Hono virou em 2026 o padrão de fato para construir APIs prontas para o edge em TypeScript. A combinação de Web Standards, performance, type safety e portabilidade resolve exatamente os problemas que travavam os frameworks tradicionais: lock-in ao runtime, bundles pesados, type system frágil entre cliente e servidor.
518~
519Você vai usá-lo para microsserviços em Cloudflare Workers, para substituir Express num monolito Node, para uma function na Vercel ou para uma API em Bun. O mesmo conhecimento se transfere para todo lugar - e isso é o que torna ele um investimento sólido para os próximos anos.
520~
521> **Checklist para começar:**
522>
523> - [x] `npm create hono@latest` e escolha seu template de runtime
524> - [x] Defina rotas com chaining (`.get(...).post(...)`)
525> - [x] Adicione `logger`, `cors`, `secureHeaders` como middleware globais
526> - [x] Valide toda entrada com `@hono/zod-validator`
527> - [x] Exporte `AppType` e consuma a API com o cliente `hc` type-safe
528> - [x] Escreva testes com `app.request()` - sem servidor HTTP
529> - [x] Deploy com `wrangler deploy` (CF), `vercel deploy` ou o bundler do seu runtime
530~