module în TypeScript

"compilerOptions": { "module": "nodenext" }

tsc --module nodenext
tsc -m nodenext

Ce face module

module spune ce fel de module scrie tsc în fișierele .js: cu import/export (module ES) sau cu require/module.exports (CommonJS). Valorile node16, node18, node20 și nodenext fac mai mult: imită regulile reale din Node.js. Un fișier .ts devine modul ES dacă cel mai apropiat package.json are "type": "module" (sau dacă fișierul este .mts) și CommonJS altfel (sau dacă este .cts).

Valorile node* și preserve stabilesc și alte opțiuni: moduleResolution, esModuleInterop, resolveJsonModule și altele (vezi exemplul cu --showConfig). preserve (TypeScript 5.4) lasă importurile exact cum sunt scrise și este pentru proiectele în care un bundler (Vite, esbuild, webpack) face pasul final.

Fără module în tsconfig, valoarea este calculată din target: commonjs pentru target es5 (implicit), es6/es2015 pentru ținte mai noi. tsc --init din 5.9 scrie "module": "nodenext". Pentru cod rulat direct de Node.js, alege nodenext; pentru o aplicație web cu bundler, preserve sau esnext.

Parametri

Parametru	Descriere
nodenext	Regulile celei mai noi versiuni Node.js; formatul fiecărui fișier vine din package.json și din extensie.
node16, node18, node20	Regulile fixe ale acelor versiuni Node.js (de exemplu node20 permite require() de module ES).
preserve	Importurile rămân cum sunt scrise; pentru bundlere. Implică moduleResolution: bundler.
es2015 (es6), es2020, es2022, esnext	Module ES (import/export). Diferă prin ce sintaxă nouă permit (de exemplu import.meta, await la nivelul de sus din es2022).
commonjs	require și exports, formatul vechi din Node.js.
amd, umd, system, none	Formate vechi, pentru încărcătoare de module din browser. Rar folosite azi.

Exemple

Exemplul 1: Același import, două formate

Cu commonjs, importul devine require. Cu esnext, rămâne import. Rezultatul de mai jos este index.js pentru commonjs; cu "module": "esnext" (și importul scris "./calcul.js") index.js conține doar cele două rânduri din index.ts.

// tsconfig.json
{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2022"
  }
}

// calcul.ts
export function cuTva(pret: number): number {
  return Math.round(pret * 1.19 * 100) / 100;
}

// index.ts
import { cuTva } from "./calcul";

console.log(cuTva(100));

Rezultat (tsc 5.9)

$ npx tsc && cat index.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const calcul_1 = require("./calcul");
console.log((0, calcul_1.cuTva)(100));

Exemplul 2: nodenext și ce opțiuni stabilește

Cu "type": "module" în package.json, fișierele sunt module ES. --showConfig arată opțiunile stabilite automat de nodenext (inclusiv target, care aici era deja scris).

// package.json
{ "type": "module" }

// tsconfig.json
{
  "compilerOptions": {
    "module": "nodenext",
    "target": "es2022"
  }
}

Rezultat (tsc 5.9)

$ npx tsc --showConfig
{
    "compilerOptions": {
        "module": "nodenext",
        "target": "es2022",
        "moduleResolution": "nodenext",
        "moduleDetection": "force",
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true,
        "resolvePackageJsonExports": true,
        "resolvePackageJsonImports": true,
        "resolveJsonModule": true,
        "useDefineForClassFields": true
    },
    "files": [
        "./calcul.ts",
        "./index.ts"
    ]
}

Exemplul 3: Un modul ES care rulează

Exemplele de pe acest site sunt compilate cu --module nodenext ca fișiere .mts, adică module ES. Se pot folosi import din node:, import.meta și await la nivelul de sus. După compilare, fișierul rulat este exemplu.mjs.

import { basename } from "node:path";
import { setTimeout as asteapta } from "node:timers/promises";

console.log("fișier:", basename(import.meta.url));
await asteapta(10);
console.log("modul ES:", typeof require === "undefined");

Rezultat

fișier: exemplu.mjs
modul ES: true

Greșeli frecvente

• Să scrii "module": "nodenext" fără "type": "module" în package.json și să te miri că apare require în fișierele generate. Fișierele .ts sunt atunci CommonJS.
• Să alegi esnext pentru cod rulat direct de Node.js. tsc nu verifică atunci regulile Node.js (de exemplu extensia .js obligatorie în importuri), iar erorile apar la rulare.

Comenzi înrudite

• moduleResolution: Alege regulile după care tsc găsește fișierul din spatele unui import („./calcul.js”, „react”, „@/utile”).
• target: Versiunea de JavaScript generată: sintaxa mai nouă decât ținta este transformată în cod echivalent mai vechi.
• verbatimModuleSyntax: Importurile rămân exact cum sunt scrise; se șterg doar cele marcate cu type, deci tipurile trebuie importate cu import type.
• esModuleInterop: Face importul implicit (import x from „pachet”) al modulelor CommonJS să funcționeze corect, la verificare și la rulare.
• moduleDetection: Decide când un fișier este modul (cu scope propriu) și când este script global; force face din fiecare fișier un modul.