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 types → worker-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

Copy// 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):

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

For npm users:

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

For yarn users:

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

The Empty Types Pattern

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

Copy// empty-types/package.json
{
  "name": "@empty/cloudflare-types",
  "version": "1.0.0",
  "types": "index.d.ts"
}

Copy// empty-types/index.d.ts
// Intentionally empty - prevents type pollution
export {};

GitHub Issues

• cloudflare/workers-sdk: Wrangler types is recommended but hard to actually use in production #8802