田中博悠 / tanahiro2010

v5 RC

• 10月8日 → 5.0.0-rc.0
• 10月10日 → 5.0.0-rc.1

honojs/hono releases

やったこと

• v4 と v5 の環境を別々に作る
• 同じコードを両方で動かす
• 差分だけを見る

環境

Apple M4 / 2026-10-18 時点

c.req.json()

app.post('/users', async (c) => {
  const body = await c.req.json()

  return c.json({ name: body.name.toUpperCase() })
})

• v4 → any
• v5 → unknown

v5

error TS18046: 'body' is of type 'unknown'.

c.req.query()

const { name } = c.req.query()
const upper: string = name.toUpperCase()

• v4 → Record<string, string>
• v5 → Record<string, string | undefined>

v5

error TS18048: 'name' is possibly 'undefined'.
error TS2322: Type 'string[] | undefined' is not
  assignable to type 'string[]'.

実行時の値を比べてみる

GET /q?a=1&a=2

わかったこと

• v5 は挙動を変えていない
• v4 でも undefined は返っていた
• 型が嘘をついていただけ

v4 の onError()

app.onError((err, c) => {
  console.error(err.message)
  return c.json({ error: 'Internal Server Error' }, 500)
})

• アプリ全体に1つだけ
• シグネチャは (err, c)

v5 の onError()

app.onError('/api/*', async (c, next) => {
  console.error(c.error?.message)
  c.header('X-Error-Handler', 'api')
  await next()
})

app.onError((c) => c.json({ error: 'Error' }, 500))

• (c, next) → 普通のミドルウェア
• エラーは c.error から読む
• パスで絞れる

設計意図

エラー処理を Hono のルーティングシステムの上に
モデル化する

• 内部では @ERROR / @NOT_FOUND という

予約メソッドで Router に登録されている

honojs/hono#5541

動かしてみた

v4

this.errorHandler is not a function

• パス文字列をハンドラとして保存してしまう
• 登録時ではなくリクエスト時に落ちる

実験

app.onError((c) => { order.push('first');  ... })
app.onError((c) => { order.push('second'); ... })

結果

敗因になりそうなところ

• v4 → 「あとから登録して潰す」が書けた
• v5 → 両方走る
• しかも⋯

型チェックは止めてくれる

error TS2339: Property 'message' does not exist
  on type 'Context<BlankEnv, string, any>'.
error TS2339: Property 'json' does not exist
  on type 'Next'.

• 第1引数が Context、第2引数が Next

実行すると

Context is not finalized.
Did you forget to return a Response object
or `await next()`?

何が起きてるか

• c のつもりで触ってるものが next 関数
• c.text() が無い → 例外
• → Context が確定しないまま終わる

型エラーを消すと、デバッグが遠回りになる

非 Error を throw したら

• オブジェクトは cause にしか入らない
• → c.error.message だけログに出すと何も分からない

c.json(undefined)

TypeError: Value is not JSON serializable

どこで踏むか

const user = await db.query.users.findFirst({ ... })
return c.json(user) // 見つからなければ undefined

• v4 → 404 のつもりが 200 で空ボディ
• v5 → 500

競合するルートを書いてみる

app.get('/x*/y', (c) => c.text('a'))
app.get('/x/*',  (c) => c.text('b'))

v5 の RegExpRouter

UnsupportedPathError: /x/*

• 両方を同時に登録できない

選ばれた Router

測った

GET /users/:id × 50,000回 × 12ラウンド

でも問題はそこじゃない

• 7〜10% は正直どうでもいい
• 問題は無言で切り替わること
• ログにも型にも出ない

マッチするハンドラも変わる

同じ競合ルートに /x/y を投げると

測った

GET /users/:id × 100,000回 × 10ラウンド

app.fetch() のインプロセス計測。実サーバーの性能ではない

分布が重なっている

• v4 の最小 258.31 ms
• v5 の中央値 266.50 ms
• → v4 の方が速いラウンドがある

敗因

• 最初 5ラウンドで測った → 差 2.9%
• 10ラウンドに増やした → 差 1.5%
• 同じコード、同じマシン、同じ日

わかったこと

• マイクロベンチで数%を語るなら

ラウンド数と分布を出す

• Router の方も 3ラウンド → 12ラウンドで

3.3% → 7.1% に変わった

インストールサイズ

npm registry の unpackedSize

3つの測り方が一致した

• npm registry → -46%
• 手元の du -sh（2.8M → 1.5M）→ -46%
• yusukebeさんの資料（1.29MB → 0.70MB）→ -46%

ファイル数 574 → 310 は完全一致

バンドルサイズ

考えてみれば当たり前

• 減ったのは CJS ビルドとアダプタの分離
• CJS はそもそもバンドルに入らない
• @hono/bun を入れれば同じコードが入る

v5 = AIのためのHono

抽象化されていて、選択肢が少ない

Yusuke Wada / Hono Conference 2026

なぜ型を厳しくするのか

• 人間は「ここは any だけど大丈夫」と空気を読む
• LLM は読まない
• 型が嘘をつけば、嘘のまま出てくる

defineHandler()

app.get('/ping', defineHandler(() => ({ pong: true })))

ping -> 200 {"pong":true}

• c.json() を呼んでいない
• 返した値が Response になる

検証も1か所で書ける

app.post('/users', defineHandler({ json: NameSchema })(
  (c, input) => ({ name: input.json.name.toUpperCase() })
))

400 {"error":"Validation failed","issues":[...]}

• Standard Schema → Zod / Valibot ...

ハマった

• 普通の検証関数で throw すると

400 ではなく 500 になる

• 400 にしてくれるのは Standard Schema のルートだけ

型定義のコメント

A JSON Response by c.json() is not accepted,
because it bypasses the response validation.

• c.json() を返すことを型で禁止している

移行チェックリスト

①まず tsc --strict を通す

• c.req.json() の直アクセス
• c.req.query() の分割代入
• onError((err, c) => ...)

→ 機械的に潰せる

移行チェックリスト

②型では捕まらない3つ

• c.json(undefined) → 500
• onError() の合成化 → 両方走る
• ワイルドカードのマッチ変更

→ ここが本番

移行チェックリスト

③import を書き換える

• hono/<runtime> → @hono/<runtime>
• hono/cloudflare-pages → 代替なし
• app.mount() → hono/mount
• app.fire() → @hono/service-worker

まとめ

• 型 → 嘘をつかなくなった。実行時の値は同じ
• エラー → 上書きから合成へ
• 地雷 → c.json(undefined) が 500
• ルーター → 統一された。でも無言で入れ替わる
• 性能 → 据え置き。ラウンド数を書こう
• サイズ → install は -46%、バンドルは微増

ひっくり返るとしたら

defineHandler() だと思う

• 唯一 experimental と明記されている
• 検証関数で 500 になる角が残っている
• onError() とワイルドカードはこのまま出る

一番詰まるのは

hono/cloudflare-pages の削除

• 他は書き換えれば済む
• これだけ代替がない
• 型エラーの数なら c.req.query() が圧倒的
• でも時間を食うのは数じゃなくて1件