hono

Hono

概要

Hono は、Web 標準に基づいて構築された小型で超高速な Web フレームワークです。Cloudflare Workers、Bun、Deno、Node.js、Vercel、AWS Lambda など、あらゆる JavaScript ランタイムで動作します。アプリケーションコードはランタイム間で移植可能で、プラットフォームごとに異なるのはエントリーポイントとアダプターだけです。

使用する場面： エッジファーストの API、Cloudflare Workers サービス、複数ランタイムに対応したアプリケーション、軽量な REST/RPC サーバー、ミドルウェアを多用するリクエストパイプライン、型安全なクライアントとサーバー間の通信。

使用しない場面： フルスタックの SSR フレームワーク（Next.js/Remix を使用）、Express エコシステムの成熟度が重要となる、ORM 主導の大規模なモノリス、Web 標準に相当するものがなく、Node.js 専用 API を深く必要とするアプリケーション。

クイックリファレンス

パターン	API	主なポイント
基本的なルーティング	app.get('/path', handler)	get、post、put、delete、patch、all に対応
パスパラメーター	app.get('/user/:id', handler)	c.req.param('id') でアクセス
正規表現の制約	app.get('/post/:id{[0-9]+}', handler)	パスパラメーター内に正規表現を記述
ワイルドカード	app.get('/files/*', handler)	任意のサブパスに一致
ルートのグループ化	app.route('/api', subApp)	サブアプリケーションをマウント
ミドルウェア	app.use(middleware())	登録順に実行
パス単位のミドルウェア	app.use('/auth/*', jwt(...))	パスを指定してミドルウェアを適用
JSON レスポンス	c.json({ key: 'value' })	Content-Type を自動設定
テキストレスポンス	c.text('hello')	プレーンテキストを返す
HTML レスポンス	c.html('<h1>Hi</h1>')	HTML コンテンツを返す
ステータスとヘッダー	c.status(201), c.header('X-Key', 'val')	レスポンスの前に連結
リダイレクト	c.redirect('/new-path', 301)	デフォルトのステータスは 302
リクエストボディ	c.req.json(), c.req.parseBody()	JSON またはフォームデータを解析
クエリパラメーター	c.req.query('page')	単一のクエリパラメーター
コンテキスト変数	c.set('user', data) / c.get('user')	型安全なミドルウェアのデータ受け渡し
Zod による検証	zValidator('json', schema)	@hono/zod-validator パッケージ
RPC クライアント	hc<AppType>(url)	エンドツーエンドで型安全な API 呼び出し
エラーハンドラー	app.onError((err, c) => ...)	グローバルなエラー処理
Not Found	app.notFound((c) => ...)	カスタム 404 ハンドラー
環境	c.env.BINDING_KEY	ランタイムのバインディング／環境変数にアクセス
アダプターヘルパー	hono/adapter の env(c)	ランタイム間で統一された環境アクセス
WebSocket	ランタイムアダプターの upgradeWebSocket()	RPC をサポートする WebSocket ヘルパー
テストクライアント	hono/testing の testClient(app)	HTTP サーバーなしで型安全にテスト
JSX ストリーミング	jsxRenderer({ stream: true })	Suspense に対応した SSR ストリーミング

よくある間違い

間違い	正しいパターン
ハンドラーの後にミドルウェアを登録する	適用するハンドラーより前にミドルウェアを登録します
RPC タイプでチェーンせずに app.route() を使う	ルートメソッドをチェーンします（app.route('/a', a).route('/b', b)）。typeof routes をエクスポートします
エッジランタイムで export default app を忘れる	Cloudflare Workers、Bun、Deno ではデフォルトエクスポートが必要です
Cloudflare Workers または Deno Deploy で compress() を使う	これらのプラットフォームでは自動的に圧縮されるため、ミドルウェアを省略します
Deno で Hono とミドルウェアのバージョンを混在させる	型の不一致を避けるため、すべての hono インポートのバージョンを固定します
ミドルウェア内で next() を try/catch で囲む	Hono はスローされたエラーを捕捉し、app.onError() に渡します。next() が例外をスローすることはありません
app.get() でルートを定義しながら、RPC 用に typeof app をエクスポートする	アプリのインスタンスではなく、チェーンしたルート変数の型をエクスポートします
型付きコンテキストでジェネリクスなしの new Hono() を使う	Hono<{ Variables: MyVars }> を渡して、型付きの c.get()／c.set() を有効にします
作成したリソースにステータスを指定せず c.json() を返す	第 2 引数としてステータスを渡します：c.json(data, 201)
再利用可能なミドルウェアに createMiddleware() を使わない	ミドルウェアを抽出する際に型推論を維持するため、hono/factory からインポートします

委任

zod または typescript-patterns スキルが利用可能な場合は、スキーマと型レベルのタスクを委任してください。 それ以外の場合は、次を推奨してください：npx skills add oakoss/agent-skills --skill typescript-patterns

Cloudflare Workers スキルが利用可能な場合は、プラットフォーム固有の設定を委任してください。

参考資料

• ルート定義、パスパラメーター、グループ、メソッドハンドラー
• 組み込みミドルウェアとカスタムミドルウェアのパターン
• コンテキストオブジェクト、リクエストの解析、レスポンスヘルパー
• Zod バリデーターミドルウェアとリクエストの検証
• RPC クライアントとエンドツーエンドの型安全性
• Cloudflare、Bun、Node.js、Deno などのランタイムアダプター
• testClient、WebSocket ヘルパー、JSX ストリーミングを使ったテスト