hono-routing

Hono ルーティングとミドルウェア

ステータス: 本番環境で使用可能 ✅ 最終更新日: 2025-11-21 依存関係: なし（フレームワーク非依存） 最新バージョン: [email protected]、[email protected]、[email protected]

---

クイックスタート（5 分）

インストール

bun add [email protected]  # preferred
# or: bun add [email protected]

Hono を選ぶ理由:

• 高速: Web 標準に基づいて構築され、あらゆる JavaScript ランタイムで動作します
• 軽量: 約 10 KB で、依存関係はありません
• 型安全: 型推論に対応した、完全な TypeScript サポート
• 柔軟: Cloudflare Workers、Deno、Bun、Node.js、Vercel で動作します

基本的なアプリ

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => {
  return c.json({ message: 'Hello Hono!' })
})

export default app

重要:

• レスポンスには c.json()、c.text()、c.html() を使用してください
• レスポンスを返してください（Express のように res.send() を使用しないでください）
• ランタイム用にアプリをエクスポートしてください

バリデーションの追加

bun add [email protected] @hono/[email protected]

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

const schema = z.object({
  name: z.string(),
  age: z.number(),
})

app.post('/user', zValidator('json', schema), (c) => {
  const data = c.req.valid('json')
  return c.json({ success: true, data })
})

---

重要なルール

常に行うこと

✅ ハンドラーからレスポンスを返す（c.json、c.text、c.html など）

✅ バリデーションミドルウェアの後に c.req.valid('source') を使用することで、型付けされたデータを取得します

✅ デプロイ用にアプリをエクスポートする（Cloudflare Workers、Bun、Deno、Node.js）

✅ 型安全なリクエストデータにはバリデーションミドルウェアを使用する（zValidator、vValidator）

✅ ミドルウェアで await next() を呼び出すことで、次のハンドラーに制御を渡します

✅ 予期されるエラーには HTTPException を使用する（適切な HTTP ステータスを返します）

✅ フックではなくテンプレートタグのバリデーターを使用する（zValidator、vValidator）

✅ カスタム変数にはコンテキスト型を定義する（Hono<{ Variables: { ... } }>）

✅ 大規模な API の整理にはサブアプリを使用する（app.route()）

✅ RPC ルートに型を付ける（クライアント用に export type AppType = typeof routes）

絶対に行わないこと

❌ ハンドラーからレスポンスを返し忘れないでください

❌ バリデーションなしで req.json() を直接使用しないでください。c.req.valid() を使用してください

❌ バリデーションフックとミドルウェアを混在させないでください。ミドルウェアのみを使用してください

❌ ミドルウェアで await next() を呼び忘れないでください。ミドルウェアチェーンが壊れます

❌ res.send() を使用しないでください。利用できません（c.json()、c.text() などを使用してください）

❌ エラーハンドリングを省略しないでください。グローバルハンドラーには app.onError() を使用してください

❌ バリデーションミドルウェアの後に、未検証のデータにアクセスしないでください

❌ ミドルウェアでブロッキング処理を使用しないでください。非同期チェーンが壊れます

❌ CORS のオリジンをハードコードしないでください。環境変数を使用してください

❌ RPC の型エクスポートを省略しないでください。クライアントで型を利用できなくなります

---

よくあるエラーの上位 5 件（全 12 件については references/top-errors.md を参照）

エラー #1: ミドルウェアのレスポンスに型が付かない

問題: ミドルウェアがレスポンスを返しても、ルートハンドラーが実行されます 解決策: チェーンを続行したい場合はミドルウェアから return しないでください。変数の設定のみを行います

// ❌ Wrong - breaks chain
app.use('*', (c) => {
  return c.json({ error: 'Unauthorized' }, 401)
})

// ✅ Correct - throw HTTPException instead
app.use('*', (c, next) => {
  if (!isAuthorized) {
    throw new HTTPException(401, { message: 'Unauthorized' })
  }
  await next()
})

エラー #2: バリデーションフックとミドルウェアの混同

問題: ミドルウェアではなくバリデーションフックを使用しています 解決策: 常にミドルウェアのバリデーター（zValidator、vValidator）を使用してください

// ❌ Wrong - hooks deprecated
app.post('/user', (c) => {
  const data = c.req.json<User>() // No runtime validation!
})

// ✅ Correct - middleware with runtime validation
app.post('/user', zValidator('json', schema), (c) => {
  const data = c.req.valid('json') // Validated & typed!
})

エラー #3: ミドルウェアで await next() がない

問題: ミドルウェアが next() を呼び出さず、チェーンが途切れます 解決策: 早期に return する場合を除き、常に await next() を呼び出してください

// ❌ Wrong - chain broken
app.use('*', (c) => {
  console.log('Log')
  // Missing await next()!
})

// ✅ Correct
app.use('*', async (c, next) => {
  console.log('Log')
  await next()
})

エラー #4: コンテキスト変数の型推論

問題: c.get() と c.set() に型が付いていません 解決策: Hono コンストラクターで Variables 型を定義してください

