Hono

外観

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
bunx create-hono my-app
sh
deno run -A npm:create-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. 実行 ​

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

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

4. デプロイ ​

Cloudflare アカウントをお持ちの場合は、Cloudflare にデプロイできます。 package.json で、$npm_execpath を選択したパッケージマネージャーに変更する必要があります。

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

以上です！

Service Worker モードまたは Module Worker モード ​

Cloudflare Workers を記述するための構文は 2 つあります。Module Worker モードとService Worker モードです。Hono を使用すると、両方の構文で記述できますが、バインディング変数をローカライズできるように、Module Worker モードを使用することをお勧めします。

ts
// Module Worker
export default app
ts
// Service Worker
app.fire()

Hono を他のイベントハンドラーで使用する ​

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

これを行うには、モジュールの fetch ハンドラーとして app.fetch をエクスポートし、必要に応じて他のハンドラーを実装します。

ts
const app = new Hono()

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

静的ファイルの提供 ​

静的ファイルを提供したい場合は、Cloudflare Workers の 静的アセット機能 を使用できます。 wrangler.toml でファイルのディレクトリを指定します。

toml
assets = { directory = "public" }

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

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

型 ​

ワーカーの型が必要な場合は、@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!`)
})

ミドルウェアでの変数の使用 ​

これは、Module Worker モードの場合のみです。 Basic 認証ミドルウェアの「username」や「password」など、ミドルウェアで変数またはシークレット変数を使用する場合は、次のように記述する必要があります。

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 Action からのデプロイ ​

CI 経由で Cloudflare にコードをデプロイする前に、cloudflare トークンが必要です。 こちらから管理できます: https://dash.cloudflare.com/profile/api-tokens

新しく作成されたトークンの場合は、**Cloudflare Workers の編集** テンプレートを選択します。別のトークンが既にある場合は、トークンに対応する権限があることを確認してください（いいえ、トークン権限は cloudflare page と cloudflare worker で共有されません）。

次に、Github リポジトリ設定ダッシュボード: Settings->Secrets and variables->Actions->Repository secrets に移動し、CLOUDFLARE_API_TOKEN という名前で新しいシークレットを追加します。

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

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.toml を編集し、compatibility_date 行の後にこのコードを追加します。

toml
main = "src/index.ts"
minify = true

すべて準備が整いました！ これでコードをプッシュして楽しんでください。

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

ローカル開発用の環境変数を構成するには、プロジェクトのルートディレクトリに .dev.vars ファイルを作成します。 次に、通常の env ファイルと同様に環境変数を構成します。

SECRET_KEY=value
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

このセクションの詳細については、Cloudflare ドキュメントを参照してください: https://developers.cloudflare.com/workers/wrangler/configuration/#secrets

次に、c.env.* を使用してコード内の環境変数を取得します。
Cloudflare Workers の場合、環境変数は process.env ではなく c を介して取得する必要があります。

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 Worker プロジェクトの構成で環境変数/シークレットを設定することを忘れないでください。

このセクションの詳細については、Cloudflare ドキュメントを参照してください: https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard

MIT ライセンスの下でリリースされています。

Copyright © 2022-present Yusuke Wada & Hono contributors. 「kawaii」ロゴは SAWARATSUKI によって作成されました。