第07章：Cloudflare向けTypeScriptの超入門 ✍️🔷☁️

この章では、TypeScriptを「言語として全部学ぶ」のではなく、Cloudflareで困らない分だけを、実務っぽくやさしく身につけることを目標にします 😊 ここで大事なのは、文法の細かい暗記より、Request・Response・env・ctx・fetch を“型つきで読める”ことです。さらに今のCloudflareでは、型を手書きするより wrangler types で実行環境に合った型を生成するのが公式の本筋です。(Cloudflare Docs)

本日時点では TypeScript 6.0 が案内されており、これは 7.0 への橋渡しになる安定版です。つまりこの章では、古い書き方を覚え込むより、6.0時代の素直な書き方に寄せておくのが安心です。(Microsoft for Developers)

この章でできるようになりたいこと 🎯

この章のゴールは、次の4つです。

TypeScriptの基本である「型注釈」「関数」「オブジェクト」「非同期」を、Cloudflareのコードで読めるようになる
fetch(request, env, ctx) の3引数が何者か分かる
Env を手で書き続けず、wrangler types で型生成する感覚をつかむ
Workers AI の binding も「型のある Cloudflare機能」として見られるようになる 🤖✨

まず知っておきたい考え方 💡

Cloudflare Workers の fetch() ハンドラは、受け取るのが Request、返すのが Response です。これがこの章のど真ん中です。さらに env には binding 群が入り、ctx は Worker のライフサイクル制御に使う文脈オブジェクトです。(Cloudflare Docs)

つまり、Cloudflare向けTypeScriptの最初の一歩は、こんな感じです。

fetch Handler Arguments

request → ブラウザやAPIクライアントから来た入力 📩
env → KV、R2、D1、Workers AI などの接続口 🔌
ctx → waitUntil() などを使う実行文脈 ⏳
戻り値 → Response 📤

この形が読めるだけで、Cloudflareのコードはかなり怖くなくなります。(Cloudflare Docs)

TypeScriptは「保険」ではなく「地図」🗺️

初学者だと、型は「うるさい警告機能」に見えがちです 😅 でも Cloudflare ではむしろ逆で、今の runtime で何が使えて、どの binding が存在して、何が返るのかを先に見せてくれる地図として使うのが気持ちいいです。

TypeScript as a Map

Cloudflare公式も、@cloudflare/workers-types をアプリ側で抱え込むより、wrangler types で runtime 型と binding 型を生成する方法を推奨しています。生成される型は compatibility_date と compatibility_flags、さらにあなたの Worker 設定にある bindings に合わせて決まります。(Cloudflare Docs)

先に覚える文法は、このくらいで十分 👍

この章で先に覚えたいのは、次の小さい範囲です。

変数に型をつける
関数の引数と戻り値に型をつける
オブジェクトの形を型で表す
async / await を読める
null や undefined を雑に扱わない

ここでは難しいジェネリクス祭りはまだ不要です 🙆 Cloudflare学習の序盤では、「値の形が分かる」「戻り値が分かる」「Promise が分かる」 だけでかなり前に進めます。

Cloudflareで最初に読むべき TypeScript 例 🌱

まずは最小の例からです。

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const url = new URL(request.url);
    const name = url.searchParams.get("name") ?? "world";

    return new Response(
      JSON.stringify({
        message: `Hello, ${name}!`,
        method: request.method,
      }),
      {
        headers: { "content-type": "application/json; charset=UTF-8" },
      }
    );
  },
} satisfies ExportedHandler<Env>;

このコードで見てほしいのは、文法テクニックではなく次の3点です 😊

fetch は非同期関数なので Promise<Response> を返す
request.url や request.method のように、Request には最初から読める情報が入っている
Env は「自分で適当に書く型」ではなく、「Cloudflare設定から寄せる型」にしていく

Cloudflareの fetch() ハンドラは Request を受けて Response を返す形で、ctx は3番目の引数として渡されます。Request / Response は Fetch API ベースです。(Cloudflare Docs)

ここが超重要：`Env` を手書きしない 🧠⚡

昔の解説では、こんなふうに interface Env { ... } を手書きする例をたくさん見かけます。でも、今のCloudflare公式のおすすめは「手書きしない」 です。

