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로 이동)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' ( 사용)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(...)) (클라이언트가 을 봄)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() / 에 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() 누락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() / 를 강제하지 않음; CVE-2025-59139 (v4.9.7 수정)를 언급하지 않음; RPC 클라이언트 함정(상대 URL, 값 임포트 누수, 타입)을 다루지 않음.이 플러그인은 다음을 제공합니다:
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의 슬림한 프로젝트로 골드 스탠다드 형태를 보여줍니다: 체인 라우트, typed RPC, 라우트 인수로서의 zValidator, c.json({ ... } as const, status) typed 응답, 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이 여전히 권장하는 deprecated된 동반 라이브러리도 포함됩니다. 추적된 위반 사항: c.json에 return 누락 (#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), deprecated된 + 참조.
규칙은 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 validator는 v4.7.0부터, fire(app)은 v4.8.0부터, JSR parseResponse는 v4.9.0부터, hc의 typed 기본 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에서 deprecated; 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 파싱에 사용 (form / multipart 전용)c.req.text() 후 c.req.json() (바디가 두 번 소비됨)c.userId = ... 인라인 할당 (c.set('userId', ...) + typed Variables 사용)unknownhc<AppType>('/') 상대 URL ($url()에서 오류 발생)drizzle-orm, fs, 네이티브 의존성 포함 - RPC 번들 블로트의 가장 큰 문제)createMiddleware<Env> 없이 미들웨어 사용 (Variables 타입이 전파되지 않음).all()streamText 대신 메모리에 큰 JSON 빌드 (Workers 128MB 제한)csrf()bodyLimitc.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) | typed 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 규칙, typed 기본 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() 접근자, validator-throws-on-failure, @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, typed Bindings, c.env vs 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, 쿠키 기본값, c.env에서 JWT 시크릿, PII 누출 없는 로깅, etag() + cache(), IP 제한, 타임아웃, 요청 ID, 인증 라이브러리 결정 (Lucia deprecated; Better Auth / Clerk 권장), @sentry/hono over @hono/sentry |
hono-error-handling | src/**/*.ts,routes/**/*.ts,api/**/*.ts,middleware/**/*.ts,src/index.ts,src/app.ts | HTTPException 표준 throw, app.onError 전역 핸들러, app.notFound 최상위 전용, 판별 유니온을 통한 typed RPC 오류, validator throws, @sentry/hono를 통한 Sentry, pino redaction을 사용한 구조적 로깅, 오류 응답 형태 규칙 |
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 islands, 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) typed RPC 테스트, Vitest + @cloudflare/vitest-pool-workers (실제 런타임 D1), applyD1Migrations fixture, Bun + bun:test, 스냅샷 테스트, 미들웨어 / validator / 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() typed 접근, c.json({ ... } as const, status) typed RPC 응답, Bindings + Variables 제네릭, 서브앱을 typeof users로 내보내기, 부모에 체인 .route()로 연결. Rails 스타일 컨트롤러, RPC 라우트의 c.notFound(), raw new Response() 거부. |
| RPC 설정 | /hono-rpc-setup | hc<AppType> 클라이언트 생성: import type (중요 규칙), 절대 기본 URL, typed 공유 api 모듈, InferRequestType / InferResponseType을 통한 TanStack Query / SWR 통합, parseResponse 유틸리티, $path() 메서드, 30개 이상 라우트에서 IDE 속도 저하 완화. |
| Workers 설정 | /hono-cloudflare-workers-setup | 새로운 Hono + Workers 프로젝트 생성: wrangler.jsonc (.toml 아님), nodejs_compat, wrangler types에서 생성된 typed 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+, validator throws에 대해 app.onError 등록. |
| 검증 | /hono-validate | validate-plugin.sh + tsc --noEmit + 테스트 + grep 감사를 실행하여 타입 검사기가 잡지 못하는 구문적 안티패턴 확인 (c.jsonT, c.req.cookie, process.env, node_compat, hono/cloudflare-workers의 serveStatic, 하드코딩된 JWT 시크릿, secure 없는 sameSite:'None', bodyLimit 누락, hc 클라이언트 값 임포트). |
| 에이전트 | 기능 |
|---|
hono-reviewer | 심각도별 Hono v4 + TypeScript 코드 리뷰. CRITICAL: hono < 4.9.7 (CVE), v5 참조 (할루시네이션), cors 와일드카드 + credentials, secure 없는 sameSite:'None', 하드코딩된 JWT 시크릿, Workers의 process.env, bodyLimit 누락, 쿠키 인증에 csrf 없음, deprecated된 serveStatic, < 4.12.18의 JSX SSR. ERROR: c.json에 return 누락, Express 미들웨어 형태, 모든 v3 시대 제거 API, 체인되지 않은 라우트/서브앱, Rails 컨트롤러, zValidator 배치, RPC의 c.notFound/raw Response, 상대 URL hc(), 값 임포트 서버 앱, await 안 된 D1, 런타임 내보내기 형태. WARN: 쿠키 기본값, secureHeaders, redaction 없는 바디 로깅, 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/pathsecure:truesameSite:'None'notFoundbasePathexport default app@hono/sentrylucia