// ❌ Wrong - no types
const app = new Hono()
c.set('user', { id: '123' }) // Not typed
const user = c.get('user') // any

// ✅ Correct - typed
type Variables = {
  user: { id: string; name: string }
}
const app = new Hono<{ Variables: Variables }>()
c.set('user', { id: '123', name: 'Alice' })
const user = c.get('user') // Fully typed!

エラー #5: RPC の型推論が機能しない

問題: クライアントでサーバーのルートの型を利用できません 解決策: AppType をエクスポートし、hc を使用してください

// Server
const routes = app.get('/users', (c) => c.json([]))
export type AppType = typeof routes // Export this!

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

const client = hc<AppType>('http://localhost:8787') // Fully typed!

詳細な解決策を含む全 12 件のエラーについては、references/top-errors.md を読み込んでください。

---

よくあるユースケース

ユースケース 1: 基本的な REST API

用途: シンプルな CRUD 操作 簡易パターン:

app.get('/users', (c) => c.json({ users: [] }))
app.post('/users', (c) => c.json({ created: true }))
app.get('/users/:id', (c) => c.json({ user: {} }))
app.put('/users/:id', (c) => c.json({ updated: true }))
app.delete('/users/:id', (c) => c.json({ deleted: true }))

読み込む内容: references/setup-guide.md → 完全な例

ユースケース 2: リクエストのバリデーション（Zod）

用途: 型安全なリクエストのバリデーションが必要な場合 簡易パターン:

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

app.post('/user',
  zValidator('json', z.object({
    name: z.string(),
    email: z.email(),
  })),
  (c) => {
    const data = c.req.valid('json') // Typed!
    return c.json(data)
  }
)

読み込む内容: references/validation-libraries.md

ユースケース 3: 型安全な RPC

用途: 型を共有するフルスタック TypeScript 読み込む内容: references/rpc-guide.md + templates/rpc-pattern.ts

ユースケース 4: ミドルウェアの合成

用途: 認証、ロギング、レート制限 読み込む内容: references/middleware-catalog.md + templates/middleware-composition.ts

ユースケース 5：カスタムコンテキスト変数

使用する場面：ミドルウェアとルート間でデータを共有する場合 読み込むファイル：templates/context-extension.ts

---

リファレンスを読み込むタイミング

references/setup-guide.md を読み込む場合：

• ユーザーがセットアップの手順全体を必要としている
• ユーザーが異なるランタイムへのデプロイについて質問している
• ユーザーが CRUD API の例を必要としている
• ユーザーが別のバリデーター（Valibot、ArkType、Typia）を試したい

references/top-errors.md を読み込む場合：

• ドキュメントに記載されている 12 個のエラーのいずれかが発生している
• ユーザーがミドルウェアの型の問題を抱えている
• ユーザーがバリデーションフックとミドルウェアの違いに混乱している
• ユーザーがトラブルシューティングやデバッグを必要としている

references/common-patterns.md を読み込む場合：

• ユーザーがコード例やベストプラクティスを求めている
• ユーザーがルートのグループ化、エラー処理、ファイルアップロードのパターンを必要としている
• ユーザーがストリーミング、WebSocket、ページネーションの例を求めている

references/middleware-catalog.md を読み込む場合：

• ユーザーが組み込みミドルウェア（cors、logger、jwt、cache、compress、etag）を必要としている
• ユーザーがカスタムミドルウェアを作成したい
• ユーザーが認証または認可について質問している

references/rpc-guide.md を読み込む場合：

• ユーザーがフルスタックの TypeScript アプリを構築している
• ユーザーが型安全なクライアント／サーバー間通信を求めている
• ユーザーが hono/client または RPC のパターンについて質問している

references/validation-libraries.md を読み込む場合：

• ユーザーが Zod、Valibot、ArkType、Typia を比較している
• ユーザーが各ライブラリのバリデーション例を必要としている
• ユーザーがパフォーマンスやバンドルサイズについて質問している

---

設定リファレンス

最小構成の設定

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => c.json({ message: 'Hello' }))

export default app

本番環境向けの設定

import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { HTTPException } from 'hono/http-exception'

type Variables = {
  user: { id: string; name: string }
  requestId: string
}

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

// Global middleware
app.use('*', logger())
app.use('*', async (c, next) => {
  c.set('requestId', crypto.randomUUID())
  await next()
})

app.use('*', cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
  credentials: true,
}))

// Routes
app.route('/api', apiRoutes)

// Global error handler
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return c.json(
      { error: err.message },
      err.status
    )
  }

  console.error(err)
  return c.json(
    { error: 'Internal Server Error' },
    500
  )
})

// 404 handler
app.notFound((c) => {
  return c.json({ error: 'Not Found' }, 404)
})

export default app

---

同梱リソースの使用

リファレンス（references/）

