Cursor plugin for Hono v4 (TypeScript edge web framework). 59 LLM regressions with BAD/CORRECT pairs. Pinned to hono ^4.12.19 (>= 4.9.7 for CVE-2025-59139). Covers Express middleware leakage, v3-era removed APIs, RPC inference traps, Cloudflare Workers gotchas, security defaults, JSX SSR hardening.
roninforge/roninforge-hono
Hono v4（TypeScript エッジ Web フレームワーク）+ TypeScript 向けの Cursor プラグイン。hono ^4.12.19、@hono/zod-validator ^0.8.0、@hono/zod-openapi ^1.4.0（peer zod ^4.x）、@hono/node-server ^2.0.3（Node 20+）に固定されています。2024 年より前のデータで学習した LLM が知らない v4 API（c.json() は常に型付き、バリデータは HTTPException をスロー、getCookie/setCookie は hono/cookie から、c.env はプロパティ、streamText は hono/streaming から、showRoutes は hono/dev から、getRuntimeKey は hono/adapter から、fire(app) は hono/service-worker から、Workers Static Assets バインディング（非推奨の serveStatic の代わり）、Deno 用の JSR @hono/hono）を教えます。BAD / CORRECT の TypeScript ペアで 50 以上の LLM の回帰をキャッチします。
Hono v5 は存在しません。 最新の安定版は v4.12.19 です。生成コード内の "v5" はすべて幻覚です。
Hono のメンテナー自身が Issue #3906（"llm.txt file"）と Issue #4812（"Official AI Agent Skill for Hono"）を提出した理由は、まさに 「LLM は最新の Hono の動作をほとんど知らない」 からです。2025 年より前のトレーニングデータは v3 時代のものです。LLM は以下を出力します。
c.jsonT() の代わりに c.json()（v4.0.0 以降は常に型付き）c.stream() / c.streamText() を Context のメソッドとして（v4 で hono/streaming に移動）c.env() 関数形式（現在はプロパティ；ランタイム検出は hono/adapter の getRuntimeKey() を使用）c.req.cookie()（削除されました；hono/cookie の getCookie(c) を使用）app.showRoutes(), app.routerName（hono/dev に移動）c.json() に return がない（undefined に解決；v4 では "Context is not finalized" がスローされる）c.json() の代わりに res.json() / res.send()（Hono に res はない）(req, res, next) ミドルウェアシグネチャ（(c, next) を使用）(err, req, res, next) エラーミドルウェア（app.onError + HTTPException を使用）app.use(express.json()) ボディパーサー（Hono は c.req.json() 経由でオンデマンドに解析）import cors from 'cors'（npm から。 を使用）new Hono() に Bindings / Variables ジェネリクスがない（c.env が {} になる）app.get(...) の後に app.post(...)） - RPC 型が失われるapp.route() 呼び出しを文として定義 - 同じルールContext を渡す（パスパラメータ推論が失われる。Hono ベストプラクティスによる）app.use('/path', zValidator(...)) をルート引数としてではなく使用（TS エラー：'json' は 'never' に代入できません）c.notFound()（クライアント側で型付け不可）new Response(JSON.stringify(...))（クライアントは を受け取る）process.env.X（undefined；型付き Bindings で c.env.X を使用）fs / path インポート（ファイルシステムなし）compatibility_flags: ["node_compat"] レガシーフラグ（nodejs_compat を使用）hono/cloudflare-workers からの非推奨 serveStatic（v4.3.0 以降；アセットバインディングを使用）c.executionCtx.waitUntil() の欠落（fire-and-forget 用）if (c.executionCtx) の真偽チェック（Bun と Next.js App Router でゲッターがスロー）.run() / .first() / （ワーカー終了時に挿入がキャンセルされる）secureHeaders() ミドルウェアがないcsrf() がないcors({ origin: '*', credentials: true })（ブラウザが静かにドロップ；AJAX が失敗）bodyLimit() がない、かつ hono >= 4.9.7 に固定していない（CVE-2025-59139）httpOnly / secure / sameSite / path なしのクッキーsameSite: 'None' かつ secure: true がない（静かにドロップされる）etag() / cache() がないnotFound ハンドラ（デッドコード；トップレベルのみが発火）/users と /users/ はデフォルトで別のルート）await next() を複数回呼び出す（ダウンストリームの作業が倍になる）app.use(prefix, mw) + app.route(prefix, subApp) の重複（ミドルウェアが 2 回発火）app.basePath('/api') を文として使用（プレフィックスが型から失われる）@hono/node-server で serve(app)（serve({ fetch: app.fetch }) を使用）export default app（export default { fetch: app.fetch } を使用）Bun.serve({ fetch: app })（app.fetch を使用）c.req.query() で単一の値を期待している場合c.req.param('id')（パスに :id がない場合 undefined）@hono/zod-openapi なしの手書き OpenAPIcors()（決して一致しない）cursor.directory と awesome-cursorrules（PR #152）にはすでにいくつかの Hono ルールがあります。これらは c.json() の戻り値、zValidator + Zod、Workers の c.env、RPC のチェーンルート、app.fetch Workers エクスポートをカバーしています。しかし、このプラグインが修正する 3 つの構造的な問題があります。
c.jsonT、c.stream、c.env()、c.req.cookie、app.showRoutes、hono/middleware バレル、app.handleEvent を出力します。これらはすべて v4.0.0（2024-02）で削除されました。既存のルールはそれらを静かに許可します。(req, res, next)、(err, req, res, next)、npm cors、app.use(express.json())、supertest、c.json の return 欠落 - これらはすべて LLM 生成の Hono コードで常に発生します。既存のルールはそれらを一回限りとして扱います。このプラグインが提供するもの：
globs 付き。ルート / RPC チェックは src/routes/**、Workers チェックは wrangler.{toml,jsonc} + Worker エントリ、セキュリティチェックはミドルウェアファイルなどに発火）/hono-new-route、/hono-rpc-setup、/hono-cloudflare-workers-setup、/hono-migrate-to-v4、/hono-validatecorrect-sample（ゴールドスタンダードの Hono 4.12.19 + Workers + D1 + Drizzle + Zod）と anti-pattern-sample（25 以上の追跡違反がある Hono v3 の後遺症）ルール、スキル、エージェントをプロジェクトの Cursor 設定にコピーします。まず既存のファイルをバックアップしてください。cp -r は同じ名前のルールを上書きします。
git clone https://github.com/RoninForge/roninforge-hono.git
# 既存のカスタマイズされた同じ名前のルールを上書きしないように -n を使用します。
cp -rn roninforge-hono/rules/* your-project/.cursor/rules/
cp -rn roninforge-hono/skills/* your-project/.cursor/skills/
cp -rn roninforge-hono/agents/* your-project/.cursor/agents/
または、リポジトリ全体を your-project/.cursor/plugins/ の下に git サブモジュールとしてベンダー化します。現在の Cursor バージョンのグローバルインストールパスについては、Cursor プラグインドキュメント を参照してください。
tests/fixtures/correct-sample/ はスリムな Hono 4.12.19 + Cloudflare Workers + D1 + Drizzle + Zod プロジェクトで、ゴールドスタンダードの形状を示しています：チェーンルート、型付き RPC、ルート引数としての zValidator、型付きレスポンス c.json({ ... } as const, status)、secureHeaders + cors + csrf + bodyLimit スタック、トップレベルの app.onError + app.notFound、export default { fetch: app.fetch } satisfies ExportedHandler<Env>。
tests/fixtures/anti-pattern-sample/ はその逆です。すべてのファイルが番号付きのアンチパターンに違反しています。package.json は意図的に hono ^3.12.0 + cors ^2.8.5 + supertest ^6.3.0 + @hono/sentry ^1.0.0 + lucia ^3.2.0 にピン留めされています。v3 時代はほとんどの 2025 年以前のモデルにおける LLM トレーニングデータのベースラインであり、LLM が今でも推奨する非推奨のコンパニオンも含まれています。追跡される違反には以下が含まれます：c.json の戻り値欠落（#1）、(req, res) Express ハンドラ形状（#2）、(req, res, next) ミドルウェア（#3）、(err, req, res, next)（#4）、npm cors（#6）、supertest（#12）、c.jsonT（#13）、addEventListener('fetch') + app.handleEvent（#15）、c.req.cookie（#16）、 関数呼び出し（#17）、 バレル（#20）、（#23）、Bindings/Variables なし（#24）、RPC ルート内の （#29）、Workers 内の （#34）、 フラグ（#36）、 からの （#37）、未 await の D1（#40）、cors + credentials（#43）、 なしのクッキー（#45）、 かつ なし（#46）、ハードコードされた JWT シークレット（#48）、サブアプリ （#50）、文としての （#53）、Workers での （#55）、非推奨の + 参照。
ルールは hono ^4.12.19 を対象とし、Node 20+（Node 上の場合）、Bun 最新、Deno 最新、Wrangler ^4.0.0 をサポートします。ほとんどのパターンは Hono 4.0.0（2024年2月）まで遡って動作し、差分はインラインで記載されています。ピンフロア：
hono >= 4.9.7 必須 - CVE-2025-59139 / GHSA-92vj-g62v-jqhh bodyLimit バイパス修正hono >= 4.12.18 JSX SSR をレンダリングする場合は必須 - タグ名、属性名、CSS インジェクションの強化@hono/node-server >= 2.0.0 には Node 20+ が必要@hono/zod-openapi >= 1.0.0 には zod ^4.0.0 が必要（peer は ^4.0.0 のみ、^3.x ではない）compatibility_date >= "2024-09-23" は nodejs_compat が nodejs_compat_v2 を暗示するために必要ルールがバージョンを引用している場合（c.json() は v4.0.0 以降常に型付き、c.text() は v4.3.0 以降型付き、Deno の JSR は v4.4.0 以降、secureHeaders Permissions-Policy は v4.6.0 以降、Standard Schema バリデータは v4.7.0 以降、fire(app) は v4.8.0 以降、JSR parseResponse は v4.9.0 以降、hc の型付きベース URL は v4.11.0 以降、$path() メソッドは v4.12.0 以降）、採用する前にインストールされているバージョンの変更ログを確認してください。
MIT - LICENSE を参照
RoninForge は、AI コーディングアシスタントを使用する開発者向けの無料ツールを構築しています。
addEventListener('fetch') + app.handleEvent()（Service Worker 構文；export default { fetch: app.fetch } を使用）app.head(...) ルート（v4 では HEAD は GET から自動派生）hono/nextjs インポート（hono/vercel を使用）hono/middleware バレルインポート（ミドルウェアごとのサブパスを使用）c.req.headers() / c.req.body() / c.req.signal() アクセサメソッド（c.req.raw.* を使用）FC 暗黙の children 付き（PropsWithChildren<P> を使用）app.fire()（v4.8.0 で非推奨；hono/service-worker の fire(app) を使用）import { Hono } from 'https://deno.land/x/hono/mod.ts'（Deno 上。v4.4.0 以降は古い；jsr:@hono/hono を使用）hono/corssupertest テスト用（app.request() / testClient(app) を使用）c.req.body をすでに解析済みとして扱う（ReadableStream です）c.req.parseBody() を JSON に使用（フォーム / multipart のみ）c.req.text() の後に c.req.json()（ボディが 2 回消費される）c.userId = ... インライン代入（c.set('userId', ...) と型付き Variables を使用）unknownhc<AppType>('/') 相対 URL（$url() でスロー）drizzle-orm、fs、ネイティブ依存を引きずる - RPC バンドル肥大化の最大の落とし穴）createMiddleware<Env> なしのミドルウェア（Variables 型が伝播しない）.all()streamText の代わりにメモリ内で大きな JSON を構築（Workers の 128MB 上限）secureHeaders() / csrf() を強制するものはなく、bodyLimit CVE-2025-59139（v4.9.7 で修正）に言及するものもなく、RPC クライアントの落とし穴（相対 URL、値インポートの漏洩、c.notFound の型付け）に対処するものもありません。| ルール | スコープ（globs） | 説明 |
|---|
hono-anti-patterns | **/*.ts,**/*.js,**/*.tsx,**/*.jsx,wrangler.{toml,jsonc,json} | 59 の LLM 回帰パターンと BAD / CORRECT ペア。カテゴリ A-H で整理（Express 漏洩、v3 時代の API、TypeScript / RPC、CF Workers、セキュリティ、ルーティング、ランタイム、小さな問題） |
hono-core | **/*.ts,**/*.tsx,**/*.js,**/*.jsx（alwaysApply） | 型付き Bindings + Variables によるアプリ初期化、Context API、リクエストアクセサ、ミドルウェアシグネチャ、組み込みミドルウェアリスト、クッキーヘルパー、ランタイム検出 |
hono-routing-and-rpc | src/**/*.ts,src/routes/**/*,src/api/**/*,src/server/**/*,src/client/**/*,routes/**/* | チェーンルート、サブアプリ構成、basePath の不変性、二重実行重複修正、サブアプリ notFound デッドコード、hc<AppType> セットアップ、import type ルール、型付きベース URL、$path()、TanStack Query / SWR 統合、factory.createHandlers、30 ルート以上での RPC 軽減 |
hono-validators | src/**/*.ts,routes/**/*.ts,api/**/*.ts,handlers/**/*.ts | @hono/zod-validator の配置、c.req.valid() アクセサ、バリデータは失敗時にスロー、@hono/zod-openapi（zod ^4 peer の注意点）、@hono/standard-validator、@hono/valibot-validator、組み込み hono/validator、決定木 |
hono-cloudflare-workers | src/**/*.ts,worker/**/*.ts,workers/**/*.ts,wrangler.{toml,jsonc,json},**/cloudflare-env.d.ts,**/worker-configuration.d.ts | wrangler.jsonc の正規形、互換性フラグルール、wrangler types、型付き Bindings、c.env と process.env の比較、c.executionCtx.waitUntil + 移植性、Static Assets バインディング、D1 の await、Drizzle + D1 スタック、Hyperdrive + Prisma アダプターの注意点、WebSocket 用 Durable Objects、hono/cache カスタムドメインルール、ES Module Worker エクスポート |
hono-security | src/**/*.ts,src/**/*.tsx,src/middleware/**/*.ts,src/auth/**/*.ts,src/index.ts,src/app.ts | secureHeaders()、csrf()、CORS 許可リスト、bodyLimit() + CVE-2025-59139 ピンフロア 4.9.7、クッキーデフォルト、JWT シークレットは c.env から、PII 漏洩のないログ、etag() + cache()、IP 制限、タイムアウト、リクエスト ID、認証ライブラリの決定（Lucia 非推奨；Better Auth / Clerk 推奨）、@sentry/hono が @hono/sentry より優先 |
hono-error-handling | src/**/*.ts,routes/**/*.ts,api/**/*.ts,middleware/**/*.ts,src/index.ts,src/app.ts | HTTPException の正規スロー、app.onError グローバルハンドラ、app.notFound はトップレベルのみ、識別共用体による型付き RPC エラー、バリデータスロー、@sentry/hono 経由の Sentry、pino 編集付き構造化ログ、エラーレスポンス形式の規約 |
hono-jsx | **/*.tsx,**/*.jsx,**/jsx-runtime.ts,src/components/**/*,src/views/**/*,src/islands/**/*,app/islands/**/* | hono/jsx サーバーサイド、tsconfig 設定、FC は children を含まない、レイアウト用 jsxRenderer ミドルウェア、Suspense 付き hono/jsx/streaming、hono/jsx/dom クライアントコンポーネント、HonoX アイランド、htmx 統合、JSX SSR セキュリティピンフロア 4.12.18 |
hono-testing | **/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,vitest.config.{ts,js},**/test/**/*.ts,**/tests/**/*.ts,**/__tests__/**/*.ts | app.request() ユニバーサルパターン、testClient(app) 型付き RPC テスト、Vitest + @cloudflare/vitest-pool-workers による実際のランタイム D1、applyD1Migrations フィクスチャ、Bun + bun:test、スナップショットテスト、ミドルウェア / バリデータ / waitUntil テスト、絶対に supertest を使わない |
hono-deployment | wrangler.{toml,jsonc,json},deno.json,deno.jsonc,package.json,Dockerfile,fly.toml,vercel.json,netlify.toml,**/serverless.yml,**/template.yaml | Cloudflare Workers（wrangler.jsonc + 互換性フラグ）、Bun.serve、Deno + JSR、@hono/node-server v2（Node 20+）、AWS Lambda + Lambda@Edge、Vercel Edge、Netlify、ビルドパイプライン、ピンフロア、一般的なデプロイの間違い |
| スキル | コマンド | 説明 |
|---|
| 新しいルート | /hono-new-route | ルート引数として zValidator、型付きアクセス c.req.valid()、型付き RPC レスポンス用 c.json({ ... } as const, status)、Bindings + Variables ジェネリクス、サブアプリを typeof users としてエクスポート、チェーン .route() で親に接続、というチェーンサブアプリをスキャフォールド。Rails スタイルのコントローラ、RPC ルート内の c.notFound()、生の new Response() を拒否。 |
| RPC セットアップ | /hono-rpc-setup | import type（負荷の高いルール）を使用した hc<AppType> クライアント、絶対ベース URL、型付き共有 api モジュール、InferRequestType / InferResponseType 経由の TanStack Query / SWR 統合、parseResponse ユーティリティ、$path() メソッド、30 ルート以上での IDE 速度低下軽減策をスキャフォールド。 |
| Workers セットアップ | /hono-cloudflare-workers-setup | 新しい Hono + Workers プロジェクトをスキャフォールド。wrangler.jsonc（.toml ではない）、nodejs_compat、wrangler types から生成された型付き Bindings、D1 + Drizzle ミドルウェアパターン、secureHeaders + cors + csrf + bodyLimit スタック、@cloudflare/vitest-pool-workers 用の Vitest 設定。 |
| v4 への移行 | /hono-migrate-to-v4 | 段階的な v3 -> v4 移行：ピンの引き上げ（CVE-2025-59139 フロア）、c.jsonT / c.stream / c.env() / c.req.cookie / app.showRoutes / app.handleEvent の置き換え、hono/middleware バレルの削除、Deno の JSR への切り替え、@hono/node-server v2 + Node 20+、バリデータスロー用の app.onError の登録。 |
| バリデーション | /hono-validate | validate-plugin.sh + tsc --noEmit + テスト + 型チェッカーがキャッチしない構文アンチパターン（c.jsonT、c.req.cookie、process.env、node_compat、hono/cloudflare-workers からの serveStatic、ハードコードされた JWT シークレット、secure なしの sameSite:'None'、bodyLimit の欠落、hc クライアントへの値インポート）の grep 監査を実行。 |
| エージェント | 説明 |
|---|
hono-reviewer | 重大度別に Hono v4 + TypeScript コードをレビュー。CRITICAL：hono < 4.9.7（CVE）、v5 参照（幻覚）、cors ワイルドカード + クレデンシャル、secure なしの sameSite:'None'、ハードコードされた JWT シークレット、Workers 内の process.env、bodyLimit の欠落、クッキー認証に csrf なし、非推奨の serveStatic、< 4.12.18 の JSX SSR。ERROR：c.json の戻り値欠落、Express ミドルウェア形状、すべての v3 時代の削除 API、チェーンされていないルート/サブアプリ、Rails コントローラ、zValidator の配置、RPC 内の c.notFound/生 Response、相対 URL hc()、値インポートサーバーアプリ、未 await の D1、ランタイムエクスポート形状。WARN：クッキーデフォルト、secureHeaders、編集なしの本文ログ、app.onError、サブアプリ notFound、c.executionCtx 真偽チェック、Bindings ジェネリクスなし、ルート後の cors、ミドルウェア重複、basePath 文、末尾スラッシュ、hono/middleware バレル、新規プロジェクトでの wrangler.toml、Lucia、@hono/sentry。NIT：satisfies ExportedHandler<Env> の欠落、手書き OpenAPI、observability.enabled の欠落。 |
c.env()hono/middlewareapp.head()c.notFoundprocess.envnode_compathono/cloudflare-workersserveStatic*httpOnly/secure/sameSite/pathsameSite:'None'secure:truenotFoundbasePathexport default app@hono/sentrylucia