INTEGRITY Документация

← Cloudflare Workers / workers / languages

TypeScript

TypeScript является полноценным языком в Cloudflare Workers. Все API, предоставляемые Workers, полностью типизированы, а определения типов генерируются напрямую из workerd ↗, среду выполнения Workers с открытым исходным кодом.

Мы рекомендуем сгенерировать типы для Worker, выполнив wrangler types. Cloudflare также публикует определения типов в GitHub ↗ и npm ↗ (npm install -D @cloudflare/workers-types).

Генерация типов, соответствующих конфигурации вашего Worker

Cloudflare постоянно совершенствует workerd ↗, среду выполнения Workers с открытым исходным кодом. Изменения в workerd могут приводить к изменениям JavaScript API, а значит и соответствующих типов TypeScript.

Это означает, что правильные типы для вашего Worker зависят от:

  1. Вашего Worker дата совместимости.
  2. Вашего Worker флаги совместимости.
  3. Привязки вашего Worker, которые определены в конфигурационный файл Wrangler.
  4. Любой правила модулей вы указали в файле конфигурации Wrangler в разделе rules.

Например, runtime разрешит использовать только AsyncLocalStorage ↗ класс, если у вас есть compatibility_flags = ["nodejs_als"] в вашем конфигурационный файл Wrangler. Это должно быть отражено в определениях типов.

Чтобы определения типов всегда соответствовали конфигурации Worker, можно динамически генерировать типы, выполнив:

npx wrangler types

См. wrangler types документация по команде для дополнительных сведений.

Это сгенерирует d.ts файл и (по умолчанию) сохраните его в worker-configuration.d.ts. Это будет включать Env типы на основе привязок вашего Worker и типы среды выполнения на основе даты совместимости и флагов вашего Worker.

Затем добавьте этот файл в tsconfig.json: compilerOptions.types массив. Если у вас есть nodejs_compat флаг совместимости, также следует установить @types/node.

При желании файл типов можно закоммитить в git.

Переход с @cloudflare/workers-types к wrangler types

Мы рекомендуем использовать wrangler types чтобы сгенерировать типы для среды выполнения вместо использования @cloudflare/workers-types пакет, так как он генерирует типы на основе вашего Worker дата совместимости ↗ и compatibility flags, гарантируя, что типы точно соответствуют runtime API, доступным для вашего Worker.

1. Удалите @cloudflare/workers-types

npm uninstall @cloudflare/workers-types

2. Генерация типов среды выполнения с помощью Wrangler

npx wrangler types

Это сгенерирует .d.ts файл, сохраненный в worker-configuration.d.ts по умолчанию. Это также приведёт к созданию Env типы. Если по какой-то причине вы не хотите их включать, можно задать --include-env=false.

Теперь можно удалить все импорты из @cloudflare/workers-types в коде вашего Worker.

3. Убедитесь, что ваш tsconfig.json включает сгенерированные типы

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

Обратите внимание: если вы указали собственный путь к файлу типов среды выполнения, используйте его в compilerOptions.types массив вместо пути по умолчанию.

4. Добавьте @types/node, если вы используете nodejs_compat (необязательно)

Если вы используете nodejs_compat флаг совместимости, также следует установить @types/node.

npm i @types/node

Затем добавьте это в tsconfig.json.

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

5. Обновите скрипты и CI-конвейеры

Независимо от используемого фреймворка или инструментов сборки следует выполнить wrangler types команду перед любыми задачами, зависящими от TypeScript.

В большинстве проектов уже есть скрипты сборки и разработки, а также какая-то проверка типов. В примере ниже мы добавляем 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, если закоммиченный файл типов устарел, и побуждает разработчиков заново сгенерировать и закоммитить обновлённые типы.

Материалы