verbatimModuleSyntax as Stricter Alternative
What you'll learn: How TypeScript 5.0's verbatimModuleSyntax flag provides a more predictable and stricter module handling than isolatedModules.
The Problem isolatedModules Tried to Solve
Remember that isolatedModules exists because bundlers like esbuild and swc transpile files one at a time without cross-file type information. It warns you about patterns that won't work in this environment — like const enums or ambiguous type-only imports.
But isolatedModules has limitations. It doesn't fully prevent all the edge cases, and its rules can feel inconsistent.
Enter verbatimModuleSyntax
TypeScript 5.0 introduced verbatimModuleSyntax as a stricter, more predictable alternative. When enabled, TypeScript enforces a simple rule: your import and export statements are emitted exactly as you write them (with type-only syntax stripped).
This means:
- If you write
import type, TypeScript knows it's type-only and won't emit it - If you write a regular
import, TypeScript emits it — even if you only use it as a type - No guessing, no ambiguity
Why This Matters
With verbatimModuleSyntax, you must be explicit about what's a type and what's a value. This eliminates the category of bugs where TypeScript strips imports that bundlers might need, or keeps imports that create runtime errors.
Think of it like this: isolatedModules is training wheels that sometimes wobble. verbatimModuleSyntax is a strict instructor who insists you declare your intentions clearly every time.
When to Use It
Enable verbatimModuleSyntax if you're using fast transpilers (esbuild, swc) and want the most predictable, maintainable module syntax. It's the modern best practice for bundler-first workflows.
Key Takeaway: verbatimModuleSyntax supersedes isolatedModules by enforcing explicit type-only syntax, giving you complete control over what gets emitted and eliminating module-related ambiguity.