@cloudflare/workers-types

@cloudflare/workers-types ships the ambient TypeScript declarations for everything a Cloudflare Worker can touch: the Workers runtime globals (Request, Response, ExecutionContext, ScheduledEvent, ExportedHandler) and the platform bindings that make Workers useful in production, including KV namespaces, D1 databases, R2 buckets, Durable Objects, Queues, Vectorize, Workers AI, and Hyperdrive. The types are generated directly from workerd’s own JSG RTTI (the C++ runtime’s structural type information), so they track the actual shape of the runtime rather than a hand-maintained guess.

Because Workers’ backward compatibility is governed by compatibility dates rather than semver, this package publishes a new version on roughly the same daily cadence as workerd itself, always representing the latest runtime surface. Cloudflare now recommends generating types scoped to a project’s specific compatibility date and flags via the wrangler types command instead, though this package continues to be published on the same schedule for projects that still depend on it directly.

What You Get

• Ambient global types for the Workers runtime — Request, Response, ExecutionContext, FetchEvent, ScheduledEvent, and the rest of the standards-based global scope.
• Typed bindings for Cloudflare’s storage and compute primitives — KVNamespace, D1Database, R2Bucket, DurableObjectNamespace, Queue, Vectorize, and AI.
• An /experimental subpath export for APIs still gated behind experimental compatibility flags, kept separate from the stable surface.
• Importable type aliases (e.g. import type { Request as WorkerRequest } from "@cloudflare/workers-types") for projects that can’t fully swap their global tsconfig.json lib/types configuration.

Common Use Cases

• Adding compile-time type safety to a Worker’s fetch/scheduled/queue handlers and their Env bindings interface.
• Getting IDE autocomplete for platform APIs (KV, D1, R2, Durable Objects) while writing Workers in TypeScript.
• Type-checking a worker-configuration.d.ts file that declares a project’s specific bindings.
• Providing a base typing environment for frameworks and tools (e.g. Hono, itty-router) that target the Workers runtime.

Under The Hood

Architecture

The generator pipeline (types/src/index.ts) turns workerd’s own JSG RTTI — a Cap’n Proto description of the runtime’s C++ structures — into TypeScript declarations: generateDefinitions() walks the RTTI into raw AST nodes, compileOverridesDefines() layers in hand-written override/define source files, and a chain of AST transforms (iterator, override-define, global-scope, class-to-interface, comments, add-onmessage-declaration) rewrites the program using TypeScript’s own compiler API (program.ts, print.ts) before a separate importable-variant pass produces the non-global export. The Cap’n Proto RTTI schema acts as a stable boundary between the C++ runtime and the TypeScript tooling, so the generator never has to parse C++ directly. The whole pipeline is invoked from Bazel (types/scripts/build-types.ts, build-worker.ts), and the npm publish step (npm/scripts/build-types-package.mjs) simply stamps the workerd release version onto the already-built declaration snapshot.

Tech Stack

The generator is written in TypeScript against TypeScript 6’s own compiler API (ts.Program, ts.TypeChecker, ts.transform), reads RTTI via capnp-es, and builds through the monorepo’s Bazel rules rather than a standalone npm build script. The published package itself has no runtime dependencies — it ships prebuilt .d.ts snapshots only — and is versioned in lockstep with workerd’s own dated releases via a WORKERD_VERSION environment variable written into package.json at build time.

Code Quality

The types/test directory carries real coverage: generator unit tests (structure, type, index), print-output snapshot tests, transform-specific tests (iterators, class-to-interface, globals, overrides), and a types/test/types directory of realistic usage snippets (D1, Durable Objects, email, RPC, AI, Cloudflare-specific properties) that are type-checked against the generated declarations as an integration check. Linting runs through a shared typescript-eslint base config, with a short, explicitly tracked list of relaxed rules (e.g. no-unnecessary-condition) called out as TODOs rather than silently disabled. tsconfig relaxes strictNullChecks for compatibility reasons but keeps checkJs and most strict flags on.

API Design The generated-from-RTTI approach is the notable choice here: instead of a hand-maintained @types package that drifts from the runtime it describes (a common failure mode for community type definitions), these types are produced from the same structural metadata the C++ runtime itself exposes, so a new runtime capability shows up in the types the moment it ships. The dual ambient/importable output and the isolated /experimental subpath mirror the platform’s own compatibility-date philosophy: stable and experimental surfaces are kept structurally separate rather than mixed behind version numbers, and consumers can opt into either the zero-config global setup or scoped type-only imports depending on how much of their tsconfig they’re willing to change.