The Bundler Problem: No Cross-File Analysis
What you'll learn: How modern bundlers like esbuild and swc transpile TypeScript files in complete isolation, without understanding relationships between files.
The Core Issue
When you enable isolatedModules, TypeScript warns you about code patterns that are safe for tsc but break in bundlers. The reason? Bundlers process each file independently — they don't know what's in other files.
Think of it like a factory assembly line where each worker only sees the part in front of them. Worker A doesn't know what Worker B is making. If your part requires knowing what's happening at another station, you're stuck.
How Bundlers Work Differently Than tsc
TypeScript's compiler (tsc) builds a complete understanding of your entire project. It knows which imports are types, which are values, what each export means across every file.
Bundlers like esbuild and swc strip types incredibly fast by transforming one file at a time. They look at math.ts, transform it, then move to app.ts. They never load both into memory together or analyze their relationship.
Why This Matters
Without cross-file knowledge, a bundler can't tell if import { User } from './types' is importing:
- A type that should be erased
- A class that needs to stay
- An interface (type-only) mixed with a function (value)
The bundler sees the syntax but doesn't resolve the file to find out. It makes its best guess per-file and moves on.
Key Takeaway: Bundlers sacrifice TypeScript's full type-checking analysis for raw speed, processing files in isolation without understanding cross-file type relationships — this is why isolatedModules exists to catch incompatible patterns early.