TypeScript Modules & Namespaces
debt(d5/e3/b5/t7)
Closest to 'specialist tool catches it' (d5). The detection_hints list TypeScript compiler and ESLint as tools. The TypeScript compiler surfaces module resolution errors and can warn on legacy namespace usage, but it won't outright reject namespaces — ESLint with specific rules (e.g. @typescript-eslint) is needed to flag legacy namespace patterns. Neither is a default linter catch (d3), since namespace syntax is syntactically valid TypeScript; specialist configuration is required.
Closest to 'simple parameterised fix' (e3). The quick_fix is clear: replace namespace/module keywords with ES module import/export syntax and update moduleResolution config. This is more than a one-line patch (e1) because every namespace block and its consumers must be converted, but it's typically scoped to refactoring within one or a few files/components rather than a cross-cutting architectural rework.
Closest to 'persistent productivity tax' (e5, mapped to b5). Applies to both web and cli contexts broadly. A codebase mixing namespaces with ES modules imposes ongoing confusion for every maintainer — they must understand two module systems, tree-shaking is broken, and tooling integration degrades. It affects many work streams (bundler config, IDE navigation, dead-code elimination) but doesn't fully reshape the architecture (b7), so b5 is appropriate.
Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception field states explicitly that developers believe namespaces are the correct modern way to organise TypeScript code, when they are actually a legacy pattern superseded by ES modules. This directly contradicts how JavaScript/Node.js modules work and how modern bundlers expect code to be structured. A competent developer coming from JavaScript will confidently use namespaces and be wrong in a non-obvious way, making this a serious trap rather than merely a documented gotcha.
Also Known As
TL;DR
Explanation
TypeScript module: any file with an import or export statement — isolated scope, explicit dependencies. Namespace (formerly 'internal module'): namespace Foo {} — only appropriate for global script files and ambient declarations. Modern TypeScript: always prefer ES modules for better tree-shaking, tooling, and compatibility. Ambient modules: declare module 'lodash' for adding types to untyped JavaScript packages. Declaration merging: interfaces and namespaces can be merged to extend existing types.
Common Misconception
Why It Matters
Common Mistakes
- Using namespaces in modern bundled applications — use ES modules
- Forgetting that a .ts file without import/export is a global script, not a module
- Triple-slash references (/// <reference>) in module code — use import in modern TypeScript
- Mixing namespace and module patterns in the same codebase
Code Examples
// Legacy namespace — not tree-shakeable, pollutes global scope:
namespace MyApp {
export namespace Utils {
export function formatDate(date: Date): string {
return date.toISOString();
}
}
}
// Usage: MyApp.Utils.formatDate(new Date())// ES Module — tree-shakeable, explicit dependencies:
// utils/date.ts:
export function formatDate(date: Date): string {
return date.toISOString();
}
// app.ts:
import { formatDate } from './utils/date';
// Bundler includes only formatDate, not all of utils
// Ambient module for untyped JS:
declare module 'legacy-lib' {
export function init(config: object): void;
}