wrangler types Generation

Cloudflareのベストプラクティスでは、Env を手書きせず wrangler types を実行して、実際の Wrangler 設定に一致した型定義を生成するよう案内されています。binding 名の追加や変更があったら、wrangler types を再実行するのが基本です。(Cloudflare Docs)

理由はすごくシンプルです。

設定ファイルでは binding 名を AI にしたのに、コードで env.MY_AI と書いてしまう
staging だけにある binding と production にある binding がズレる
compatibility_date を変えたのに、型が古いまま残る

こういう事故を、型生成でかなり前倒しに検出できるからです。(Cloudflare Docs)

`wrangler types` の基本手順 🛠️

Cloudflare公式では、wrangler types を実行すると、デフォルトで worker-configuration.d.ts が生成され、そこに runtime 型と Env 型が入ります。さらに tsconfig.json の compilerOptions.types にそのファイルを登録する流れが推奨されています。(Cloudflare Docs)

手順はこんな感じです。

1. 型を生成する

npx wrangler types

2. `tsconfig.json` に生成ファイルを登録する

{
  "compilerOptions": {
    "types": ["./worker-configuration.d.ts"]
  }
}

3. binding を増やえたり名前を変えたら、もう一度生成する

npx wrangler types

Cloudflare公式は、wrangler types を TypeScript に依存するタスクの前に実行する ことも案内しています。CI や build の前に入れておくのも自然です。--check で更新漏れ確認もできます。(Cloudflare Docs)

`tsconfig.json` は盛りすぎない 🧾✨

初学者ほど tsconfig.json をいじり倒したくなりますが、この段階ではおすすめしません。まずは Cloudflareが生成した型を読むための最低限 だけで十分です。

本日時点の TypeScript 6.0 は 7.0 への移行を見据えた節目の版なので、昔の設定をコピペして温存するより、シンプルな tsconfig で始めるほうが後で楽です。非推奨設定は 7.0 で消える予定のものもあります。(Microsoft for Developers)

`compatibility_date` と型はセットで考える 📅🔗

Cloudflareでは、Worker の設定にある compatibility_date がとても大事です。Wrangler 設定では name、main、compatibility_date が最低限必要で、wrangler types はこの compatibility_date や compatibility_flags を見て runtime 型を生成します。(Cloudflare Docs)

つまり、TypeScriptの型は単なる飾りではなく、「今日の自分の Worker runtime に合わせた型」 です。

compatibility_date

ここが Node.js の普通のサーバー開発と少し違って、Cloudflareらしい気持ちいいところです ☁️

Node.jsっぽい型がほしいときの注意 🟢

Cloudflare Workers は Node.js そのものではありません。ただし Node互換機能を使う場面もあり、その場合 Cloudflare公式の TypeScript ページでは、nodejs_compat を使っているなら @types/node も追加して tsconfig.json の types に "node" を入れる よう案内されています。(Cloudflare Docs)

たとえばこんな形です。

{
  "compilerOptions": {
    "types": ["./worker-configuration.d.ts", "node"]
  }
}

この章ではまだ Node互換を深掘りしませんが、「Cloudflareの型」と「Nodeの型」は別物で、必要なときだけ足すという感覚だけ持っておくと十分です 😊

`fetch(request, env, ctx)` を型で読む練習 📘

ここは声に出して読むくらいでちょうどいいです。

request は Request
env は bindings の集合
ctx は Context API
返り値は Response か Promise<Response>

Cloudflare docs でも fetch(request, env, ctx) が基本形として案内されていて、ctx は Context API の入口、env は binding 参照口です。Request のコンストラクタや Response のコンストラクタも型情報つきで整理されています。(Cloudflare Docs)

`satisfies ExportedHandler<Env>` は怖く見えるけど便利 😌

Cloudflareのサンプルでは、末尾に satisfies ExportedHandler<Env> がついていることがあります。これは雑に言うと、「この export default の形は Cloudflare Worker として正しい？」を型でチェックするためのお守りです。

ExportedHandler Validation

