Hono

Appearance

Cloudflare Workers ​

Cloudflare Workers は Cloudflare の CDN で JavaScript を実行するエッジランタイムです。

アプリケーションをローカルで開発し、 Wrangler のいくつかのコマンドを使用して公開します。 Wrangler はコンパイラを内蔵しているため、 TypeScript でコードを書けます。

Hono を使った Cloudflare Workers 最初のアプリケーションを作りましょう。

1. セットアップ ​

Cloudflare Workers 向けのスターターが使用できます。 "create-hono" コマンドでプロジェクトを作成してください。 cloudflare-workers テンプレートを選択します。

sh
npm create hono@latest my-app
sh
yarn create hono my-app
sh
pnpm create hono my-app
sh
bun create hono@latest my-app
sh
deno init --npm hono my-app

my-app に移動し、依存関係をインストールします。

sh
cd my-app
npm i
sh
cd my-app
yarn
sh
cd my-app
pnpm i
sh
cd my-app
bun i

2. Hello World ​

src/index.ts をこのように変更します。

ts
import { Hono } from 'hono'
const app = new Hono()

app.get('/', (c) => c.text('Hello Cloudflare Workers!'))

export default app

3. Run ​

ローカル開発サーバーを起動し、ブラウザで http://localhost:8787 にアクセスします。

sh
npm run dev
sh
yarn dev
sh
pnpm dev
sh
bun run dev

ポート番号を変える ​

ポート番号を変える必要がある場合は、 wrangler.toml / wrangler.json / wrangler.jsonc を以下のドキュメントに従って変更してください: Wrangler Configuration

もしくは CLI オプションで設定することもできます: Wrangler CLI

4. デプロイ ​

Cloudflare アカウントを持っている場合、 Cloudflare にデプロイ出来ます。 package.json の $npm_execpath を選択したパッケージマネージャに置き換える必要があります。

sh
npm run deploy
sh
yarn deploy
sh
pnpm run deploy
sh
bun run deploy

それだけです!

他のイベントハンドラとともに Hono を使う ​

Module Worker モード で他のイベントハンドラ ( scheduled など ) を統合できます。

このように、 app.fetch を fetch ハンドラとしてエクスポートし、必要に応じて他のハンドラも実装します:

ts
const app = new Hono()

export default {
  fetch: app.fetch,
  scheduled: async (batch, env) => {},
}

静的ファイルの提供 ​

静的ファイルを提供したい場合、 Cloudflare Workers の Static Assets 機能 を使うことができます。 wrangler.jsonc でファイルを置くディレクトリを指定します:

jsonc
"assets": { "directory": "public" }

次に public ディレクトリを作成し、ファイルを設置します. 例えば、 ./public/static/hello.txt は /static/hello.txt として提供されます。

.
├── package.json
├── public
│   ├── favicon.ico
│   └── static
│       └── hello.txt
├── src
│   └── index.ts
└── wrangler.jsonc

型 ​

Workers の型が欲しい場合は @cloudflare/workers-types をインストールする必要があります。

sh
npm i --save-dev @cloudflare/workers-types
sh
yarn add -D @cloudflare/workers-types
sh
pnpm add -D @cloudflare/workers-types
sh
bun add --dev @cloudflare/workers-types

テスト ​

テストのために @cloudflare/vitest-pool-workers が推奨されます。 例を読んで設定してください。

このようなアプリケーションに対して

ts
import { Hono } from 'hono'

const app = new Hono()
app.get('/', (c) => c.text('Please test me!'))

このコードを使用して "200 OK" レスポンスが返されるかをテストします。

ts
describe('Test the application', () => {
  it('Should return 200 response', async () => {
    const res = await app.request('http://localhost/')
    expect(res.status).toBe(200)
  })
})

バインディング ​

Cloudflare Workers では環境変数、 KV ネームスペース、 R2 バケット、 Durable Object などをバインドし、 c.env からアクセスできます。 Hono のジェネリクスとしてバインディングの型定義を渡します。

