"verbatimModuleSyntax"

Imports without the word type stay in JavaScript unchanged, so type imports must be marked explicitly.

On this page

Example

#
JSON
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "verbatimModuleSyntax": true
  }
}

Definition and usage

#

The verbatimModuleSyntax option introduces a simple rule: an import or export without the word type ends up in the generated JavaScript exactly as written, and import type disappears completely. The compiler stops guessing on its own which imports to remove because they only serve types.

This makes the output predictable and the same in every tool that translates files one at a time, such as esbuild, SWC, or Babel. An unmarked type import fails with an error, so you can immediately see what will remain in the code. The option also turns on all the isolatedModules checks.

It appeared in TypeScript 5.0 and replaced the older importsNotUsedAsValues and preserveValueImports options. It fits best in projects with ES modules. In files compiled to CommonJS, it forbids import and export syntax, because that syntax can’t be left unchanged there.

Syntax

#
Syntax
"verbatimModuleSyntax": true

More examples

#
An unmarked type import
TypeScript
import { Course, formatTitle } from './course'
// Error: 'Course' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.
What stays in JavaScript
TypeScript
import type { Course } from './course'
import { type Lesson } from './lesson'
import { type Badge, formatTitle } from './format'

export function heading(course: Course, lesson: Lesson, badge: Badge): string {
  return formatTitle(`${course.title}: ${lesson.title} (${badge.name})`)
}

// Compilation result:
// import {} from './lesson';
// import { formatTitle } from './format';
// export function heading(course, lesson, badge) { … }

Good practices

#
  • Starting a new project with a bundler? Enable verbatimModuleSyntax instead of just isolatedModules. You get the same checks and one simple rule for imports.
  • Write an import that takes only types as import type { … }. The form import { type A } leaves an empty import import {} from "…" in the JavaScript, which still loads the module.
  • In a Node.js project on CommonJS, you get the error “ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'”. Switch to ES modules (the type field set to module in package.json) or turn this option off.

Related entries

#

Spotted a mistake or missing an example? Write to us.