Cloudflare Workers

Cloudflare Workers は Cloudflare CDN 上で動作する JavaScript エッジランタイムです。

Wrangler を使えば、アプリケーションをローカルで開発し、数個のコマンドで公開できます。 Wrangler はトランスコンパイラーを備えているため、TypeScript でコードを記述できます。

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

1. セットアップ

Cloudflare Workers 向けのスターターテンプレートがあります。 「create-hono」コマンドでプロジェクトを開始します。 この例では cloudflare-workers テンプレートを選択します。

npm

npm create hono@latest my-app

yarn

yarn create hono my-app

pnpm

pnpm create hono my-app

bun

bun create hono@latest my-app

deno

deno init --npm hono my-app

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

2. Hello World

次のように src/index.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 にアクセスします。

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

ポート番号の変更

ポート番号を変更する場合は、次の手順に従って wrangler.toml / wrangler.json / wrangler.jsonc ファイルを更新できます。 Wrangler の設定

また、次の手順に従って CLI オプションを設定することもできます。 Wrangler CLI

4. デプロイ

Cloudflare アカウントがあれば、Cloudflare にデプロイできます。package.json の $npm_execpath は、使用するパッケージマネージャーに変更する必要があります。

npm

npm run deploy

yarn

yarn deploy

pnpm

pnpm run deploy

bun

bun run deploy

これで完了です。

Hono と他のイベントハンドラーの併用

Module Worker モードでは、Hono を他のイベントハンドラー（scheduled など）と組み合わせられます。

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

const app = new Hono()

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

静的ファイルの配信

静的ファイルを配信する場合は、Cloudflare Workers の静的アセット機能を使えます。wrangler.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 をインストールする必要があります。

npm

npm i --save-dev @cloudflare/workers-types

yarn

yarn add -D @cloudflare/workers-types

pnpm

pnpm add -D @cloudflare/workers-types

bun

bun add --dev @cloudflare/workers-types

テスト

テストには @cloudflare/vitest-pool-workers を推奨します。 設定方法は例を参照してください。

次のアプリケーションがあるとします。

import { Hono } from 'hono'

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

次のコードで「200 OK」レスポンスを返すかをテストできます。

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 の型引数として渡すと、型が付与されます。

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 フラグを使います。

wrangler types --env-interface CloudflareBindings

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

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 認証ミドルウェアの「username」や「password」を使う場合は、次のように記述する必要があります。

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 トークンが必要です。ユーザー API トークンから管理できます。

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

続いて、GitHub リポジトリの設定画面 Settings->Secrets and variables->Actions->Repository secrets に移動し、CLOUDFLARE_API_TOKEN という名前のシークレットを追加します。

Hono プロジェクトのルートに .github/workflows/deploy.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 の行の後に次のコードを追加します。

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

準備が整いました。コードをプッシュしましょう。

ローカル開発時の環境変数の読み込み

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

SECRET_KEY=value
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

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

コードでは c.env.* を使って環境変数を取得します。

情報

Cloudflare Workers ではデフォルトで process.env を使えないため、c.env から環境変数を取得することを推奨します。使用するには、nodejs_compat_populate_process_env フラグを有効にする必要があります。また、cloudflare:workers から env をインポートすることもできます。詳しくは Cloudflare ドキュメントの env へのアクセス方法を参照してください。

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