TypeScript

TypeScript は Cloudflare Workers の第一級言語です。Workers が提供する API はすべて型付きで、型定義はオープンソースの Workers ランタイムである workerd ↗ から直接生成されます。

Worker の型は wrangler types を実行して生成することをおすすめします。Cloudflare は型定義を GitHub ↗ と npm ↗（npm install -D @cloudflare/workers-types）にも公開しています。

Worker の設定に一致する型を生成する

Cloudflare は、オープンソースの Workers ランタイムである workerd ↗ を継続的に改善しています。 workerd の変更により JavaScript API が変わり、対応する TypeScript の型も変わることがあります。

そのため、Worker に正しい型は次の条件に依存します。

1. Worker の 互換性日付
2. Worker の 互換性フラグ
3. Wrangler 設定ファイル で定義する Worker のバインディング
4. Wrangler 設定ファイルの rules で指定した モジュールルール

たとえば、ランタイムが AsyncLocalStorage ↗ クラスの使用を許可するのは、Wrangler 設定ファイル に compatibility_flags = ["nodejs_als"] がある場合だけです。この条件は型定義にも反映される必要があります。

型定義を Worker の設定と常に一致させるには、次のコマンドで動的に型を生成します。

npx wrangler types

yarn wrangler types

pnpm wrangler types

詳細は wrangler types コマンドのドキュメント を参照してください。

これにより d.ts ファイルが生成され、デフォルトでは worker-configuration.d.ts に保存されます。Worker のバインディングに基づく Env 型と、Worker の互換性日付およびフラグに基づくランタイム型の両方が含まれます。

そのファイルを tsconfig.json の compilerOptions.types 配列に追加します。nodejs_compat 互換性フラグを使っている場合は、@types/node もインストールします。

型ファイルは、必要に応じて git にコミットできます。

@cloudflare/workers-types から wrangler types へ移行する

ランタイム型の生成には @cloudflare/workers-types パッケージではなく、wrangler types を使うことをおすすめします。Worker の 互換性日付 ↗ と compatibility_flags に基づいて型が生成されるため、Worker で使えるランタイム API と型が一致します。

npm uninstall @cloudflare/workers-types

yarn remove @cloudflare/workers-types

pnpm remove @cloudflare/workers-types

bun remove @cloudflare/workers-types

npx wrangler types

yarn wrangler types

pnpm wrangler types

.d.ts ファイルが生成され、デフォルトでは worker-configuration.d.ts に保存されます。Env 型も生成されます。何らかの理由で含めない場合は、--include-env=false を設定できます。

Worker のコードから @cloudflare/workers-types のインポートは削除できます。

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

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

nodejs_compat 互換性フラグを使っている場合は、@types/node もインストールします。

npm i @types/node

yarn add @types/node

pnpm add @types/node

bun add @types/node

次に、これを tsconfig.json に追加します。

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

フレームワークやビルドツールにかかわらず、TypeScript に依存するタスクの前に wrangler types を実行します。

多くのプロジェクトには、既存のビルド / 開発スクリプトと型チェックがあります。次の例では、型チェックスクリプトの前に wrangler types を追加しています。

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

CI で使うために、生成した型ファイルをコミットすることをおすすめします。wrangler types は数秒で終わるため、ほかの CI コマンドの前に実行できます。例:

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

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

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

生成した型ファイルをコミットし、CI で最新かどうかを確認したい場合は、--check フラグを使えます。

- run: npx wrangler types --check
- run: npm run build
- run: npm test

- run: yarn wrangler types --check
- run: yarn build
- run: yarn test

- run: pnpm wrangler types --check
- run: pnpm run build
- run: pnpm test

コミット済みの型ファイルが古い場合、CI ジョブは失敗します。開発者は型を再生成してコミットする必要があります。

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