Modules : TypeScript

[Historique]

Version	Modifications
v22.7.0	Ajout de l'indicateur --experimental-transform-types.

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1.1 - Développement actif

Activation

Il existe deux manières d'activer la prise en charge de TypeScript au moment de l'exécution dans Node.js :

Prise en charge complète de TypeScript

Pour utiliser TypeScript avec une prise en charge complète de toutes les fonctionnalités de TypeScript, y compris tsconfig.json, vous pouvez utiliser un package tiers. Ces instructions utilisent tsx à titre d'exemple, mais de nombreuses autres bibliothèques similaires sont disponibles.

Suppression des types

Ajouté dans : v22.6.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1.1 - Développement actif

L'indicateur --experimental-strip-types permet à Node.js d'exécuter des fichiers TypeScript. Par défaut, Node.js n'exécutera que les fichiers qui ne contiennent aucune fonctionnalité TypeScript nécessitant une transformation, comme les énumérations ou les espaces de noms. Node.js remplacera les annotations de type intégrées par des espaces blancs, et aucune vérification de type ne sera effectuée. Pour activer la transformation de ces fonctionnalités, utilisez l'indicateur --experimental-transform-types. Les fonctionnalités TypeScript qui dépendent des paramètres de tsconfig.json, tels que les chemins d'accès ou la conversion d'une syntaxe JavaScript plus récente vers des normes plus anciennes, ne sont pas prises en charge intentionnellement. Pour obtenir une prise en charge complète de TypeScript, consultez la section Prise en charge complète de TypeScript.

La fonctionnalité de suppression des types est conçue pour être légère. En ne prenant pas en charge intentionnellement les syntaxes qui nécessitent une génération de code JavaScript, et en remplaçant les types intégrés par des espaces blancs, Node.js peut exécuter du code TypeScript sans avoir besoin de source maps.

La suppression des types fonctionne avec la plupart des versions de TypeScript, mais nous recommandons la version 5.7 ou une version plus récente avec les paramètres tsconfig.json suivants :

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true
  }
}

Détermination du système de modules

Node.js prend en charge les syntaxes CommonJS et ES Modules dans les fichiers TypeScript. Node.js ne convertira pas d'un système de modules à un autre ; si vous souhaitez que votre code s'exécute comme un module ES, vous devez utiliser la syntaxe import et export, et si vous souhaitez que votre code s'exécute comme CommonJS, vous devez utiliser require et module.exports.

• Le système de modules des fichiers .ts sera déterminé de la même manière que les fichiers .js. Pour utiliser la syntaxe import et export, ajoutez "type": "module" au fichier package.json parent le plus proche.
• Les fichiers .mts seront toujours exécutés comme des modules ES, de la même manière que les fichiers .mjs.
• Les fichiers .cts seront toujours exécutés comme des modules CommonJS, de la même manière que les fichiers .cjs.
• Les fichiers .tsx ne sont pas pris en charge.

Comme dans les fichiers JavaScript, les extensions de fichier sont obligatoires dans les instructions import et les expressions import() : import './file.ts', et non import './file'. Pour des raisons de compatibilité descendante, les extensions de fichier sont également obligatoires dans les appels require() : require('./file.ts'), et non require('./file'), de la même manière que l'extension .cjs est obligatoire dans les appels require dans les fichiers CommonJS.

L'option tsconfig.json allowImportingTsExtensions permettra au compilateur TypeScript tsc de vérifier le typage des fichiers avec des spécificateurs import qui incluent l'extension .ts.

Fonctionnalités TypeScript

Node.js ne supprimant que les types inline, toute fonctionnalité TypeScript impliquant le remplacement de la syntaxe TypeScript par une nouvelle syntaxe JavaScript entraînera une erreur, sauf si l'indicateur --experimental-transform-types est passé.

Les fonctionnalités les plus importantes nécessitant une transformation sont :

• Enum
• namespaces
• legacy module
• propriétés de paramètres

Les décorateurs étant actuellement une proposition TC39 de phase 3 et seront bientôt pris en charge par le moteur JavaScript, ils ne sont pas transformés et entraîneront une erreur d'analyse. Il s'agit d'une limitation temporaire qui sera résolue à l'avenir.

De plus, Node.js ne lit pas les fichiers tsconfig.json et ne prend pas en charge les fonctionnalités qui dépendent des paramètres de tsconfig.json, tels que les chemins ou la conversion d'une syntaxe JavaScript plus récente en des normes plus anciennes.

Importation de types sans le mot clé type

En raison de la nature de la suppression des types, le mot clé type est nécessaire pour supprimer correctement les importations de types. Sans le mot clé type, Node.js traitera l'importation comme une importation de valeur, ce qui entraînera une erreur d'exécution. L'option tsconfig verbatimModuleSyntax peut être utilisée pour correspondre à ce comportement.

Cet exemple fonctionnera correctement :

import type { Type1, Type2 } from './module.ts'
import { fn, type FnParams } from './fn.ts'

Ceci entraînera une erreur d'exécution :

import { Type1, Type2 } from './module.ts'
import { fn, FnParams } from './fn.ts'

Formes d'entrée non-fichier

La suppression des types peut être activée pour --eval. Le système de modules sera déterminé par --input-type, comme pour JavaScript.

La syntaxe TypeScript n'est pas prise en charge dans le REPL, l'entrée STDIN, --print, --check et inspect.

Source maps

Étant donné que les types inline sont remplacés par des espaces blancs, les source maps sont inutiles pour des numéros de ligne corrects dans les traces de pile ; et Node.js ne les génère pas. Lorsque --experimental-transform-types est activé, les source maps sont activées par défaut.

Suppression des types dans les dépendances

Pour décourager les auteurs de paquets de publier des paquets écrits en TypeScript, Node.js refusera par défaut de gérer les fichiers TypeScript dans les dossiers sous un chemin node_modules.

Alias de chemins

tsconfig "paths" ne sera pas transformé et produira donc une erreur. La fonctionnalité la plus proche disponible est les importations de sous-chemins avec la limitation qu'elles doivent commencer par #.