본문 바로가기
Q&A2026년 5월 28일2분 읽기

Hono 5.0 마이그레이션 — zValidator 빌드 에러 "type X is not assignable"

박
박지훈
조회 439댓글 4

Hono 4.5에서 5.0으로 올렸는데 기존 @hono/zod-validator 사용 코드가 모두 빌드 에러입니다.

// 이전 (4.5)
import { zValidator } from '@hono/zod-validator'
app.post('/items', zValidator('json', schema), async c => {
  const body = c.req.valid('json')
  return c.json(body)
})

에러:

error TS2769: No overload matches this call.
  Type '(c: Context, next: Next) => Promise<...>' is not assignable to type 'Handler'.

5.0에서는 zValidator를 어떻게 호출해야 하나요? README 예제는 builtin이라는데 import path가 명확하지 않습니다.

환경: Hono 5.0.0, Zod 4.0.2, TypeScript 5.7

댓글 4

김김영삼5개월 전

5.0에서 패턴이 바뀌었습니다. zValidator import는 불필요하고, schema를 미들웨어 자리에 직접 두면 됩니다.


import { Hono } from 'hono'
import { z } from 'zod'

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

app.post('/items', schema, async c => {
const body = c.req.valid('json') // 자동 추론
return c.json({ ok: true, body })
})

핵심 변화 — schema가 곧 미들웨어. 'json' 같은 target 인자도 자동 추론(GET이면 query, POST면 json).


target을 명시하고 싶을 때


app.post('/items', z.object({...}).optional(), { target: 'form' }, async c => {...})

또는 multipart upload 같은 특수 케이스:


import { validator } from 'hono/validator'
app.post('/upload', validator('form', (value) => {
// 커스텀 검증
return value
}), async c => {...})

Zod 4.0 breaking 같이 확인


5.0과 Zod 4를 묶어 올렸다면 schema.parse()의 객체 키 순서 처리가 미묘하게 다릅니다. .strict() 사용 위치도 변경. Zod 3에서 동작하던 일부 패턴이 4에서 escape 검증 실패. 마이그레이션 가이드의 migrate-from-3 섹션 한 번 훑어보세요.

풀풀스택지훈5개월 전

저도 같은 함정에 빠졌었는데 한 가지 추가하면 — 5.0에서는 middleware 순서가 더 엄격해졌습니다. onError와 notFound는 반드시 모든 route 정의 이후에 위치해야 합니다. 안 그러면 빌드는 통과하는데 런타임에서 catch가 안 됩니다.


// ❌ 5.0에서 위험
app.onError((err, c) => c.json({ error: err.message }, 500))
app.post('/items', schema, ...)

// ✅
app.post('/items', schema, ...)
app.onError((err, c) => c.json({ error: err.message }, 500))
hhono_user_lee(guest)5개월 전
RPC client 자동 codegen 패턴도 5.0에서 좀 달라졌어요. typeof app export하고 client 측에서 hc로 import할 때 generic 명시가 좀 더 엄격해진 느낌. 4.5 코드 그대로 가져오면 일부 endpoint에서 type 추론 깨집니다.
리리액트사랑(guest)5개월 전
3년 차 개발자인데 이런 깊은 답변 매번 도움 많이 됩니다. 책에서 안 나오는 실전 내용이 많아서 좋아요.
Ctrl+Enter로 등록