TypeScript

TypeScript is a first-class language on Cloudflare Workers. All APIs provided in Workers are fully typed, and type definitions are generated directly from workerd, the open-source Workers runtime.

We recommend you generate types for your Worker by running wrangler types. Cloudflare also publishes type definitions to GitHub and npm (npm install -D @cloudflare/workers-types).

Generate types that match your Worker's configuration

Cloudflare continuously improves workerd, the open-source Workers runtime. Changes in workerd can introduce JavaScript API changes, thus changing the respective TypeScript types.

This means the correct types for your Worker depend on:

1. Your Worker's compatibility date.
2. Your Worker's compatibility flags.
3. Your Worker's bindings, which are defined in your Wrangler configuration file.
4. Any module rules you have specified in your Wrangler configuration file under rules.

For example, the runtime will only allow you to use the AsyncLocalStorage class if you have compatibility_flags = ["nodejs_als"] in your Wrangler configuration file. This should be reflected in the type definitions.

To ensure that your type definitions always match your Worker's configuration, you can dynamically generate types by running:

npx wrangler types

yarn wrangler types

pnpm wrangler types

See the wrangler types command docs for more details.

This will generate a d.ts file and (by default) save it to worker-configuration.d.ts. This will include Env types based on your Worker bindings and runtime types based on your Worker's compatibility date and flags.

worker-configuration.d.ts is generated and will be overwritten when you rerun wrangler types, so do not edit it manually. Define custom environment types in source-owned TypeScript, separate from the generated file. Use declaration merging with the public Cloudflare.Env interface.

You should then add that file to your tsconfig.json's compilerOptions.types array. If you have the nodejs_compat compatibility flag, you should also install @types/node.

You can commit your types file to git if you wish.

Migrating from @cloudflare/workers-types to wrangler types

We recommend you use wrangler types to generate runtime types, rather than using the @cloudflare/workers-types package, as it generates types based on your Worker's compatibility date and compatibility flags, ensuring that types match the exact runtime APIs made available to your Worker.

1. Uninstall @cloudflare/workers-types

npm uninstall @cloudflare/workers-types

yarn remove @cloudflare/workers-types

pnpm remove @cloudflare/workers-types

bun remove @cloudflare/workers-types

2. Generate runtime types using Wrangler

npx wrangler types

yarn wrangler types

pnpm wrangler types

This will generate a .d.ts file, saved to worker-configuration.d.ts by default. This will also generate Env types. If for some reason you do not want to include those, you can set --include-env=false.

You can now remove any imports from @cloudflare/workers-types in your Worker code.

3. Make sure your tsconfig.json includes the generated types

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

Note that if you have specified a custom path for the runtime types file, you should use that in your compilerOptions.types array instead of the default path.

4. Add @types/node if you are using nodejs_compat (Optional)

If you are using the nodejs_compat compatibility flag, you should also install @types/node.

npm i @types/node

yarn add @types/node

pnpm add @types/node

bun add @types/node

Then add this to your tsconfig.json.

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

5. Update your scripts and CI pipelines

Regardless of your specific framework or build tools, you should run the wrangler types command before any tasks that rely on TypeScript.

Most projects will have existing build and development scripts, as well as some type-checking. In the example below, we're adding the wrangler types before the type-checking script in the project:

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

We recommend you commit your generated types file for use in CI. You can run wrangler types before other CI commands, as it should not take more than a few seconds. For example:

- 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

Alternatively, if you commit your generated types file, use --check in CI:

- 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

--check compares the generated file's recorded environment/configuration hash and runtime header with the current Wrangler configuration and runtime inputs. It does not compare or validate the generated file body. It fails the CI job when the recorded inputs are out of date, prompting developers to regenerate and commit the updated types.

Resources

• TypeScript template
• @cloudflare/workers-types
• Runtime APIs
• TypeScript Examples