Course contentsShow
← TypeScript
Lesson 1257 of 1,79629. The Build PipelineFree lesson

Namespace Exports and Limitations

Why namespace merging and certain namespace patterns don't work with isolatedModules.

Namespace Exports and Limitations

What you'll learn: Why namespace merging and certain namespace patterns fail when using isolatedModules, and what to do instead.

The Core Problem

When isolatedModules is enabled, TypeScript's compiler (and bundlers like esbuild or Babel) process each file independently without looking at other files. This creates a fundamental conflict with namespaces, which were designed for TypeScript's older, cross-file analysis model.

Namespaces rely on declaration merging—the ability to define a namespace in multiple places and have TypeScript combine them into one logical entity. But if each file is compiled in isolation, the compiler can't see those other pieces to merge them together.

Why This Matters

Consider this pattern that works without isolatedModules:

// utilities.ts
namespace Utils {
  export function log(msg: string) {
    console.log(msg);
  }
}

// Same namespace, different file section
namespace Utils {
  export function warn(msg: string) {
    console.warn(msg);
  }
}

export { Utils };

When isolatedModules: true, this fails because the bundler can't merge the two namespace declarations—it doesn't know if there are more pieces in other files.

The Safe Alternative

Use object exports instead:

// utilities.ts
export const Utils = {
  log(msg: string) {
    console.log(msg);
  },
  warn(msg: string) {
    console.warn(msg);
  }
};

This is a simple value export that any bundler can handle without cross-file analysis.

Key Takeaway: With isolatedModules, avoid namespace merging and multi-declaration namespaces; use standard ES module exports with objects or individual named exports instead.