Workers AI の公式 TypeScript 例でも、この書き方が使われています。つまり、序盤から慣れておく価値があります。(Cloudflare Docs)

Workers AI まで見据えると、TypeScriptがさらに気持ちよくなる 🤖💙

CloudflareのAI機能も、TypeScriptの章で早めに軽く触れておくと理解が深まります。 Workers AI を Worker から使うには、Wrangler 設定に AI binding を追加し、その binding はコード上で env.AI として使えます。さらに env.AI.run() でモデルを実行できます。(Cloudflare Docs)

設定の例です。

{
  "ai": {
    "binding": "AI"
  }
}

コードの最小例はこんな感じです。

export default {
  async fetch(request, env): Promise<Response> {
    const result = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      prompt: "TypeScriptとは何かをやさしく一言で説明して",
    });

    return new Response(JSON.stringify(result), {
      headers: { "content-type": "application/json; charset=UTF-8" },
    });
  },
} satisfies ExportedHandler<Env>;

この例でうれしいのは、AI ですら “なんとなく呼ぶ外部サービス” ではなく、env.AI という型のある binding として扱えることです。

Typed AI Binding

「Cloudflare向けTypeScript」は、AI時代ほど価値が上がります ✨(Cloudflare Docs)

しかも Workers AI は TypeScript と相性がいい 🚀

Cloudflareは Workers AI について、JavaScript / TypeScript コードベースで Vercel AI SDK を使えることも案内しています。さらに OpenAI互換 endpoint もあり、OpenAI SDK のコードをベースURLとモデル名の切り替えで流用しやすい導線もあります。(Cloudflare Docs)

つまり将来的には、

まずは env.AI.run() で素直に触る
次に OpenAI互換 endpoint で既存コード資産を流用する
必要なら AI SDK に広げる

という段階的な学び方ができます。この流れに乗るためにも、型つきで env や戻り値を読める力が効いてきます。(Cloudflare Docs)

VS Code と Copilot はどう絡むの？ 🤝💻

本日時点の GitHub公式資料では、VS Code は Copilot の chat、code completion、agent mode、MCP、workspace indexing をサポートしています。また GitHubは、最新の安定版IDEとCopilot拡張を使うことを推奨しています。(GitHub Docs)

つまりこの章では、Copilotにコードを書かせ切るより、次の使い方が相性抜群です。

「この Request の型を日本語で説明して」
「この env に何の binding が入っている想定？」
「この型エラーは、文法ミスか設定ミスかどっち？」
「wrangler types を前提にすると、ここはどう直す？」

こういう聞き方をすると、TypeScriptの学習補助としてかなり強いです 🤖✨

さらに GitHub docs では、Copilot の agent mode を MCP で拡張する使い方も案内されています。将来的に Cloudflare系のドキュメントやツール文脈を強く渡したいとき、この流れはかなり重要です。(GitHub Docs)

Cloudflare公式のVS Code拡張はある？ 🧩

あります。Visual Studio Marketplace には Cloudflare Workers Extension があり、説明では Cloudflare Worker の bindings 管理 を目的にした拡張として案内されています。(marketplace.visualstudio.com)

ただし、学習の主役はあくまでこれではありません。 Cloudflare公式のデバッグ導線を見ると、VS Code での基本線は launch.json を使ったデバッガ接続です。つまり、実務の中心は Wrangler + 型生成 + VS Code + Copilot で、拡張は補助輪くらいに考えるのが自然です。(Cloudflare Docs)

初学者がつまずきやすいポイント 😵‍💫

1. `Env` を自作してしまう

Common TypeScript Pitfalls

いちばん多いです。「今は動く」けれど、binding名変更や環境差分で壊れやすいです。Cloudflare公式は手書きより wrangler types を推奨しています。(Cloudflare Docs)

2. `tsconfig.json` を盛りすぎる

最初から難解な設定を入れると、TypeScriptの勉強ではなく設定ファイル格闘編になります。 6.0時代は特に、古い設定の温存より素直な構成が安全です。(Microsoft for Developers)

3. `fetch` の戻り値を雑にする

Cloudflareの fetch() ハンドラは Response を返す世界です。ここを曖昧にすると、型の恩恵が一気に減ります。(Cloudflare Docs)