• setup-guide.md - 6 ステップの完全なセットアップ（インストール → デプロイ）
• top-errors.md - 解決策付きの 12 個すべてのエラー
• common-patterns.md - 7 つの本番環境向けパターン（RPC、ミドルウェア、エラー処理、ファイルアップロード）
• middleware-catalog.md - 組み込みミドルウェアのリファレンス（cors、logger、jwt、cache）
• rpc-guide.md - 型安全な RPC クライアント／サーバーガイド
• validation-libraries.md - Zod、Valibot、ArkType、Typia の比較

テンプレート（templates/）

• routing-patterns.ts - ルートの例（パラメーター、クエリ、ワイルドカード、グループ化）
• validation-zod.ts - Zod のバリデーション例
• validation-valibot.ts - Valibot のバリデーション例
• middleware-composition.ts - 認証、レート制限、ロギングのミドルウェア
• error-handling.ts - HTTPException とグローバルエラーハンドラー
• context-extension.ts - カスタムコンテキスト変数
• rpc-pattern.ts - RPC サーバーのセットアップ
• rpc-client.tsx - RPC クライアントの使用方法
• package.json - 依存関係の設定

---

依存関係

必須：

• hono@^4.12.12 - コアフレームワーク

バリデーターを 1 つ選択（推奨）：

• zod@^4.3.6 + @hono/zod-validator@^0.7.4（最も人気）
• valibot@^1.1.0 + @hono/valibot-validator@^0.6.1（バンドルサイズが小さい）
• arktype@^2.0.0 + @hono/arktype-validator@^0.1.0（実行時の速度が最速）
• typia@^7.0.0 + @hono/typia-validator@^0.1.0（コンパイル時のバリデーション）

任意：

• @hono/node-server - Node.js アダプター
• @cloudflare/workers-types - Workers 用の TypeScript 型

---

公式ドキュメント

• Hono：https://hono.dev
• GitHub：https://github.com/honojs/hono (17.8k ⭐)
• API リファレンス：https://hono.dev/docs/api/hono
• ルーティング：https://hono.dev/docs/api/routing
• ミドルウェア：https://hono.dev/docs/guides/middleware
• バリデーション：https://hono.dev/docs/guides/validation
• RPC：https://hono.dev/docs/guides/rpc
• 例：https://github.com/honojs/hono/tree/main/examples

---

比較：Hono とその他の選択肢

機能	Hono	Express	Fastify
サイズ	約10KB	約200KB	約100KB
TypeScript	✅ ネイティブ	⚠️ 型定義	✅ ネイティブ
型推論	✅ 完全	❌ なし	⚠️ 限定的
RPC	✅ 組み込み	❌ なし	❌ なし
エッジランタイム	✅ 対応	❌ 非対応	❌ 非対応
バリデーション	✅ プラグイン	⚠️ 手動	✅ プラグイン
速度	非常に高速	高速	非常に高速

推奨事項：

• Hono を使う場合：TypeScript、エッジランタイム、完全な型推論、小さなバンドルが必要なとき
• Express を使う場合：レガシーな Node.js アプリや、大規模なエコシステムが必要なとき
• Fastify を使う場合：Node.js のみを使用し、最速の Node.js フレームワークが必要なとき

---

本番環境での使用例

動作確認済みプロジェクト：

1. Cloudflare Workers API：https://github.com/honojs/examples/tree/main/cloudflare-workers
2. Bun REST API：https://github.com/honojs/examples/tree/main/bun
3. Deno API：https://github.com/honojs/examples/tree/main/deno
4. Node.js API：https://github.com/honojs/examples/tree/main/nodejs

---

セキュアなインストール

Hono とミドルウェアパッケージをインストールする際は、サプライチェーンセキュリティのベストプラクティスに従ってください。

• インストール後スクリプトをブロック — npm config set ignore-scripts true（または Bun：デフォルトで無効）
• クールダウン期間 — 新しいパッケージバージョンがコミュニティによって審査されるまで、7 日間待ちます
• インストール前に監査 — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認します

Socket CLI の統合、クールダウンの設定、ロックファイルの検証、CI での適用を含むセキュリティ設定の全手順については、dependency-upgrade スキルを読み込んでください。

セットアップ完了チェックリスト

• Hono をインストールした（bun add hono）
• バリデーターをインストールした（Zod、Valibot、ArkType、または Typia）
• ルートを含む基本的なアプリを作成した
• ルートにバリデーションミドルウェアを追加した
• クロスオリジンリクエスト用に CORS を設定した
• グローバルエラーハンドラーを追加した（app.onError）
• 404 ハンドラーを追加した（app.notFound）
• カスタム変数用のコンテキスト型を設定した
• ローカルでルートをテストした
• 対象のランタイム（Cloudflare、Bun、Deno、Node.js）にデプロイした

---

質問や問題がありますか？

1. 12 個すべてのエラーと解決策については、references/top-errors.md を確認してください
2. セットアップの全手順については、references/setup-guide.md を参照してください
3. 本番環境でのパターンについては、references/common-patterns.md をご覧ください
4. 組み込みミドルウェアについては、references/middleware-catalog.md を確認してください
5. 型安全なクライアント／サーバーについては、references/rpc-guide.md をご覧ください
6. 公式ドキュメントを確認してください：https://hono.dev