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):
{
"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 {};