Module: TypeScript

[Verlauf]

Version	Änderungen
v22.7.0	Flag --experimental-transform-types hinzugefügt.

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.1 - Aktive Entwicklung

Aktivierung

Es gibt zwei Möglichkeiten, die Runtime-TypeScript-Unterstützung in Node.js zu aktivieren:

Volle TypeScript-Unterstützung

Um TypeScript mit voller Unterstützung für alle TypeScript-Funktionen, einschließlich tsconfig.json, zu verwenden, können Sie ein Drittanbieterpaket verwenden. Diese Anweisungen verwenden tsx als Beispiel, aber es gibt viele andere ähnliche Bibliotheken.

Typ-Stripping

Hinzugefügt in: v22.6.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.1 - Aktive Entwicklung

Das Flag --experimental-strip-types ermöglicht es Node.js, TypeScript-Dateien auszuführen. Standardmäßig führt Node.js nur Dateien aus, die keine TypeScript-Funktionen enthalten, die eine Transformation erfordern, wie z. B. Enums oder Namespaces. Node.js ersetzt Inline-Typannotationen durch Leerzeichen, und es wird keine Typüberprüfung durchgeführt. Um die Transformation solcher Funktionen zu aktivieren, verwenden Sie das Flag --experimental-transform-types. TypeScript-Funktionen, die von Einstellungen innerhalb von tsconfig.json abhängen, wie z. B. Pfade oder die Konvertierung neuerer JavaScript-Syntax in ältere Standards, werden absichtlich nicht unterstützt. Um volle TypeScript-Unterstützung zu erhalten, siehe Volle TypeScript-Unterstützung.

Das Typ-Stripping-Feature ist als leichtgewichtig konzipiert. Indem es absichtlich keine Syntaxen unterstützt, die JavaScript-Code-Generierung erfordern, und indem es Inline-Typen durch Leerzeichen ersetzt, kann Node.js TypeScript-Code ohne die Notwendigkeit von Source Maps ausführen.

Das Typ-Stripping funktioniert mit den meisten Versionen von TypeScript, aber wir empfehlen Version 5.7 oder neuer mit den folgenden tsconfig.json-Einstellungen:

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

Modulsystem bestimmen

Node.js unterstützt sowohl CommonJS als auch ES Modules Syntax in TypeScript-Dateien. Node.js wird nicht von einem Modulsystem in ein anderes konvertieren; wenn Ihr Code als ES-Modul laufen soll, müssen Sie die import- und export-Syntax verwenden, und wenn Ihr Code als CommonJS laufen soll, müssen Sie require und module.exports verwenden.

• Bei .ts-Dateien wird das Modulsystem auf die gleiche Weise bestimmt wie bei .js-Dateien. Um die import- und export-Syntax zu verwenden, fügen Sie "type": "module" zur nächstgelegenen übergeordneten package.json-Datei hinzu.
• .mts-Dateien werden immer als ES-Module ausgeführt, ähnlich wie .mjs-Dateien.
• .cts-Dateien werden immer als CommonJS-Module ausgeführt, ähnlich wie .cjs-Dateien.
• .tsx-Dateien werden nicht unterstützt.

Wie in JavaScript-Dateien sind Dateierweiterungen in import-Anweisungen und import()-Ausdrücken obligatorisch: import './file.ts', nicht import './file'. Aus Gründen der Abwärtskompatibilität sind Dateierweiterungen auch in require()-Aufrufen obligatorisch: require('./file.ts'), nicht require('./file'), ähnlich wie die .cjs-Erweiterung in require-Aufrufen in CommonJS-Dateien obligatorisch ist.

Die tsconfig.json-Option allowImportingTsExtensions ermöglicht es dem TypeScript-Compiler tsc, Dateien mit import-Spezifizierern, die die .ts-Erweiterung enthalten, typgeprüft zu verarbeiten.

TypeScript-Funktionen

Da Node.js nur Inline-Typen entfernt, führen alle TypeScript-Funktionen, die eine Ersetzung der TypeScript-Syntax durch neue JavaScript-Syntax beinhalten, zu einem Fehler, es sei denn, der Flag --experimental-transform-types wird übergeben.

Die wichtigsten Funktionen, die eine Transformation erfordern, sind:

• Enum
• namespaces
• legacy module
• Parameter-Eigenschaften

Da Decorators derzeit ein TC39 Stage 3 Proposal sind und bald von der JavaScript-Engine unterstützt werden, werden sie nicht transformiert und führen zu einem Parserfehler. Dies ist eine vorübergehende Einschränkung und wird in Zukunft behoben.

Darüber hinaus liest Node.js keine tsconfig.json-Dateien und unterstützt keine Funktionen, die von Einstellungen in tsconfig.json abhängen, wie z. B. Pfade oder die Umwandlung neuerer JavaScript-Syntax in ältere Standards.

Importieren von Typen ohne type-Schlüsselwort

Aufgrund der Natur des Typ-Strippings ist das Schlüsselwort type erforderlich, um Typ-Importe korrekt zu entfernen. Ohne das Schlüsselwort type behandelt Node.js den Import als Wertimport, was zu einem Laufzeitfehler führt. Die tsconfig-Option verbatimModuleSyntax kann verwendet werden, um dieses Verhalten anzupassen.

Dieses Beispiel funktioniert korrekt:

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

Dies führt zu einem Laufzeitfehler:

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

Nicht-Datei-Formen der Eingabe

Type-Stripping kann für --eval aktiviert werden. Das Modulsystem wird durch --input-type bestimmt, wie es auch für JavaScript der Fall ist.

TypeScript-Syntax wird in der REPL, STDIN-Eingabe, --print, --check und inspect nicht unterstützt.

Source Maps

Da Inline-Typen durch Leerzeichen ersetzt werden, sind Source Maps für korrekte Zeilennummern in Stack-Traces unnötig; und Node.js generiert sie nicht. Wenn --experimental-transform-types aktiviert ist, sind Source Maps standardmäßig aktiviert.

Type Stripping in Abhängigkeiten

Um Paketautoren davon abzuhalten, in TypeScript geschriebene Pakete zu veröffentlichen, weigert sich Node.js standardmäßig, TypeScript-Dateien innerhalb von Ordnern unter einem node_modules-Pfad zu verarbeiten.

Pfadaliase

tsconfig "paths" werden nicht transformiert und erzeugen daher einen Fehler. Die am nächsten kommende verfügbare Funktion sind Subpath-Importe mit der Einschränkung, dass sie mit # beginnen müssen.