Hono: ультрашвидкий веб-фреймворк на основі Web Standards

Роками вибір JavaScript-веб-фреймворку означав прийняття компромісу: Express універсальний, але повільний і прив'язаний до Node, Fastify швидкий, але лише Node, Next.js повнофункціональний, але важкий. Із появою edge-рантаймів — Cloudflare Workers, Deno Deploy, Bun, Vercel Edge — ці фреймворки виявили свої межі.

Hono (з японської "полум'я" 🔥) — сучасна відповідь. Фреймворк менше 14KB, повністю побудований на Web Standards (Request, Response, fetch), який працює там, де є JavaScript-рантайм. Той самий код деплоїться на Cloudflare Workers, Bun, Deno, Node.js, Vercel, Netlify і AWS Lambda — без змін.

Чому Hono

1. Продуктивність. RegExpRouter компілює всі шаблони маршрутів в одне регулярне вираження. Бенчмарки перевищують 400 000 ops/с.
2. Портативність. Web Standards означає нуль залежностей від Node.
3. TypeScript-first DX. Параметри шляху виводяться як літерали, типобезпечний RPC-клієнт end-to-end.

Початок роботи

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

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

const app = new Hono()

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

export default app

На Cloudflare Workers цього досить. На Bun: Bun.serve({ fetch: app.fetch, port: 3000 }). На Node: serve({ fetch: app.fetch }) з @hono/node-server.

Маршрутизація

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)
})

Групування маршрутів

// 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)

Об'єкт 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: цибулева модель

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`)
})

Вбудовані middleware

Middleware	Призначення
logger	Структуровані логи методу, шляху, статусу, тривалості
cors	CORS налаштовуваний за origin, методами, заголовками
csrf	CSRF-захист на основі origin
secureHeaders	Встановлює CSP, HSTS, X-Frame-Options
bearerAuth / basicAuth	Готова Bearer/Basic-автентифікація
jwt	Перевірка/підпис JWT через jose
etag	Генерує ETag і обробляє 304
cache	Кеш через Web Cache API
compress	gzip/deflate відповіді
bodyLimit	Відхиляє body понад поріг
timing	Заголовок Server-Timing для профілювання

Типобезпечні власні 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 })
})

Валідація з 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: типобезпечний клієнт 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: 'Привіт', body: 'Hono — це полум\'я' },
})

Дискримінація за статус-кодом

.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()
}

Маршрутизатори і продуктивність

Маршрутизатор	Сильні сторони	Коли використовувати
RegExpRouter	Максимальна швидкість, скомпільований regex	Дефолт для більшості API
TrieRouter	Підтримує всі шаблони	Складні шаблони, які RegExp не обробляє
SmartRouter	Обирає найкращий автоматично	Рекомендований дефолт
LinearRouter	Надшвидка реєстрація	One-shot воркери, критичний cold start
PatternRouter	Мінімальний bundle (<15KB)	Жорсткі обмеження за розміром

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

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

Мультирантайм-деплой

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

Деплой: 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)

Практичний приклад: REST API з auth і 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

Тестування

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

describe('GET /api/posts', () => {
  it('повертає список постів', async () => {
    const res = await app.request('/api/posts')
    expect(res.status).toBe(200)
    const body = await res.json()
    expect(body.posts).toBeInstanceOf(Array)
  })
})

Найкращі практики

1. Ланцюжок визначень маршрутів

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

2. Експортуйте тип, а не реалізацію

Клієнт має імпортувати AppType.

3. По одному маршрутизатору на домен

Sub-app для posts, users, webhooks.

4. Валідація на кордоні, завжди

Кожен зовнішній вхід має пройти через zValidator.

5. Спирайтеся на bindings, а не глобальні клієнти

На Cloudflare доступ до KV/D1/R2 через c.env.

6. Замірюйте перед оптимізацією маршрутизатора

Дефолтний SmartRouter підходить для 95% випадків.

Висновок

Hono став у 2026 році де-факто стандартом для побудови edge-готових API в TypeScript.

Чек-лист для старту:

• npm create hono@latest і виберіть шаблон рантайму
• Визначте маршрути ланцюжком (.get(...).post(...))
• Додайте logger, cors, secureHeaders як глобальний middleware
• Валідуйте кожен вхід з @hono/zod-validator
• Експортуйте AppType і використовуйте API через типобезпечний hc-клієнт
• Пишіть тести з app.request() — без HTTP-сервера
• Деплойте через wrangler deploy (CF), vercel deploy або bundler вашого рантайму