はじめに

Hono はとても簡単に使えます。プロジェクトのセットアップ、コードの作成、ローカルサーバーでの開発、デプロイをすばやく行えます。同じコードがどのランタイムでも動作し、必要なのは異なるエントリーポイントだけです。Hono の基本的な使い方を見ていきましょう。

スターターテンプレート

各プラットフォーム向けのスターターテンプレートがあります。次の「create-hono」コマンドを使います。

npm

npm create hono@latest my-app

yarn

yarn create hono my-app

pnpm

pnpm create hono@latest my-app

bun

bun create hono@latest my-app

deno

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 に取得されるので、そのディレクトリに移動して依存関係をインストールします。

npm

cd my-app
npm i

yarn

cd my-app
yarn

pnpm

cd my-app
pnpm i

bun

cd my-app
bun i

パッケージのインストールが完了したら、次のコマンドでローカルサーバーを起動します。

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

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 にアクセスします。

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

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 を使う例です。

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!')
})

ミドルウェアの使用

ミドルウェアを使うと、手間のかかる処理を任せられます。 たとえば、Basic 認証を追加できます。

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

// ...

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

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

Bearer や JWT による認証、CORS、ETag など、便利な組み込みミドルウェアがあります。 Hono は GraphQL Server や Firebase Auth などの外部ライブラリーを利用するサードパーティのミドルウェアも提供しています。 独自のミドルウェアを作成することもできます。

アダプター

静的ファイルの処理や WebSocket など、プラットフォームに依存する機能にはアダプターがあります。 アダプターは個別のパッケージとして公開されています。たとえば、Cloudflare Workers で WebSocket を扱うには、@hono/cloudflare-workers をインストールしてインポートします。

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

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

次のステップ

ほとんどのコードはどのプラットフォームでも動作しますが、プラットフォームごとのガイドも用意されています。 プロジェクトのセットアップやデプロイ方法などを説明しています。 アプリケーションの作成に使いたいプラットフォームのページを参照してください。