Moduły w TypeScript: import, export i import type

Moduł w TypeScript to plik z co najmniej jednym import lub export na najwyższym poziomie. Wszystko, co jest w nim zadeklarowane, jest prywatne dla pliku, dopóki tego nie wyeksportujesz przez export, a inne pliki importują przez import to, czego potrzebują. Składnia to składnia ES modules z JavaScriptu plus kilka form tylko dla typów.

// 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

Eksporty nazwane i domyślne

Projekt ma wiele plików, więc strona importująca wygląda tak. Eksport domyślny importuje się bez nawiasów klamrowych i można nadać mu dowolną nazwę; eksporty nazwane idą w nawiasy klamrowe i zachowują swoje nazwy, chyba że zmienisz je przez as.

// 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);

Ponowne eksporty pozwalają jednemu plikowi (często index.ts) zebrać publiczne API folderu. Zachowanie modułów w zwykłym JavaScripcie, takie jak live bindings i cache modułów, opisuje strona ES modules.

import type i export type

Typy nie istnieją w czasie działania, więc import używany tylko jako typ nie ma czego wczytać. import type mówi to wprost, a instrukcja znika z wyjściowego JavaScriptu. Modyfikator type działa też przy pojedynczej nazwie w zwykłym imporcie.

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"];

Bez tego słowa kluczowego TypeScript i tak usuwa nazwy, o których wie, że są tylko typami. Dwa ustawienia sprawiają, że słowo kluczowe jest wymagane:

• verbatimModuleSyntax: true zachowuje każdy import, który nie jest oznaczony type, więc nieoznaczony import typu to błąd TS1484: 'Point' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.
• Uruchamianie plików .ts bezpośrednio w Node (type stripping) usuwa adnotacje typów, ale nie zagląda do innych plików. Nieoznaczone import { Point } zostaje w kodzie, a Node kończy się błędem w czasie działania: SyntaxError: The requested module './math.ts' does not provide an export named 'Point'.

Pisanie type przy każdym imporcie samych typów działa w obu przypadkach, więc warto wyrobić sobie ten nawyk.

Cannot find module

Gdy ścieżka w imporcie nie prowadzi do pliku ani do pakietu z typami, kompilator zatrzymuje się z błędem TS2307. Uruchom ten przykład, żeby go zobaczyć:

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

console.log(formatPrice(9.5));

Wynik to index.ts(2,29): error TS2307: Cannot find module './utils.js' or its corresponding type declarations. Typowe przyczyny:

• Literówka w ścieżce względnej albo brak ./ (bez niego nazwa jest szukana w node_modules).
• Pakiet JavaScript bez dołączonych typów: zainstaluj @types/{package}, jeśli istnieje, albo napisz dla niego plik deklaracji.
• Ścieżka podrzędna, której pakiet nie wymienia w polu exports swojego package.json. Przy rozwiązywaniu node16, nodenext i bundler można importować tylko wymienione punkty wejścia.

Wyjście jako ES modules lub CommonJS

Zawsze piszesz import i export. Opcja module w tsconfig.json decyduje, jaki JavaScript powstaje.

// 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));

Przy node16, node18, node20 lub nodenext TypeScript stosuje dla każdego pliku reguły samego Node:

Przy module: "esnext" lub "preserve" wyjście zachowuje import/export, czego oczekują bundlery takie jak Vite i esbuild. Różnice między tymi dwoma systemami modułów w czasie działania opisuje strona CommonJS a ESM.

Rozszerzenia plików w importach

Przy module: node16 lub nodenext plik ES module musi wskazywać plik, który Node faktycznie wczyta, a jest nim skompilowany plik .js. Do sprawdzania typów TypeScript mapuje ./math.js z powrotem na math.ts.

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

Treść błędu to Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './math.js'? Pliki CommonJS przy tych samych ustawieniach mogą pomijać rozszerzenie, bo require sam próbuje rozszerzeń.

Dwie inne konfiguracje zmieniają tę regułę:

• moduleResolution: "bundler" (z module ustawionym na esnext, preserve lub commonjs) akceptuje ./math bez rozszerzenia, bo rozwiązuje je bundler.
• rewriteRelativeImportExtensions: true pozwala pisać ./math.ts, czyli tę samą ścieżkę, która działa, gdy Node uruchamia plik .ts bezpośrednio, i przepisuje ją na ./math.js w wyjściu.

Rozwiązywanie modułów i paths

Dla samej nazwy, takiej jak "zod", TypeScript szuka w node_modules, czyta package.json pakietu (pola exports i types), a w ostateczności sięga do node_modules/@types/zod. Nazwy względne (./, ../) są rozwiązywane względem pliku importującego. Można też zaimportować plik .json; potrzebne do tego ustawienia są na stronie JSON.

paths w tsconfig.json dodaje aliasy dla twoich własnych folderów:

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

paths wpływa tylko na sprawdzanie typów. Wygenerowany plik nadal zawiera import { v } from "@lib/util", więc w czasie działania musi to rozwiązać coś innego: bundler skonfigurowany z tym samym aliasem albo pole imports Node w package.json (aliasy zaczynające się od #, jak "#lib/*": "./dist/lib/*"), które działa bez dodatkowych narzędzi. baseUrl nie istnieje w TypeScript 7 (błąd TS5102); zapisuj wpisy paths względem tsconfig.json, z ./ na początku.