시작하기

Hono를 사용하는 방법은 매우 간단하다. 프로젝트를 설정하고, 코드를 작성하고, 로컬 서버에서 개발한 후 빠르게 배포할 수 있다. 동일한 코드가 다른 런타임에서도 작동하며, 단지 엔트리 포인트만 다르다. Hono의 기본 사용법을 살펴보자.

시작하기

각 플랫폼별로 스타터 템플릿을 제공한다. 아래 "create-hono" 커맨드를 사용해 보자.

npm create hono@latest my-app

yarn create hono my-app

pnpm create hono@latest my-app

bun create hono@latest my-app

deno init --npm hono@latest my-app

그러면 사용할 템플릿을 선택하라는 메시지가 나타난다. 이 예제에서는 Cloudflare Workers를 선택한다.

? Which template do you want to use?
    aws-lambda
    bun
    cloudflare-pages
❯   cloudflare-workers
    deno
    fastly
    nextjs
    nodejs
    vercel

템플릿이 my-app 디렉토리에 다운로드된다. 해당 디렉토리로 이동해 의존성을 설치한다.

npmyarnpnpmbun

cd my-app
npm i

cd my-app
yarn

cd my-app
pnpm i

cd my-app
bun i

패키지 설치가 완료되면, 아래 커맨드를 실행해 로컬 서버를 시작한다.

npmyarnpnpmbun

npm run dev

yarn dev

pnpm dev

bun run dev

Hello World

Cloudflare Workers 개발 도구인 "Wrangler", Deno, Bun 등을 사용하면 트랜스파일링을 의식하지 않고도 TypeScript로 코드를 작성할 수 있다.

src/index.ts 파일에 첫 번째 Hono 애플리케이션을 작성해보자. 아래 예제는 Hono 애플리케이션을 시작하기 위한 기본 코드다.

import와 마지막의 export default 부분은 런타임에 따라 다를 수 있지만, 애플리케이션 코드는 어디서든 동일하게 실행된다.

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => {
  return c.text('Hello Hono!')
})

export default app

개발 서버를 시작하고 브라우저에서 http://localhost:8787에 접속해보자.

npmyarnpnpmbun

npm run dev

yarn dev

pnpm dev

bun run dev

JSON 반환

JSON을 반환하는 것도 쉽다. 다음은 /api/hello에 대한 GET 요청을 처리하고 application/json 응답을 반환하는 예제다.

app.get('/api/hello', (c) => {
  return c.json({
    ok: true,
    message: 'Hello Hono!',
  })
})

요청과 응답

경로 매개변수, URL 쿼리 값을 가져오고, 응답 헤더를 추가하는 코드는 다음과 같이 작성한다.

app.get('/posts/:id', (c) => {
  const page = c.req.query('page')
  const id = c.req.param('id')
  c.header('X-Message', 'Hi!')
  return c.text(`You want to see ${page} of ${id}`)
})

GET뿐만 아니라 POST, PUT, DELETE도 쉽게 처리할 수 있다.

app.post('/posts', (c) => c.text('Created!', 201))
app.delete('/posts/:id', (c) =>
  c.text(`${c.req.param('id')} is deleted!`)
)

HTML 반환하기

html 헬퍼를 사용하거나 JSX 문법으로 HTML을 작성할 수 있다. JSX를 사용하려면 파일명을 src/index.tsx로 변경하고 각 런타임에 맞게 설정한다. 아래는 JSX를 사용한 예제다.

tsx

const View = () => {
  return (
    <html>
      <body>
        <h1>Hello Hono!</h1>
      </body>
    </html>
  )
}

app.get('/page', (c) => {
  return c.html(<View />)
})

원시 Response 반환

Response 객체를 직접 반환할 수도 있다.

app.get('/', () => {
  return new Response('Good morning!')
})

미들웨어 사용하기

미들웨어는 여러분 대신 힘든 작업을 처리할 수 있다. 예를 들어, 기본 인증 기능을 추가할 수 있다.

import { basicAuth } from 'hono/basic-auth'

// ...

app.use(
  '/admin/*',
  basicAuth({
    username: 'admin',
    password: 'secret',
  })
)

app.get('/admin', (c) => {
  return c.text('You are authorized!')
})

Hono는 Bearer 인증, JWT를 사용한 인증, CORS, ETag 등 유용한 내장 미들웨어를 제공한다. 또한 GraphQL 서버나 Firebase Auth와 같은 외부 라이브러리를 활용한 서드파티 미들웨어도 지원한다. 필요에 따라 직접 커스텀 미들웨어를 만들 수도 있다.

어댑터

플랫폼 의존적인 기능을 처리하기 위해 어댑터를 사용한다. 예를 들어 정적 파일 처리나 WebSocket 처리가 여기에 해당한다. Cloudflare Workers에서 WebSocket을 처리하려면 hono/cloudflare-workers를 임포트한다.

import { upgradeWebSocket } from 'hono/cloudflare-workers'

app.get(
  '/ws',
  upgradeWebSocket((c) => {
    // ...
  })
)

다음 단계

대부분의 코드는 모든 플랫폼에서 동작하지만, 각 플랫폼별로 가이드가 제공된다. 예를 들어 프로젝트 설정 방법이나 배포 방법 등이 있다. 애플리케이션을 만들고자 하는 특정 플랫폼에 대한 정확한 정보는 해당 페이지를 참고한다!

시작하기 ​

시작하기 ​

Hello World ​

JSON 반환 ​

요청과 응답 ​

HTML 반환하기 ​

원시 Response 반환 ​

미들웨어 사용하기 ​

어댑터 ​

다음 단계 ​

시작하기

시작하기

Hello World

JSON 반환

요청과 응답

HTML 반환하기

원시 Response 반환

미들웨어 사용하기

어댑터

다음 단계