Przez lata wybór frameworka webowego JavaScript oznaczał akceptację kompromisu: Express uniwersalny, ale powolny i przywiązany do Node, Fastify szybki, ale tylko Node, Next.js pełnofunkcyjny, ale ciężki. Gdy pojawiły się runtime'y edge — Cloudflare Workers, Deno Deploy, Bun, Vercel Edge — frameworki te ujawniły swoje granice.

Hono (po japońsku "płomień" 🔥) to nowoczesna odpowiedź. Framework poniżej 14KB, w pełni zbudowany na Web Standards (Request, Response, fetch), działający wszędzie, gdzie istnieje runtime JavaScript. Ten sam kod deployuje się na Cloudflare Workers, Bun, Deno, Node.js, Vercel, Netlify i AWS Lambda — bez zmian.

Dlaczego Hono

1. Wydajność. RegExpRouter kompiluje wszystkie wzorce route'ów do jednego regexa. Benchmarki przekraczają 400 000 ops/s.
2. Przenośność. Web Standards oznacza zero zależności od Node. Ten sam app.fetch jest eksportowany jako default w Cloudflare Worker, przekazywany do Bun.serve, montowany w serwerze Deno lub adaptowany przez @hono/node-server.
3. DX TypeScript-first. Parametry ścieżki wnioskowane jako literały, RPC client type-safe end-to-end.

Zaczynamy

npm create hono@latest my-api
cd my-api
npm install
npm run dev

Starter pyta o szablon: cloudflare-workers, bun, deno, nodejs, vercel, aws-lambda, nextjs i inne.

// src/index.ts
import { Hono } from 'hono'

const app = new Hono()

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

export default app

Na Cloudflare Workers to wystarczy. Na Bun: Bun.serve({ fetch: app.fetch, port: 3000 }). Na Node: serve({ fetch: app.fetch }) z @hono/node-server.

Routing

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => c.text('Home'))
app.get('/posts/:id', (c) => {
  const id = c.req.param('id')
  return c.json({ id })
})
app.get('/posts/:id/comments/:commentId', (c) => {
  const { id, commentId } = c.req.param()
  return c.json({ id, commentId })
})
app.get('/files/*', (c) => c.text('Wildcard'))
app.post('/posts', async (c) => {
  const body = await c.req.json()
  return c.json({ created: body }, 201)
})

Grupowanie route'ów

// routes/posts.ts
import { Hono } from 'hono'

const posts = new Hono()
posts.get('/', (c) => c.json({ posts: [] }))
posts.get('/:id', (c) => c.json({ id: c.req.param('id') }))
export default posts

// src/index.ts
import { Hono } from 'hono'
import posts from './routes/posts'

const app = new Hono()
app.route('/posts', posts)

Obiekt Context

app.post('/echo', async (c) => {
  const userAgent = c.req.header('User-Agent')
  const page = c.req.query('page')
  const body = await c.req.json()
  const env = c.env

  c.set('requestId', crypto.randomUUID())
  const id = c.get('requestId')

  c.header('X-Request-Id', id)
  c.status(200)
  return c.json({ userAgent, page, body, id })
})

Middleware: model cebuli

import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { secureHeaders } from 'hono/secure-headers'

const app = new Hono()

app.use('*', logger())
app.use('*', secureHeaders())
app.use('/api/*', cors({ origin: 'https://spinny.dev' }))

app.use('*', async (c, next) => {
  const start = performance.now()
  await next()
  c.header('X-Response-Time', `${performance.now() - start}ms`)
})

Wbudowane middleware

Middleware	Cel
logger	Strukturyzowane logi metody, ścieżki, statusu, czasu
cors	CORS konfigurowalny przez origin, metody, nagłówki
csrf	Ochrona CSRF na podstawie origin
secureHeaders	Ustawia CSP, HSTS, X-Frame-Options
bearerAuth / basicAuth	Gotowe Bearer/Basic auth
jwt	Weryfikacja/podpis JWT z jose
etag	Generuje ETag i obsługuje 304
cache	Cache przez Web Cache API
compress	gzip/deflate odpowiedzi
bodyLimit	Odrzuca body powyżej progu
timing	Nagłówek Server-Timing do profilowania

Type-safe niestandardowe middleware

import { createMiddleware } from 'hono/factory'

type AuthVars = { userId: string; role: 'user' | 'admin' }

export const requireAuth = createMiddleware<{ Variables: AuthVars }>(
  async (c, next) => {
    const token = c.req.header('Authorization')?.replace('Bearer ', '')
    if (!token) return c.json({ error: 'Unauthorized' }, 401)

    const payload = await verifyJwt(token)
    c.set('userId', payload.sub)
    c.set('role', payload.role)
    await next()
  }
)

app.get('/me', requireAuth, (c) => {
  const userId = c.var.userId
  return c.json({ userId })
})

Walidacja z Zod

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

const createPost = z.object({
  title: z.string().min(1).max(200),
  body: z.string().min(1),
  tags: z.array(z.string()).default([]),
})

app.post(
  '/posts',
  zValidator('json', createPost),
  (c) => {
    const data = c.req.valid('json')
    return c.json({ ok: true, post: data }, 201)
  }
)

RPC: type-safe klient end-to-end

// server.ts
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const app = new Hono()
  .get('/posts/:id', (c) =>
    c.json({ id: c.req.param('id'), title: 'Hello' })
  )
  .post(
    '/posts',
    zValidator('json', z.object({ title: z.string(), body: z.string() })),
    (c) => c.json({ ok: true }, 201)
  )

export type AppType = typeof app
export default app

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

const client = hc<AppType>('https://api.spinny.dev')

