(これは某所でやる Cloudflare の入門チュートリアルで、そこの肌感に合わせています。)
アカウント登録が終わっていることは前提とします。
$ npm create cloudflare@latest
いちばん簡単な TypeScript のワーカーのサンプルを作ります
npm run dev で起動。
この中身を解説します。
Cloudflare Worker は wrangler という CLI でコードを管理します。gcloud や aws-cli みたいなものだと思ってください。
wrangler は npx wrangler でもいいですが、プロジェクト毎に devDependencies 経由にすることを推奨します。
(全体的にはかなりおせっかい気味な CLI です)
デプロイやクラウドリソースを管理するのに、$ wrangler login で認証します。ブラウザで Cloudflare の OAuth の認証してください。
ログイン済みだと wrangler whoami でパーミッションが表示されます。
プロジェクト設定を管理するのが wrangler.json(c) です。最近まで toml でしたが json になりました。
wrangler.json
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "noisy-bush-ced6",
"main": "src/index.ts",
"compatibility_date": "2025-04-16",
"observability": {
"enabled": true
}
}
name はサービス固有名です。デフォルト設定だと
main はエントリポイントです。pnpm wrangler dev src/main.ts で明示的にエントリポイントを指定して立ち上げることもできます。
大事な点なのですが、wrangler には esbuild が組み込まれており、デフォルトでは esbuild でコンパイルしています。
カスタムビルドをしたかったら wrangler.json に次のような設定が必要です。
{
"build": {
"command": "npm run build",
"cwd": "build_cwd",
"watch_dir": "build_watch_dir"
}
}
これは簡単なものは楽に作れる反面、フレームワークのビルドパイプラインと干渉すると地獄が始まります。そうならないように祈るしかありません。
現代だと変な設定をしない限りは esbuild で十分です。
では、実際のエントリポイントのコードをみてみましょう。
src/index.ts
export default {
async fetch(request, env, ctx): PromiseResponse> {
return new Response('Hello World!');
},
} satisfies ExportedHandlerEnv>;
これは Node.js ではなく、 wrangler というサーバー環境で実行されます。
import で Node.js のように node_modules のライブラリを呼ぶことができるのですが、実際には wrangler にビルトインされている esbuild でバンドルされているだけです。
deploy せずにビルドだけして確かめてみます。
$ pnpm wrangler deploy --outdir=dist --dry-run
$ ls -al dist
.rw-r--r-- 194 mizchi 16 Apr 16:32 index.js
.rw-r--r-- 902 mizchi 16 Apr 16:32 index.js.map
.rw-r--r-- 116 mizchi 16 Apr 16:32 README.md
wrangler の事情はテストランナーにも現れています。vitest を普通に動かすのではなく、 wrangler を経由して動かすようになっています。
vitest.config.mts
import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
export default defineWorkersConfig({
test: {
poolOptions: {
workers: {
wrangler: { configPath: './wrangler.jsonc' },
},
},
},
});
要は esbuild でビルドされていることを知っていればいいのですが、 @types/node ではなく @cloudflare/workers-types を呼んでいることを認識しておきましょう。
tsconfig.json
"types": [
"@cloudflare/workers-types/2023-07-01"
],
Cloudflare Workers には様々なバインディングがあるのですが、それは基本的に wrangler.json に書くことになります。
wrangler types を叩くと それらのバインディング定義に合わせて API の型定義ファイル worker-configuration.d.ts を生成します。
$ pnpm wrangler types
✨ Types written to worker-configuration.d.ts
ログインしてる状態で pnpm wrangler deploy
$ pnpm wrangler deploy
⛅️ wrangler 4.11.1
-------------------
Total Upload: 0.19 KiB / gzip: 0.16 KiB
No bindings found.
--dry-run: exiting now.
(base)
Cloudflare Workers は反映がとにかく早く、多分 10 秒もせずに本番サーバーに反映されています。
デプロイすると管理画面の Worker & Pages から、デプロイしたサービスの状態を確認できます。
wrangler deploy -e で環境のバインディングを切り替えることができます。
例えば production や staging 等でデプロイするサービスを切り替えたい場合、 wrangler.json 内に env を作ります。
例えば vars でバインドする変数を変更する例です。
{
"$schema": "node_modules/wrangler/config-schema.json",
"main": "src/main.ts",
"vars": {
"XXX": "DEV"
},
"env": {
"prod": {
"vars": {
"XXX": "PROD"
}
}
}
}
これを書いた状態で pnpm wrangler types で型を更新します。
ついでにソースコードからこの XXX を参照してみます。
src/main.ts
export default {
async fetch(request, env, ctx): PromiseResponse> {
return new Response('Hello World!' + env.XXX);
},
} satisfies ExportedHandlerEnv>;
これを wrangler deploy -e prod でデプロイしてみましょう。
デフォルトのデプロイ先は
ここに別名を設定したい場合は、Workers の管理画面からドメインを追加したり色々します (略)
これでデプロイできますが、Cloudflare Access を使うとデプロイした URL に対して Cloudflare のアカウントで認証を掛けることができます。これが開発時に便利で、開発者は Cloudflare アカウントでログインしてるはず。
注意: この機能はドメイン登録する必要があります。手っ取り早く試したいなら、管理画面内からドメインを買えるので、買って DNS を設定してください。
解説はこの記事に譲ります。
kv を使ってみます。これは結果整合な高速キャッシュです。
まず wrangler kv で namespace を作成します。
$ pnpm wrangler kv namespace create test-kv
{
"kv_namespaces": [
{
"binding": "test_kv",
"id": ""
}
]
}
バインディングを wrangler.json に追記保存します。 wrangler types も忘れずに。
これを使ったコードを書きます。1 分間だけ last_access のキーを保持するようにします。
const LAST_ACCESS_KEY = "last_access";
export default {
async fetch(request, env, ctx): PromiseResponse> {
const lastAccess = await env.test_kv.get(LAST_ACCESS_KEY);
if (lastAccess) {
return new Response(lastAccess);
} else {
await env.test_kv.put("last_access", Date.now().toString(), {
expirationTtl: 60,
});
return new Response("new_access");
}
},
} satisfies ExportedHandlerEnv>;
最初は new_access で、以降 1 分間だけ new_access の UnixTime のレスポンスを返す例です。
これを眺めてください
代表的なもの
本気で使い込む場合に大事なのは、おそらく Durable Objects です。これが他の機能の基盤なので、これで実現できるかどうかで Cloudflare 自体のポテンシャルがわかります。
6 月に Cloudflare Container Registry が来るらしいので、そうなると Docker コンテナがデプロイできるようになる…らしいです。
割と流行りに応じて無節操になんでも作ってくる感じです。
別記事で後で書く。
Be the first to comment
