TypeScript

TypeScript

TypeScriptはCloudflare Workersの第一級言語です。Cloudflareは型定義をGitHub ↗とnpm ↗に公開しています（npm install -D @cloudflare/workers-types）。Workersで提供されるすべてのAPIは完全に型付けされており、型定義はオープンソースのWorkersランタイムであるworkerd ↗から直接生成されます。

ワーカーの設定に一致する型を生成する（実験的）

CloudflareはオープンソースのWorkersランタイムであるworkerd ↗を継続的に改善しています。 workerdの変更はJavaScript APIの変更を引き起こす可能性があり、それによりそれぞれのTypeScript型が変更されることがあります。例えば、urlsearchparams_delete_has_value_arg互換フラグは、新しいWHATWG URL標準APIへの追加をサポートするために、一部のメソッドにオプション引数を追加します。

これは、あなたのWorkerに対する正しいTypeScript型が以下に依存することを意味します：

1. あなたのWorkerの互換性日。
2. あなたのWorkerの互換性フラグ。

例えば、wrangler.tomlにcompatibility_flags = ["nodejs_als"]がある場合、ランタイムはあなたのワーカーコードでAsyncLocalStorage ↗クラスを使用することを許可しますが、@cloudflare/workers-typesの型定義にはこれが反映されません。

この問題を解決し、型定義が常に互換性設定に最新の状態であることを保証するために、ランタイム型を動的に生成することができます（wrangler 3.66.0以降）：

npx wrangler types --experimental-include-runtime

これにより、d.tsファイルが生成され、デフォルトでは.wrangler/types/runtime.d.tsに保存されます。コマンドの出力で、そのファイルをtsconfig.jsonのcompilerOptions.types配列に追加するように促されます。

ファイルをgitにコミットしたい場合は、カスタムパスを指定できます。例えば、runtime.d.tsファイルはプロジェクトのルートに保存されます：

npx wrangler types --experimental-include-runtime="./runtime.d.ts"

注意：型が常に最新の状態であることを保証するために、設定ファイルに変更を加えた後は必ずwrangler types --experimental-include-runtimeを実行してください。

詳細については利用可能なフラグの完全なリストを参照してください。

@cloudflare/workers-typesからwrangler types --experimental-include-runtimeへの移行

@cloudflare/workers-typesパッケージは、ユーザーがtsconfig.jsonで指定した各異なる互換性日 ↗のためのランタイム型を提供します。しかし、このパッケージはwrangler types --experimental-include-runtimeコマンドに取って代わられます。

@cloudflare/workers-typesからwrangler typesを使用するための実験的ランタイムの含有に切り替える手順は以下の通りです：

@cloudflare/workers-typesをアンインストール

npm

npm uninstall @cloudflare/workers-types

yarn

yarn remove @cloudflare/workers-types

pnpm

pnpm uninstall @cloudflare/workers-types

bun

bun remove @cloudflare/workers-types

wranglerを使用してランタイム型を生成

npx wrangler types --experimental-include-runtime

これにより、デフォルトで.wrangler/types/runtime.d.tsに保存される.d.tsファイルが生成されます。

生成された型を含めるようにtsconfig.jsonを更新

{
  "compilerOptions": {
    "types": ["./.wrangler/types/runtime"]
  }
}

ランタイム型ファイルのカスタムパスを指定している場合は、デフォルトパスの代わりにそれをcompilerOptions.types配列で使用する必要があります。

スクリプトとCIパイプラインを更新

wrangler types --experimental-include-runtimeに切り替える際は、開発プロセスが常に最新の型を使用することを確認したいでしょう。ここで覚えておくべき主なことは、特定のフレームワークやビルドツールに関係なく、TypeScriptに依存する開発タスクの前にwrangler types --experimental-include-runtimeコマンドを実行する必要があるということです。これにより、エディタやビルドツールが常に最新の型にアクセスできるようになります。

ほとんどのプロジェクトには既存のビルドおよび開発スクリプト、ならびにいくつかの型チェックがあります。以下の例では、プロジェクトの型チェックスクリプトの前にwrangler types --experimental-include-runtimeを追加しています：

{
  "scripts": {
    "dev": "existing-dev-command",
    "build": "-existing-build-command",
    "type-check": "wrangler types --experimental-include-runtime && tsc"
  }
}

CIでは、別のビルドおよびテストコマンドがあるかもしれません。wrangler types --experimental-include-runtimeを他のCIコマンドの前に実行することがベストプラクティスです。例えば：

npm

- run: npm run generate-types
- run: npm run build
- run: npm test

yarn

- run: yarn generate-types
- run: yarn build
- run: yarn test

pnpm

- run: pnpm run generate-types
- run: pnpm run build
- run: pnpm test

bun

- run: bun run generate-types
- run: bun run build
- run: bun test

このようにしてwrangler types --experimental-include-runtimeコマンドをワークフローに統合することで、特定のフレームワークやツールの選択に関係なく、Cloudflare Workerのための最も正確で最新の型を常に使用することができます。

既知の問題

@types/nodeの遷移的読み込みが@cloudflare/workers-typesを上書きする

あなたのプロジェクトの依存関係が独自に@types/nodeパッケージを読み込むことがあります。@types/node@20.8.4以降、そのパッケージは@cloudflare/workers-typesによって指定されたRequest、Response、およびfetch型（おそらく他の型も）を上書きし、型エラーを引き起こす可能性があります。

この問題を回避する方法は、package.jsonで@types/nodeのバージョンを20.8.3に固定することです：

{
  "overrides": {
    "@types/node": "20.8.3"
  }
}

詳細についてはこのGitHubの問題 ↗を参照してください。

リソース

• TypeScriptテンプレート ↗
• @cloudflare/workers-types ↗
• ランタイムAPI
• TypeScriptの例