4. AI binding を「外部APIキー直呼び」と同じ感覚で考える

Workers AI は Cloudflare binding として扱えるので、env.AI の設計に慣れておくと後で伸びやすいです。(Cloudflare Docs)

この章のおすすめ演習 🧪🎓

演習1：クエリ文字列を読む

?name=komiyamma を受け取って JSON を返す Worker を作る。ねらいは Request、URL、Response に慣れることです。

演習2：`wrangler types` を回す

AI や vars を1つ追加して、worker-configuration.d.ts がどう変わるか見る。ねらいは「型は手で書くものではなく、設定から育つもの」と体感することです。

演習3：Workers AI を1回だけ呼ぶ

env.AI.run() で短い文章生成をして、結果を JSON で返す。ねらいは「AIも型のある binding」と理解することです。(Cloudflare Docs)

演習4：Copilotに説明させる

次のように聞いてみます。

この Worker の TypeScript 初学者向けに、
request / env / ctx / Response の役割を
1つずつ日本語で説明して。
また、wrangler types を使う前提で
Env を手書きしない理由も説明して。

この使い方だと、Copilotが「答えを全部出す機械」ではなく、理解を言語化してくれる家庭教師になってくれます 🤝

この章の完成イメージ 🏁✨

この章が終わった時点で、次の状態になっていれば大成功です。

fetch(request, env, ctx) を見てビビらない
Request と Response の役割が分かる
Env は wrangler types で作るのが正道だと分かる
worker-configuration.d.ts を tsconfig.json に入れる意味が分かる
Workers AI の env.AI.run() を見ても「型のある binding だな」と思える

Cloudflareの今の公式導線では、TypeScriptは「おまけ」ではなく、runtime・bindings・AI・複数環境を安全につなぐための中心道具です。特に wrangler types は、Cloudflare向けTypeScript学習の要になります。(Cloudflare Docs)

章末のひとこと 🌈

この章では、TypeScriptを難しくしすぎないのがコツです。 「型理論の勉強」ではなく、「Cloudflareのコードを安心して読めるようになる練習」 と考えると、かなり進めやすいです 😊

次の第8章では、この型つきの土台を使って、最小のWorkerを作りながら HTTP の流れそのものを気持ちよく体感していく流れにすると、とてもつながりがよくなります 🌐📨

必要なら次に、そのまま続けて 「第7章の学習目標・演習課題・成果物・想定学習時間つき教材設計版」 まで落とし込めます。

この章でできるようになりたいこと 🎯​

まず知っておきたい考え方 💡​

TypeScriptは「保険」ではなく「地図」🗺️​

先に覚える文法は、このくらいで十分 👍​

Cloudflareで最初に読むべき TypeScript 例 🌱​

ここが超重要：Env を手書きしない 🧠⚡​

wrangler types の基本手順 🛠️​

1. 型を生成する​

2. tsconfig.json に生成ファイルを登録する​

3. binding を増やえたり名前を変えたら、もう一度生成する​

tsconfig.json は盛りすぎない 🧾✨​

compatibility_date と型はセットで考える 📅🔗​

Node.jsっぽい型がほしいときの注意 🟢​

fetch(request, env, ctx) を型で読む練習 📘​

satisfies ExportedHandler<Env> は怖く見えるけど便利 😌​

Workers AI まで見据えると、TypeScriptがさらに気持ちよくなる 🤖💙​

しかも Workers AI は TypeScript と相性がいい 🚀​

VS Code と Copilot はどう絡むの？ 🤝💻​

Cloudflare公式のVS Code拡張はある？ 🧩​

初学者がつまずきやすいポイント 😵‍💫​

1. Env を自作してしまう​

2. tsconfig.json を盛りすぎる​

3. fetch の戻り値を雑にする​

4. AI binding を「外部APIキー直呼び」と同じ感覚で考える​

この章のおすすめ演習 🧪🎓​

演習1：クエリ文字列を読む​

演習2：wrangler types を回す​

演習3：Workers AI を1回だけ呼ぶ​

演習4：Copilotに説明させる​

この章の完成イメージ 🏁✨​

章末のひとこと 🌈​