TypeScript Namespace Pollution in Cloudflare Worker Types

May 24, 2025

Any third-party library that depends on @cloudflare/workers-types can pollute the TypeScript namespace in modern Cloudflare Workers projects, overriding your custom generated types.

Why This Happens: Cloudflare has evolved from using base types (@cloudflare/workers-types) to generated, project-specific types via wrangler types, but many third-party libraries still depend on the legacy base types.

The Evolution of Cloudflare Workers TypeScript Support

  • Legacy approach: Direct dependency on @cloudflare/workers-types
  • Modern approach: Generated types via wrangler typesworker-configuration.d.ts
  • The conflict: When both exist, the base types can override your custom types

Common Scenarios Where This Happens

  • Monitoring libraries (Sentry, Datadog, etc.)
  • Database libraries
  • Authentication libraries
  • Any library that needs to reference Cloudflare's Env interface

Identifying the Problem

// Before importing third-party lib - custom Env works
export interface Env {
  MY_CUSTOM_BINDING: string;
  DATABASE_URL: string;
}

// After importing lib with @cloudflare/workers-types dependency
// Your custom Env is replaced by generic base types

Solutions by Package Manager

For pnpm users (the fix from the GitHub issue):

{
  "overrides": {
    "@cloudflare/workers-types": "link:./packages/empty-types"
  }
}

For npm users:

{
  "overrides": {
    "@cloudflare/workers-types": "file:./empty-types"
  }
}

For yarn users:

{
  "resolutions": {
    "@cloudflare/workers-types": "file:./empty-types"
  }
}

The Empty Types Pattern

Create a minimal package that effectively "nullifies" the problematic dependency:

// empty-types/package.json
{
  "name": "@empty/cloudflare-types",
  "version": "1.0.0",
  "types": "index.d.ts"
}
// empty-types/index.d.ts
// Intentionally empty - prevents type pollution
export {};