"verbatimModuleSyntax"
Imports without the word type stay in JavaScript unchanged, so type imports must be marked explicitly.
Example
#{
"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
#"verbatimModuleSyntax": trueMore examples
#import { Course, formatTitle } from './course'
// Error: 'Course' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.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
verbatimModuleSyntaxinstead of justisolatedModules. You get the same checks and one simple rule for imports. - Write an import that takes only types as
import type { … }. The formimport { type A }leaves an empty importimport {} 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
typefield set tomoduleinpackage.json) or turn this option off.
Related entries
#- import typeA type-only import that disappears completely from the generated JavaScript.
- "isolatedModules"Makes sure every file can be translated to JavaScript on its own, without knowing about the rest of the project.
- "module"The module format of the generated code and how imports are understood.
- "moduleResolution"The algorithm the compiler uses to find the files named in imports.
- "esModuleInterop"Makes it easier to import CommonJS packages with ES module syntax.
Spotted a mistake or missing an example? Write to us.