TypeScript Module: import, export und import type

Ein TypeScript-Modul ist eine Datei mit mindestens einem import oder export auf oberster Ebene. Alles, was darin deklariert wird, ist privat für die Datei, solange du es nicht mit export freigibst, und andere Dateien holen sich mit import, was sie brauchen. Die Syntax ist die ES-Modul-Syntax von JavaScript plus einige Formen nur für Typen.

// math.ts: this file is a module because it has exports.
export interface Point {
  x: number;
  y: number;
}

export const ORIGIN: Point = { x: 0, y: 0 };

export function distance(a: Point, b: Point): number {
  return Math.hypot(b.x - a.x, b.y - a.y);
}

// One default export per file, at most.
export default function describe(p: Point): string {
  return `(${p.x}, ${p.y})`;
}

const secret = 42; // not exported: invisible to other files

console.log(describe({ x: 3, y: 4 }), distance(ORIGIN, { x: 3, y: 4 })); // (3, 4) 5

Benannte und Default-Exports

Ein Projekt hat viele Dateien, die importierende Seite sieht also so aus. Der Default-Export wird ohne geschweifte Klammern importiert und kann jeden Namen bekommen; benannte Exports stehen in geschweiften Klammern und behalten ihre Namen, außer du benennst sie mit as um.

// main.ts
import describe, { distance, ORIGIN, type Point } from "./math.js";
import { distance as dist } from "./math.js"; // renamed on import
import * as math from "./math.js";            // everything, as one object

const p: Point = { x: 6, y: 8 };
console.log(describe(p), distance(ORIGIN, p), dist(p, p), math.ORIGIN);

Mit Re-Exports sammelt eine Datei (oft index.ts) die öffentliche API eines Ordners. Das Verhalten reiner JavaScript-Module, etwa Live Bindings und Modul-Caching, wird unter ES-Module erklärt.

import type und export type

Typen existieren zur Laufzeit nicht, also gibt es bei einem Import, der nur als Typ verwendet wird, nichts zu laden. import type sagt das ausdrücklich, und die Anweisung verschwindet aus der JavaScript-Ausgabe. Der Modifikator type funktioniert auch für einen einzelnen Namen in einem normalen Import.

import type { User } from "./models.js";        // whole statement erased
import { saveUser, type Settings } from "./api.js"; // only saveUser survives

export type { User };                            // re-export a type only
export type UserId = User["id"];

Auch ohne das Schlüsselwort entfernt TypeScript Namen, von denen es sieht, dass sie nur Typen sind. Zwei Einstellungen machen das Schlüsselwort zur Pflicht:

• verbatimModuleSyntax: true behält jeden Import, der nicht mit type markiert ist, ein unmarkierter Typimport ist also der Fehler TS1484: 'Point' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.
• Werden .ts-Dateien direkt in Node ausgeführt (Type Stripping), entfernt Node Typannotationen, schaut aber nicht in andere Dateien. Ein unmarkiertes import { Point } bleibt im Code, und Node scheitert zur Laufzeit mit SyntaxError: The requested module './math.ts' does not provide an export named 'Point'.

type bei jedem reinen Typimport zu schreiben funktioniert in beiden Fällen, daher lohnt es sich, das zur Gewohnheit zu machen.

Cannot Find Module

Führt der Pfad in einem Import zu keiner Datei und keinem Paket mit Typen, bricht der Compiler mit dem Fehler TS2307 ab. Führe diesen Block aus, um ihn zu sehen:

// This does not compile: there is no utils file next to this one.
import { formatPrice } from "./utils.js";

console.log(formatPrice(9.5));

Die Ausgabe ist index.ts(2,29): error TS2307: Cannot find module './utils.js' or its corresponding type declarations. Die üblichen Ursachen:

• Ein Tippfehler in einem relativen Pfad oder ein fehlendes ./ (ohne das wird der Name in node_modules gesucht).
• Ein JavaScript-Paket ohne mitgelieferte Typen: Installiere @types/{package}, falls es existiert, oder schreibe eine Deklarationsdatei dafür.
• Ein Unterpfad, den das Paket nicht im Feld exports seiner package.json aufführt. Unter der Auflösung node16, nodenext und bundler lassen sich nur aufgeführte Einstiegspunkte importieren.

ES-Module oder CommonJS als Ausgabe

Du schreibst immer import und export. Die Option module in tsconfig.json entscheidet, welches JavaScript herauskommt.

// Source, the same in both cases
import { add } from "./math.js";
console.log(add(1, 2));

// module: nodenext, in a package with "type": "module"
import { add } from "./math.js";
console.log(add(1, 2));

// module: nodenext, in a package without "type": "module"
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const math_js_1 = require("./math.js");
console.log((0, math_js_1.add)(1, 2));

Mit node16, node18, node20 oder nodenext folgt TypeScript für jede Datei den Regeln von Node:

Mit module: "esnext" oder "preserve" behält die Ausgabe import/export, was Bundler wie Vite und esbuild erwarten. Die Unterschiede der beiden Modulsysteme zur Laufzeit stehen unter CommonJS vs ESM.

Dateiendungen in Imports

Unter module: node16 oder nodenext muss eine ES-Modul-Datei die Datei nennen, die Node tatsächlich lädt, und das ist die kompilierte .js-Datei. TypeScript bildet ./math.js für die Typprüfung zurück auf math.ts ab.

import { add } from "./math";    // error TS2835 in an ES module file
import { add } from "./math.js"; // correct: the path as it exists after compiling

Der Fehlertext lautet Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './math.js'? CommonJS-Dateien dürfen bei denselben Einstellungen die Endung weglassen, weil require Endungen selbst ausprobiert.

Zwei andere Konfigurationen ändern die Regel:

• moduleResolution: "bundler" (mit module auf esnext, preserve oder commonjs) akzeptiert ./math ohne Endung, da der Bundler es auflöst.
• rewriteRelativeImportExtensions: true erlaubt dir, ./math.ts zu schreiben, also denselben Pfad, der funktioniert, wenn Node die .ts-Datei direkt ausführt, und schreibt ihn in der Ausgabe zu ./math.js um.

Modulauflösung und paths

Bei einem nackten Namen wie "zod" sucht TypeScript in node_modules, liest die package.json des Pakets (die Felder exports und types) und greift ersatzweise auf node_modules/@types/zod zurück. Relative Namen (./, ../) werden von der importierenden Datei aus aufgelöst. Auch eine .json-Datei lässt sich importieren; die dafür nötigen Einstellungen stehen auf der Seite zu JSON.

paths in tsconfig.json fügt Aliasse für deine eigenen Ordner hinzu:

{
    "compilerOptions": {
        "module": "esnext",
        "moduleResolution": "bundler",
        "paths": {
            "@lib/*": ["./src/lib/*"]
        }
    }
}

paths wirkt nur auf die Typprüfung. In der erzeugten Datei steht weiterhin import { v } from "@lib/util", also muss etwas anderes das zur Laufzeit auflösen: ein Bundler mit demselben Alias oder das Feld imports in der package.json von Node (Aliasse, die mit # beginnen, wie "#lib/*": "./dist/lib/*"), das ohne zusätzliches Tool funktioniert. baseUrl gibt es in TypeScript 7 nicht mehr (Fehler TS5102); schreibe die Einträge in paths relativ zur tsconfig.json mit einem führenden ./.