What isolatedModules Does
You'll learn: Why TypeScript enforces stricter rules with isolatedModules and what it means for single-file transpilation compatibility.
The Core Problem
TypeScript's compiler (tsc) normally analyzes your entire project to understand types. It looks at imports, exports, and relationships between files to perform sophisticated type checking. But many modern build tools like Babel, esbuild, and swc compile TypeScript files one at a time without seeing the whole project—they just strip types away quickly.
This creates a mismatch: code that TypeScript accepts might break when these single-file transpilers try to process it, because they can't resolve cross-file information.
What isolatedModules Enforces
When you enable isolatedModules: true in your tsconfig.json, TypeScript prevents you from writing code patterns that require looking at multiple files to transpile correctly.
It adds compile-time errors for code that:
- Uses TypeScript-only syntax ambiguously (like
const enumor namespace merging) - Exports values that can't be distinguished from types without type information
- Re-exports types in ways that require type resolution
Think of it like this: isolatedModules is TypeScript saying "I'll only allow code that works when each file is compiled in isolation, without knowing what's in other files."
Why This Matters
Modern bundlers prioritize speed. They achieve incredible performance by processing files independently and in parallel. But this speed comes at a cost—they can't perform the same deep analysis as tsc. By enabling isolatedModules, you ensure your code remains compatible with these fast transpilers, avoiding mysterious runtime errors where imports are suddenly undefined.
Key Takeaway: isolatedModules enforces stricter coding rules to guarantee your TypeScript can be safely transpiled by tools that process one file at a time, bridging the gap between TypeScript's type system and fast modern build tooling.