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 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

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

Use overrides and the dash character to prevent it from installing.

{
  "overrides": {
    "@cloudflare/workers-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 {};

GitHub Issues

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

Comments 4

doraeminemonJuly 19, 2025

I still have the same problem even though I follow the same step. Do I need to change anything in tsconfig.json ?

jokullJuly 21, 2025

Run pnpm install?

aromanAugust 19, 2025

with pnpm >=9.12.0, you can just do:

"overrides": {
  "@cloudflare/workers-types": "-"
}

jokullAugust 19, 2025

Thanks @aroman - post is now updated!