INTEGRITY Dokumentace

← Cloudflare Workers / workers / languages

TypeScript

TypeScript je na Cloudflare Workers plnohodnotně podporovaným jazykem. Všechna API poskytovaná ve Workers jsou plně typovaná a definice typů jsou generovány přímo z workerd ↗, open source runtime Workers.

Doporučujeme, abyste pro svůj Worker vygenerovali typy spuštěním wrangler types. Cloudflare rovněž publikuje definice typů na GitHub ↗ a npm ↗ (npm install -D @cloudflare/workers-types).

Vygenerovat typy odpovídající konfiguraci Workeru

Cloudflare neustále vylepšuje workerd ↗, open source runtime Workers. Změny ve workerd mohou přinést změny v JavaScript API, a tím i změny příslušných typů TypeScript.

To znamená, že správné typy pro váš Worker závisí na:

  1. Vašeho Workeru compatibility date.
  2. Vašeho Workeru compatibility flags.
  3. Bindings vašeho Workeru, které jsou definovány ve vašem Konfigurační soubor Wrangler.
  4. Jakýkoli pravidla modulů jste zadali v konfiguračním souboru Wrangler v části rules.

Runtime vám například umožní použít pouze AsyncLocalStorage ↗ třídu, pokud máte compatibility_flags = ["nodejs_als"] ve vašem Konfigurační soubor Wrangler. To by se mělo projevit i v definicích typů.

Aby definice typů vždy odpovídaly konfiguraci vašeho Workeru, můžete typy dynamicky generovat spuštěním:

npx wrangler types

Viz wrangler types dokumentace k příkazu pro další podrobnosti.

Tímto se vygeneruje d.ts soubor a (ve výchozím nastavení) jej uložit do worker-configuration.d.ts. Bude to zahrnovat Env typy na základě vazeb vašeho Workeru a typy runtime na základě data kompatibility a příznaků vašeho Workeru.

Poté tento soubor přidejte do tsconfig.json's compilerOptions.types pole. Pokud máte nodejs_compat příznak kompatibility byste měli také nainstalovat @types/node.

Pokud chcete, můžete svůj soubor typů commitnout do gitu.

Migrace z @cloudflare/workers-types na wrangler types

Doporučujeme, abyste použili wrangler types ke generování runtime typů namísto použití @cloudflare/workers-types balíček, protože generuje typy na základě vašeho Workeru compatibility date ↗ a compatibility flags, čímž zajišťuje, že typy přesně odpovídají runtime API dostupným pro váš Worker.

1. Odinstalujte @cloudflare/workers-types

npm uninstall @cloudflare/workers-types

2. Vygenerujte typy runtime pomocí Wrangler

npx wrangler types

Tímto se vygeneruje .d.ts soubor uložený do worker-configuration.d.ts ve výchozím nastavení. Tím se také vygeneruje Env typy. Pokud je z nějakého důvodu nechcete zahrnout, můžete nastavit --include-env=false.

Nyní můžete odstranit veškeré importy z @cloudflare/workers-types v kódu vašeho Workeru.

3. Ujistěte se, že váš tsconfig.json zahrnuje vygenerované typy

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

Mějte na paměti, že pokud jste zadali vlastní cestu k souboru s typy runtime, měli byste ji použít i ve svém compilerOptions.types pole místo výchozí cesty.

4. Přidejte @types/node, pokud používáte nodejs_compat (Volitelné)

Pokud používáte nodejs_compat příznak kompatibility byste měli také nainstalovat @types/node.

npm i @types/node

Poté toto přidejte do svého tsconfig.json.

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

5. Aktualizujte své skripty a pipeline CI

Bez ohledu na konkrétní framework nebo nástroje pro sestavení byste měli spustit wrangler types příkaz před jakýmikoli úlohami, které závisí na TypeScriptu.

Většina projektů už má existující skripty pro sestavení a vývoj a rovněž nějakou formu kontroly typů. V následujícím příkladu přidáváme wrangler types před skriptem pro kontrolu typů v projektu:

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

Doporučujeme, abyste vygenerovaný soubor typů zahrnuli do commitu pro použití v CI. Můžete spustit wrangler types před ostatními příkazy CI, protože by to nemělo trvat déle než pár sekund. Například:

- 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

Alternativně, pokud commitnete vygenerovaný soubor typů a chcete v CI ověřovat, že zůstává aktuální, můžete použít --check příznak:

- 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

Tím úloha CI selže, pokud je commitnutý soubor typů zastaralý, což vývojáře vyzve k jeho regeneraci a commitnutí aktualizovaných typů.

Zdroje