ts
type Bindings = {
  MY_BUCKET: R2Bucket
  USERNAME: string
  PASSWORD: string
}

const app = new Hono<{ Bindings: Bindings }>()

// Access to environment values
app.put('/upload/:key', async (c, next) => {
  const key = c.req.param('key')
  await c.env.MY_BUCKET.put(key, c.req.body)
  return c.text(`Put ${key} successfully!`)
})

自動的にバインディングの型を生成する ​

手動でバインディングの型を定義する代わりに、 wrangler types コマンドを使用して、 wrangler.toml から自動生成することができます。 Hono のビルトインである Env 型との名前の衝突を避けるために --env-interface フラグを使用してください。

sh
wrangler types --env-interface CloudflareBindings

指定したインタフェース名をもつ worker-configuration.d.ts ファイルを生成します。 これを Hono に渡します:

ts
const app = new Hono<{ Bindings: CloudflareBindings }>()

app.put('/upload/:key', async (c, next) => {
  const key = c.req.param('key')
  await c.env.MY_BUCKET.put(key, c.req.body)
  return c.text(`Put ${key} successfully!`)
})

ミドルウェアで環境変数を使用する ​

Module Worker モードのみで使用できます。 Basic 認証のユーザー名やパスワードなど、ミドルウェア内で環境変数やシークレットを使用したい場合はこのように書きます。

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

type Bindings = {
  USERNAME: string
  PASSWORD: string
}

const app = new Hono<{ Bindings: Bindings }>()

//...

app.use('/auth/*', async (c, next) => {
  const auth = basicAuth({
    username: c.env.USERNAME,
    password: c.env.PASSWORD,
  })
  return auth(c, next)
})

同じように Bearer 認証や JWT 認証などもできます。

Github Actions からデプロイする ​

CI で Cloudflare にデプロイする前に、 Cloudflare のトークンが必要です。 User API Tokens で管理できます。

新しく作られたトークンでは、 Edit Cloudflare Workers テンプレートを選択し、すでにトークンがある場合は、トークンが対応する権限を持っていることを確認してください。

次に GitHub リポジトリの設定ダッシュボードで Settings->Secrets and variables->Actions->Repository secrets を開き、 CLOUDFLARE_API_TOKEN という名前のシークレットを作成します。

.github/workflows/deploy.yml を Hono プロジェクトのルートフォルダに作成し、以下のコードを貼り付けます:

yml
name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

次に wrangler.jsonc を編集し、 compatibility_date の行の後に次のコードを追加します。

jsonc
"main": "src/index.ts",
"minify": true

準備が整いました! 後はコードを push して楽しんでください。

ローカル開発環境で環境変数をロードする ​

ローカル開発環境で環境変数を設定するには、 .dev.vars か .env ファイルをプロジェクトのルートディレクトリに作成します。 これらのファイルは dotenv の構文を使用します。 以下に例を示します:

SECRET_KEY=value
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

詳しくは Cloudflare のドキュメントをご覧ください: https://developers.cloudflare.com/workers/wrangler/configuration/#secrets

コードの中で c.env.* から環境変数にアクセスします。

INFO

デフォルトでは、 process.env は Cloudflare Workers では利用できないため、環境変数は c.env から取得することが推奨されます。 使用したい場合は、 nodejs_compat_populate_process_env フラグを有効にする必要があります。 また、 cloudflare:workers から env をインポートすることもできます。 詳細は Cloudflare docs の How to access env をご覧ください。

ts
type Bindings = {
  SECRET_KEY: string
}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/env', (c) => {
  const SECRET_KEY = c.env.SECRET_KEY
  return c.text(SECRET_KEY)
})

Cloudflare にプロジェクトをデプロイする前に、環境変数、シークレットを Cloudflare Workers プロジェクトの設定で追加することを忘れないでください。

詳しくは Cloudflare のドキュメントをご覧ください: https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard

このドキュメントは非公式の日本語翻訳版です。
Released under the MIT License.

Copyright © 2022-present Yusuke Wada & Hono contributors. "kawaii" logo is created by SAWARATSUKI.