const res = await client.posts[':id'].$get({ param: { id: '42' } })
if (res.ok) {
  const data = await res.json()
  console.log(data.title)
}

const created = await client.posts.$post({
  json: { title: 'Cześć', body: 'Hono to płomień' },
})

Dyskryminacja kodów statusu

.get('/posts/:id', (c) => {
  const post = findPost(c.req.param('id'))
  if (!post) return c.json({ error: 'not found' }, 404)
  return c.json({ post }, 200)
})

const res = await client.posts[':id'].$get({ param: { id } })
if (res.status === 404) {
  const { error } = await res.json()
}
if (res.status === 200) {
  const { post } = await res.json()
}

Routery i wydajność

Router	Zalety	Kiedy używać
RegExpRouter	Maksymalna prędkość, skompilowany regex	Domyślny dla większości API
TrieRouter	Obsługuje wszystkie wzorce	Złożone wzorce nieobsługiwane przez RegExp
SmartRouter	Wybiera najlepszy automatycznie	Zalecany domyślny
LinearRouter	Ultraszybka rejestracja	Worker one-shot, krytyczny cold start
PatternRouter	Minimalny bundle (<15KB)	Ekstremalne ograniczenia rozmiaru

import { Hono } from 'hono'
import { LinearRouter } from 'hono/router/linear-router'

const app = new Hono({ router: new LinearRouter() })

Multi-runtime deploy

Cloudflare Workers

import { Hono } from 'hono'

type Bindings = { MY_KV: KVNamespace; DB: D1Database }
const app = new Hono<{ Bindings: Bindings }>()

app.get('/cache/:key', async (c) => {
  const value = await c.env.MY_KV.get(c.req.param('key'))
  return c.json({ value })
})

export default app

Deploy: npx wrangler deploy.

Bun

import { Hono } from 'hono'
const app = new Hono()
app.get('/', (c) => c.text('Bun + Hono'))

Bun.serve({ fetch: app.fetch, port: 3000 })

Node.js

import { serve } from '@hono/node-server'
import { Hono } from 'hono'

const app = new Hono()
app.get('/', (c) => c.text('Node + Hono'))

serve({ fetch: app.fetch, port: 3000 })

Deno

import { Hono } from 'jsr:@hono/hono'
const app = new Hono()
app.get('/', (c) => c.text('Deno + Hono'))
Deno.serve(app.fetch)

Vercel

// api/[[...route]].ts
import { Hono } from 'hono'
import { handle } from 'hono/vercel'

const app = new Hono().basePath('/api')
app.get('/hello', (c) => c.json({ msg: 'Hello from Vercel' }))

export const GET = handle(app)
export const POST = handle(app)

Praktyczny przykład: REST API z auth i DB

import { Hono } from 'hono'
import { jwt } from 'hono/jwt'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

type Bindings = { DB: D1Database; JWT_SECRET: string }
type Variables = { jwtPayload: { sub: string } }

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

app.use('*', logger())
app.use('/api/*', cors({ origin: 'https://spinny.dev', credentials: true }))

const auth = (c: any, next: any) =>
  jwt({ secret: c.env.JWT_SECRET })(c, next)

const api = app.basePath('/api')

api.get('/posts', async (c) => {
  const { results } = await c.env.DB
    .prepare('SELECT id, title, created_at FROM posts ORDER BY created_at DESC LIMIT 50')
    .all()
  return c.json({ posts: results })
})

api.post(
  '/posts',
  auth,
  zValidator('json', z.object({
    title: z.string().min(1).max(200),
    body: z.string().min(1),
  })),
  async (c) => {
    const { title, body } = c.req.valid('json')
    const userId = c.var.jwtPayload.sub
    const result = await c.env.DB
      .prepare('INSERT INTO posts (title, body, author_id) VALUES (?, ?, ?) RETURNING id')
      .bind(title, body, userId)
      .first<{ id: number }>()
    return c.json({ id: result?.id }, 201)
  }
)

api.onError((err, c) => {
  console.error(err)
  return c.json({ error: 'Internal error' }, 500)
})

export type AppType = typeof api
export default app

Testy

import { describe, it, expect } from 'vitest'
import app from '../src/index'

describe('GET /api/posts', () => {
  it('zwraca listę postów', async () => {
    const res = await app.request('/api/posts')
    expect(res.status).toBe(200)
    const body = await res.json()
    expect(body.posts).toBeInstanceOf(Array)
  })
})

Najlepsze praktyki

1. Łańcuchowanie definicji route'ów

const app = new Hono()
  .get('/posts', handler1)
  .post('/posts', handler2)
  .get('/posts/:id', handler3)

2. Eksportuj typ, nie implementację

Klient musi importować AppType.

3. Jeden router na domenę

Sub-app dla posts, users, webhooks.

4. Walidacja na granicy, zawsze

Każde wejście zewnętrzne musi przejść przez zValidator.

5. Polegaj na bindings, nie globalnych klientach

Na Cloudflare dostęp do KV/D1/R2 przez c.env.

6. Mierz przed optymalizacją routera

Domyślny SmartRouter pasuje w 95% przypadków.

Podsumowanie

Hono stało się w 2026 de facto standardem do budowy API gotowych na edge w TypeScript.

Lista startowa:

• npm create hono@latest i wybierz szablon runtime
• Zdefiniuj route'y z łańcuchowaniem (.get(...).post(...))
• Dodaj logger, cors, secureHeaders jako globalne middleware
• Waliduj każde wejście z @hono/zod-validator
• Eksportuj AppType i konsumuj API z type-safe klientem hc
• Pisz testy z app.request() — bez serwera HTTP
• Deployuj z wrangler deploy (CF), vercel deploy lub bundlerem twojego runtime