Workers TypeScript types get a major overhaul

TypeScript has become an essential tool for developers building on Cloudflare Workers, catching type errors before code ever runs. But the types themselves need to keep pace with an evolving runtime. The latest major release of @cloudflare/workers-types rebuilds the entire type generation pipeline, improves standards compliance, and ties types more closely to your actual runtime configuration.

Setup and configuration

Getting started is straightforward: run npx wrangler init for a new project. For existing Workers projects, upgrade with npm install --save-dev typescript @cloudflare/workers-types@latest and create a tsconfig.json file:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "lib": ["esnext"],
    "types": ["@cloudflare/workers-types"]
  }
}

Your editor will then flag issues and offer code completions as you type.

Better interoperability with browser types

Workers share many runtime APIs with browsers, but fundamental platform differences remain. This creates friction for frameworks like Remix that run the same files both on Cloudflare's network and in the browser — those files need to type-check against lib.dom.d.ts, which has historically been incompatible with Workers types.

The new release solves this by generating a separate version of the types that can be selectively imported, without adding @cloudflare/workers-types to your tsconfig.json's types field:

import type { KVNamespace } from "@cloudflare/workers-types";

declare const USERS_NAMESPACE: KVNamespace;

The generation scripts also produce an automatic diff against TypeScript's lib.webworker.d.ts, which will guide future spec-compliance improvements.

Compatibility dates reflected in types

Cloudflare uses compatibility flags and dates to introduce breaking changes without disrupting existing code. Some flags alter types directly — for example, global_navigator adds a navigator global, and url_standard changes the URLSearchParams constructor signature.

You can now select a types version that matches your project's compatibility date, ensuring your code doesn't rely on features that won't be available at runtime:

{
  "compilerOptions": {
    ...
    "types": ["@cloudflare/workers-types/2022-08-04"]
  }
}

Wrangler-driven type generation

Runtime configuration also affects the type surface. KV namespaces, R2 buckets, and custom module rules for text, data, or WebAssembly files all need corresponding TypeScript declarations. Previously, you had to maintain these manually in a separate ambient file.

The new npx wrangler types command generates that file automatically, keeping wrangler.toml as the single source of truth. Given this configuration:

kv_namespaces = [{ binding = "MY_NAMESPACE", id = "..." }]
rules = [{ type = "Text", globs = ["**/*.txt"] }]

…you get these ambient types:

interface Env {
  MY_NAMESPACE: KVNamespace;
}
declare module "*.txt" {
  const value: string;
  export default value;
}

Documentation and changelogs

Code completions are a valuable exploration tool for developers new to Workers. The types now include documentation for standard APIs from TypeScript's official types, with Cloudflare-specific API docs being integrated incrementally.

For existing users, each release includes a detailed changelog that splits out new, changed, and removed definitions — making upgrade decisions easier.

Under the hood: a new generation pipeline

The automatic type generation scripts have been fully rewritten to be more reliable and maintainable. The system now leverages workerd's runtime-type-information (RTTI) system to query API types directly, rather than parsing C++ ASTs.

RTTI is passed to a TypeScript program that uses the TypeScript Compiler API to generate declarations and tidy them up with AST transformations. This is built into workerd's Bazel build system, so generating types is now a single bazel build //types:types command, with Bazel's cache minimizing rebuilds.

While auto-generated types correctly describe the JavaScript interface, handcrafted TypeScript "overrides" add higher-fidelity types for better ergonomics. These overrides now live alongside the C++ declarations using macros, so they stay in sync with runtime changes. The overrides enable:

  • Type parameters (generics) on types like ReadableStream, eliminating any-typed values.
  • Method overloads that map input to output types — for instance, KVNamespace#get() returns string with type: "text" but ArrayBuffer with type: "arrayBuffer".
  • Renamed types that match TypeScript conventions and reduce verbosity.
  • Full type replacements for better accuracy, such as WebSocketPair declared as a const for cleaner use with Object.values().
  • Types for internally untyped values like the Request#cf object.
  • Hiding of internal types that aren't usable in Workers.

Upgrade with npm install --save-dev @cloudflare/workers-types@latest and try wrangler types to see the improvements firsthand. New types versions will publish with each workerd release.