"verbatimModuleSyntax"

Les imports sans le mot type restent inchangés dans le JavaScript, il faut donc marquer explicitement les imports de types.

Sur cette page

Exemple

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

Définition et utilisation

#

L’option verbatimModuleSyntax introduit une règle simple : un import ou un export sans le mot type arrive dans le JavaScript généré exactement tel qu’il a été écrit, et import type disparaît entièrement. Le compilateur cesse de deviner lui-même quels imports supprimer parce qu’ils ne servent qu’aux types.

Le résultat est ainsi prévisible et identique dans tous les outils qui traduisent les fichiers un par un, comme esbuild, SWC ou Babel. Un import de type non marqué échoue avec une erreur, on voit donc immédiatement ce qui restera dans le code. L’option active aussi toutes les vérifications de isolatedModules.

Elle est apparue dans TypeScript 5.0 et a remplacé les anciennes options importsNotUsedAsValues et preserveValueImports. Elle convient surtout aux projets en modules ES. Dans les fichiers compilés en CommonJS, elle interdit la syntaxe import et export, car on ne peut pas y laisser cette syntaxe inchangée.

Syntaxe

#
Syntaxe
"verbatimModuleSyntax": true

Plus d’exemples

#
Un import de type non marqué
TypeScript
import { Course, formatTitle } from './course'
// Erreur : 'Course' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.
Ce qui reste dans le 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})`)
}

// Résultat de la compilation :
// import {} from './lesson';
// import { formatTitle } from './format';
// export function heading(course, lesson, badge) { … }

Bonnes pratiques

#
  • Vous démarrez un nouveau projet avec un bundler ? Activez verbatimModuleSyntax plutôt que le seul isolatedModules. Vous obtenez les mêmes vérifications et une seule règle simple pour les imports.
  • Écrivez un import dont vous ne prenez que des types sous la forme import type { … }. La version import { type A } laisse dans le JavaScript un import vide import {} from "…", qui charge quand même le module.
  • Dans un projet Node.js en CommonJS, vous obtiendrez l’erreur « ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax' ». Passez aux modules ES (le champ type valant module dans package.json) ou désactivez cette option.

Entrées associées

#

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.