Cloudflare Workers
Cloudflare Workers は Cloudflare の CDN で JavaScript を実行するエッジランタイムです。
アプリケーションをローカルで開発し、 Wrangler のいくつかのコマンドを使用して公開します。 Wrangler はコンパイラを内蔵しているため、 TypeScript でコードを書けます。
Hono を使った Cloudflare Workers 最初のアプリケーションを作りましょう。
1. セットアップ
Cloudflare Workers 向けのスターターが使用できます。 "create-hono" コマンドでプロジェクトを作成してください。 cloudflare-workers
テンプレートを選択します。
npm create hono@latest my-app
yarn create hono my-app
pnpm create hono my-app
bun create hono@latest my-app
deno init --npm hono my-app
my-app
に移動し、依存関係をインストールします。
cd my-app
npm i
cd my-app
yarn
cd my-app
pnpm i
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. Run
ローカル開発サーバーを起動し、ブラウザで http://localhost:8787
にアクセスします。
npm run dev
yarn dev
pnpm dev
bun run dev
ポート番号を変える
ポート番号をる必要がある場合は、 wrangler.toml
/ wrangler.json
/ wrangler.jsonc
を以下のドキュメントに従って変更してください: Wrangler Configuration
もしくは CLI オプションで設定することもできます: Wrangler CLI
4. デプロイ
Cloudflare アカウントを持っている場合、 Cloudflare にデプロイ出来ます。 package.json
の $npm_execpath
を選択したパッケージマネージャに置き換える必要があります。
npm run deploy
yarn deploy
pnpm run deploy
bun run deploy
それだけです!
Service Worker モード / Module Worker モード
Cloudflare Workers には2通りの記法があります。 Module Worker モード と Service Worker モード です。 Hono を使うと、どちらの記法でも書くことができますが、バインディング変数がローカライズされるため Module Worker モードを推奨します。
// Module Worker
export default app
// Service Worker
app.fire()
他のイベントハンドラとともに Hono を使う
Module Worker モード で他のイベントハンドラ( scheduled
など)を統合できます。
このように、 app.fetch
を fetch
ハンドラとしてエクスポートし、必要に応じて他のハンドラも実装します:
const app = new Hono()
export default {
fetch: app.fetch,
scheduled: async (batch, env) => {},
}
静的ファイルの提供
静的ファイルを提供したい場合、 Cloudflare Workers の Static Assets 機能 を使うことができます。 wrangler.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
型
Workers の型が欲しい場合は @cloudflare/workers-types
をインストールする必要があります。
npm i --save-dev @cloudflare/workers-types
yarn add -D @cloudflare/workers-types
pnpm add -D @cloudflare/workers-types
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!`)
})
ミドルウェアで環境変数を使用する
Module Worker モードのみで使用できます。 Basic 認証のユーザー名やパスワードなど、ミドルウェア内で環境変数やシークレットを使用したい場合はこのように書きます。
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 のトークンが必要です。 ここで管理できます: https://dash.cloudflare.com/profile/api-tokens
新しく作られたトークンでは、 Edit Cloudflare Workers テンプレートを選択します。 すでにトークンがある場合は、トークンが対応する権限を持っていることを確認してください。 ( Cloudflare Pages と Cloudflare Workers の間で権限が共有されないことに注意してください。
次に GitHub リポジトリの設定ダッシュボードで Settings->Secrets and variables->Actions->Repository secrets
を開き、 CLOUDFLARE_API_TOKEN
という名前のシークレットを作成します。
.github/workflows/deploy.yml
を Hono プロジェクトのルートフォルダに作成し、以下のコードを貼り付けます:
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 }}
then edit wrangler.toml
, and add this code after compatibility_date
line.
main = "src/index.ts"
minify = true
準備が整いました! 後はコードを push して楽しんでください。
ローカル開発環境で環境変数をロードする
ローカル開発環境で環境変数を設定するには、 .dev.vars
ファイルをプロジェクトのルートディレクトリに作成します。 そして環境変数を普通の .env
ファイルのように設定します。
SECRET_KEY=value
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
詳しくは Cloudflare のドキュメントをご覧ください: https://developers.cloudflare.com/workers/wrangler/configuration/#secrets
コードの中で c.env.*
から環境変数にアクセスします。 Cloudflare Workers では、環境変数には c
からアクセスします。 process.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