# TypeScript Namespace Pollution in Cloudflare Worker Types

2025-05-24

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](https://developers.cloudflare.com/workers/wrangler/commands/#types$0).

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

```typescript
// 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](https://pnpm.io/9.x/package_json#pnpmoverrides) and the dash character to prevent it from installing.

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

**For npm users**:

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

**For yarn users**:

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

**The Empty Types Pattern**

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

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

```typescript
// 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](https://github.com/cloudflare/workers-sdk/issues/8802$0)