Make type/value intent explicit
A codebase wants generated JavaScript to reflect whether each module declaration is a runtime value or type-only dependency.
TypeScript · Const
verbatimModuleSyntax
verbatimModuleSyntax makes module emit follow the import/export syntax you write: unmarked declarations remain, while type-marked declarations are erased. It also prevents ECMAScript module syntax from being rewritten into CommonJS.
- Since
- TypeScript 5.0
How it works
Enable this compiler option to make module emit follow the source syntax. Imports and exports marked with type are removed because they serve only type analysis; unmarked forms remain, and ECMAScript syntax is not rewritten into CommonJS syntax. For CommonJS output, use TypeScript’s import = require and export = forms.
Syntax
{
"compilerOptions": {
"verbatimModuleSyntax": true
}
}Parameters
| Name | Type | Description |
|---|---|---|
verbatimModuleSyntax | boolean | Boolean compiler option; enable it with true or the --verbatimModuleSyntax command-line flag. |
Returns
No runtime return value; this is a compiler configuration option.
Key points
- The option was introduced in TypeScript 5.0.
- Unmarked imports and exports are preserved in the generated JavaScript.
- The
typemodifier makes an import or export type-only and removes it from emitted JavaScript. - The setting makes the runtime-versus-type purpose of module declarations explicit in source code.
- It turns module-format mismatches into explicit compiler feedback rather than silently transforming syntax.
Common mistakes
- ES module syntax is not converted to CommonJS; use
import = requireandexport =when the emitted module kind is CommonJS. - A type-only import or export disappears from JavaScript, so do not use the
typemodifier for bindings whose runtime side effects or values are needed. importsNotUsedAsValuesandpreserveValueImportsare superseded by this option.
Example: Mark type-only module syntax explicitly
import { type User, createUser } from "./users.js";
export type { User };
export { createUser };Type-only imports and exports are erased, while value imports and exports remain in the emitted JavaScript.
When to use it
Validate mixed module formats
A Node.js project mixes mostly ESM with a small number of CommonJS files and needs module syntax checked against output.
Modernize compiler configuration
A project is replacing older import-elision configuration flags with one clearer rule set.
Interview questions
QWhat does verbatimModuleSyntax change about import and export emit?
It makes the emit rules explicit: unmarked imports and exports stay, while forms using the type modifier are removed. This replaces the more complicated interaction among import elision-related options.
Follow-up: What happens when ESM syntax is used for a CommonJS-emitting file? It produces an error instead of rewriting the syntax to require calls.
QHow does the type modifier affect emitted code?
The modifier identifies declarations needed only for type analysis. Such declarations are omitted from the JavaScript output, while value-bearing declarations remain.
Follow-up: How can a mixed named import express both roles? Write a normal value name and mark type-only names individually, such as import { value, type Shape } from "pkg".
QHow should CommonJS files be written with this option enabled?
When CommonJS output is intended, use TypeScript’s older CommonJS-oriented syntax: import x = require("x") and export = value. Verbatim ESM syntax is not rewritten under this option.
Follow-up: Why can this expose configuration mistakes? The compiler reports a mismatch between the source module syntax and the module kind implied by settings or file extensions.
Related
importsNotUsedAsValuespreserveValueImportsisolatedModulesmoduleimport typeexport type