Hono v4(TypeScript 엣지 웹 프레임워크)용 Cursor 플러그인. BAD/CORRECT 쌍이 있는 59개의 LLM 회귀. hono ^4.12.19(>= 4.9.7, CVE-2025-59139용)에 고정됨. Express 미들웨어 누출, v3 시대 제거 API, RPC 추론 함정, Cloudflare Workers 주의 사항, 보안 기본값, JSX SSR 강화를 다룹니다.
Hono v4 (TypeScript 엣지 웹 프레임워크) + 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()은 항상 타입이 지정됨, validator는 HTTPException을 throw, getCookie/setCookie는 hono/cookie에서, c.env는 속성, streamText는 hono/streaming에서, showRoutes는 hono/dev에서, getRuntimeKey는 hono/adapter에서, fire(app)은 hono/service-worker에서, Workers Static Assets 바인딩은 deprecated된 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로 이동)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에서 deprecated; hono/service-worker의 fire(app) 사용)import { Hono } from 'https://deno.land/x/hono/mod.ts' Deno에서 (v4.4.0 이후 구식; jsr:@hono/hono 사용)c.json()에 return 누락 (undefined로 resolve, v4는 "Context is not finalized" throw)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' (hono/cors 사용)supertest (app.request() / testClient(app) 사용)c.req.body 가 이미 파싱된 것으로 간주 (실제로는 ReadableStream)c.req.parseBody() 를 JSON 파싱에 사용 (form / multipart 전용)c.req.text() 후 c.req.json() (바디가 두 번 소비됨)c.userId = ... 인라인 할당 (c.set('userId', ...) + typed Variables 사용)Bindings / Variables 제네릭 없이 new Hono() (c.env는 {})app.get(...) 다음 app.post(...)) - RPC 타입 손실app.route() 호출을 명령문으로 - 동일한 규칙Context 전달 (경로 매개변수 추론 손실, Hono Best Practices 참고)app.use('/path', zValidator(...)) (TS 오류: 'json'을 'never'에 할당할 수 없음)c.notFound() (클라이언트에서 타입 지정 불가)new Response(JSON.stringify(...)) (클라이언트가 unknown을 봄)hc<AppType>('/') 상대 URL ($url()에서 오류 발생)drizzle-orm, fs, 네이티브 의존성 포함 - RPC 번들 블로트의 가장 큰 문제)createMiddleware<Env> 없이 미들웨어 사용 (Variables 타입이 전파되지 않음)process.env.X (undefined; typed Bindings와 함께 c.env.X 사용)fs / path 임포트 (파일시스템 없음)compatibility_flags: ["node_compat"] (nodejs_compat 사용)hono/cloudflare-workers의 deprecated된 serveStatic (v4.3.0 이후; asset 바인딩 사용)c.executionCtx.waitUntil() 누락 (fire-and-forget)if (c.executionCtx) (Bun 및 Next.js App Router에서 getter가 오류 발생).run() / .first() / .all()에 await 누락 (워커 종료 시 삽입 취소)secureHeaders() 미들웨어 누락csrf() 누락cors({ origin: '*', credentials: true }) (브라우저가 조용히 드롭; AJAX 실패)bodyLimit() 누락 및 hono >= 4.9.7로 고정 (CVE-2025-59139 대응)httpOnly / secure / sameSite / path 없는 쿠키secure: true 없이 sameSite: 'None' (조용히 드롭됨)etag() / cache() 누락streamText 대신 메모리에 큰 JSON 빌드 (Workers 128MB 제한)notFound 핸들러 (데드 코드; 최상위만 작동)/users와 /users/는 기본적으로 다른 라우트)await next()를 두 번 이상 호출 (다운스트림 작업이 중복)app.use(prefix, mw) + app.route(prefix, subApp) 겹침 (미들웨어가 두 번 실행)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 없이)cors() 마운트 (일치하지 않음)이미 cursor.directory와 awesome-cursorrules (PR #152)에 몇 가지 Hono 규칙이 있습니다: c.json() 반환, zValidator + Zod, Workers용 c.env, RPC용 체인 라우트, app.fetch Workers 내보내기를 다룹니다. 하지만 이 플러그인이 해결하는 세 가지 구조적 문제가 있습니다:
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 코드에서 지속적으로 발생. 기존 규칙은 일회성으로 처리합니다.secureHeaders() / csrf()를 강제하지 않음; bodyLimit CVE-2025-59139 (v4.9.7 수정)를 언급하지 않음; RPC 클라이언트 함정(상대 URL, 값 임포트 누수, c.notFound 타입)을 다루지 않음.이 플러그인은 다음을 제공합니다:
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 플러그인 문서를 참조하세요.