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

verbatimModuleSyntax as Stricter Alternative

Understanding TypeScript 5.0's verbatimModuleSyntax flag and how it supersedes isolatedModules concerns.

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.