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

Годами выбор JavaScript веб-фреймворка означал принятие компромисса: Express универсален, но медленный и привязан к Node, Fastify быстр, но только для Node, Next.js полнофункционален, но тяжёлый. С появлением edge-рантаймов — Cloudflare Workers, Deno Deploy, Bun, Vercel Edge — эти фреймворки показали свои пределы: несовместимые зависимости, огромные бандлы, API, привязанные к req/res Node.

Hono (с японского "пламя" 🔥) — современный ответ. Фреймворк весом менее 14KB, полностью построенный на Web Standards (Request, Response, fetch), работающий везде, где есть JavaScript-рантайм. Один и тот же код деплоится на Cloudflare Workers, Bun, Deno, Node.js, Vercel, Netlify и AWS Lambda — без изменений.

Почему Hono

Hono делает три вещи лучше всех:

1. Производительность. RegExpRouter компилирует все паттерны маршрутов в одно регулярное выражение, избегая линейных циклов традиционных маршрутизаторов. Бенчмарки превышают 400 000 ops/s, ставя Hono в число самых быстрых маршрутизаторов JavaScript-экосистемы.
2. Портативность. Web Standards означает ноль зависимостей от Node. Один и тот же app.fetch экспортируется по умолчанию в Cloudflare Worker, передаётся в Bun.serve, монтируется в Deno-сервер или адаптируется через @hono/node-server.
3. TypeScript-first DX. Параметры пути типизированы как литералы, типобезопасный RPC-клиент end-to-end, валидаторы, выводящие типы входа и выхода. Автодополнение почти телепатическое.

Начало работы

Самый быстрый путь — официальный стартер, который скаффолдит проект для выбранного рантайма.

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

Стартер спрашивает, какой шаблон использовать: cloudflare-workers, bun, deno, nodejs, vercel, aws-lambda, nextjs и другие. Для быстрой пробы можно начать и с одного файла:

// 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. Поверхность идентична.

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

Маршруты объявляются методами HTTP-глаголов и поддерживают параметры, wildcard и regex.

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') // string, типизировано
  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)
})

Параметры выводятся как литеральные типы: TypeScript знает, что c.req.param('id') возвращает string только если вы объявили :id в паттерне. Опечатка — ошибка времени компиляции.

Группировка маршрутов

app.route() позволяет компоновать суб-приложения как модули, каждое со своим префиксом.

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

Вложенные маршруты наследуют base path и тип корневого приложения, поэтому RPC-клиент видит всю структуру.

Объект Context

Каждый обработчик получает c — Context для текущего запроса. Это единственный API, который нужно изучить, чтобы читать вход и производить выход.

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 // bindings (KV, D1, секреты на Cloudflare)

  // Переменные, разделяемые между middleware и обработчиком
  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 })
})

Основные методы ответа: c.text, c.json, c.html, c.body (raw), c.redirect. Все принимают код состояния вторым аргументом.

Middleware: луковичная модель

Middleware — функции (c, next) => ..., которые могут выполнять код до и после обработчика. Скомпонованные, они образуют классическую луковичную модель: первый зарегистрированный 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`)
})

await next() передаёт управление следующему middleware. Всё, что после, выполняется в фазе ответа после того, как обработчик произвёл результат. Возврат Response до next() короткозамыкает цепочку.

Встроенный middleware

Типобезопасный custom 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 // string, типизировано
  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)
  }
)

Если тело не проходит валидацию, Hono отвечает 400 с ошибкой Zod ещё до вызова обработчика. Можно валидировать также query, param, header, cookie и form.

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 — это пламя' },
})

Переименуйте маршрут на сервере, и TypeScript клиента сразу же сломается в CI. То же преимущество, что у tRPC, но поверх стандартного HTTP, без специфичного middleware и с крошечным бандлом.

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

.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() // { error: string }
}
if (res.status === 200) {
  const { post } = await res.json() // { post: Post }
}

Маршрутизаторы и производительность

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. KV/D1/R2/Queues bindings нативны.

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)

Тот же бизнес-код, та же маршрутизация, тот же middleware. Меняется только адаптер.

Реальный пример: 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

React-клиент потребляет с полной типобезопасностью:

import { hc } from 'hono/client'
import type { AppType } from '../api/src/index'

const api = hc<AppType>(import.meta.env.VITE_API_URL)

const res = await api.posts.$post({
  json: { title: 'Hono в 2026', body: '...' },
}, {
  headers: { Authorization: `Bearer ${token}` },
})

Тестирование

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

app.request() позволяет тестировать маршруты без поднятия HTTP-сервера.

Лучшие практики

1. Цепочка определений маршрутов

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

Цепочка поддерживает тип app актуальным с каждым маршрутом — критично для RPC-клиента.

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

Клиент должен импортировать AppType, а не приложение. import type гарантирует, что фронтенд-сборка не включит код бэкенда.

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

Под-приложение для posts, для users, для webhooks. Компонуй через app.route().

4. Валидация на границе, всегда

Каждый внешний вход (body, query, header) должен пройти через zValidator.

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

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

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

Дефолтный SmartRouter подходит для 95% случаев.

Заключение

Hono стал в 2026 году де-факто стандартом для построения edge-готовых API на TypeScript. Сочетание Web Standards, производительности, типобезопасности и портативности решает именно те проблемы, которые сдерживали традиционные фреймворки.

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

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