Hono.js 경량 웹 프레임워크 입문 가이드 — Express 대안

Hono.js란 무엇인가 — Express와 무엇이 다른가

설치 및 프로젝트 생성

create-hono CLI로 프로젝트 생성
# npm
npm create hono@latest my-app

# pnpm
pnpm create hono@latest my-app

# bun
bun create hono@latest my-app

# 런타임 선택 프롬프트 예시
# ? Which template do you want to use?
#   cloudflare-workers
#   cloudflare-pages
#   vercel
#   deno
#   bun
#   nodejs
#   aws-lambda

Node.js 환경 직접 설치
npm install hono @hono/node-server

# TypeScript 사용 시
npm install -D typescript @types/node ts-node
npx tsc --init

Node.js 기본 서버 (src/index.ts)
import { Hono } from 'hono'
import { serve } from '@hono/node-server'

const app = new Hono()

app.get('/', (c) => c.text('Hello Hono!'))
app.get('/json', (c) => c.json({ status: 'ok', runtime: 'node' }))

serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log(`Server running at http://localhost:${info.port}`)
})

라우팅과 미들웨어 — 핵심 패턴 정리

라우팅 패턴 — 경로 파라미터, 와일드카드, 그룹
import { Hono } from 'hono'

const app = new Hono()

// 기본 HTTP 메서드
app.get('/posts', (c) => c.json({ posts: [] }))
app.post('/posts', async (c) => {
  const body = await c.req.json()
  return c.json({ created: body }, 201)
})

// 경로 파라미터
app.get('/posts/:id', (c) => {
  const id = c.req.param('id')
  return c.json({ id })
})

// 와일드카드
app.get('/files/*', (c) => c.text('file handler'))

// 라우트 그룹 (Hono 인스턴스 중첩)
const api = new Hono().basePath('/api')
api.get('/users', (c) => c.json({ users: [] }))
api.get('/users/:id', (c) => c.json({ id: c.req.param('id') }))

app.route('/', api)

미들웨어 — 로깅, 요청 시간, 커스텀
import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { timing } from 'hono/timing'
import { cors } from 'hono/cors'

const app = new Hono()

// 글로벌 미들웨어
app.use('*', logger())
app.use('*', timing())
app.use('/api/*', cors({ origin: 'https://example.com' }))

// 커스텀 미들웨어
app.use('*', async (c, next) => {
  const start = Date.now()
  await next()
  const elapsed = Date.now() - start
  c.res.headers.set('X-Response-Time', `${elapsed}ms`)
})

app.get('/', (c) => c.text('OK'))

Cloudflare Workers · Vercel Edge · Deno Deploy 배포

Cloudflare Workers 배포 (wrangler)
# 1. wrangler 설치
npm install -D wrangler

# 2. wrangler.toml 예시
# name = "my-hono-app"
# main = "src/index.ts"
# compatibility_date = "2024-01-01"

# 3. src/index.ts — CF Workers는 default export fetch 사용
import { Hono } from 'hono'
const app = new Hono()
app.get('/', (c) => c.text('Edge!'))
export default app

# 4. 로컬 개발
npx wrangler dev

# 5. 배포
npx wrangler deploy

Vercel Edge Functions 배포
# vercel.json
{
  "functions": {
    "api/**/*.ts": { "runtime": "edge" }
  }
}

# api/index.ts
import { Hono } from 'hono'
import { handle } from 'hono/vercel'

export const runtime = 'edge'

const app = new Hono().basePath('/api')
app.get('/hello', (c) => c.json({ message: 'Hello from Vercel Edge' }))

export const GET = handle(app)
export const POST = handle(app)

Deno Deploy 배포
# Deno는 별도 어댑터 없이 app.fetch 직접 사용
import { Hono } from 'npm:hono'

const app = new Hono()
app.get('/', (c) => c.text('Hello from Deno Deploy!'))

Deno.serve(app.fetch)

Zod OpenAPI 통합 및 JWT·CORS 미들웨어

Zod OpenAPI — 스키마 기반 라우트 정의
npm install @hono/zod-openapi zod

# src/app.ts
import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi'

const app = new OpenAPIHono()

const UserSchema = z.object({
  id: z.string().openapi({ example: 'user-123' }),
  name: z.string().openapi({ example: 'Alice' }),
})

const getUserRoute = createRoute({
  method: 'get',
  path: '/users/{id}',
  request: {
    params: z.object({ id: z.string() }),
  },
  responses: {
    200: { content: { 'application/json': { schema: UserSchema } }, description: 'User found' },
    404: { description: 'User not found' },
  },
})

app.openapi(getUserRoute, (c) => {
  const { id } = c.req.valid('param')
  return c.json({ id, name: 'Alice' }, 200)
})

// /doc 에서 OpenAPI JSON 제공
app.doc('/doc', { openapi: '3.1.0', info: { title: 'My API', version: '1.0.0' } })

JWT 인증 미들웨어
import { Hono } from 'hono'
import { jwt, sign, verify } from 'hono/jwt'

const app = new Hono()
const SECRET = process.env.JWT_SECRET ?? 'change-this-in-production'

// 토큰 발급 엔드포인트
app.post('/auth/login', async (c) => {
  const { username } = await c.req.json()
  const token = await sign({ sub: username, exp: Math.floor(Date.now() / 1000) + 3600 }, SECRET)
  return c.json({ token })
})

// 보호 라우트
app.use('/protected/*', jwt({ secret: SECRET }))
app.get('/protected/profile', (c) => {
  const payload = c.get('jwtPayload')
  return c.json({ user: payload.sub })
})

Express에서 Hono로 마이그레이션하는 법