moduleDetection în TypeScript

"compilerOptions": { "moduleDetection": "force" }

Ce face moduleDetection

Un fișier fără import/export este tratat de TypeScript ca script: variabilele lui de la nivelul de sus sunt globale și se ciocnesc cu cele din alte scripturi (eroarea TS2451, „Cannot redeclare block-scoped variable”). Un modul are scope propriu.

auto (implicit) consideră modul un fișier care are import, export, import.meta, JSX cu react-jsx sau care este modul ES după regulile lui module: node16+. force tratează orice fișier (în afară de .d.ts) ca modul. legacy folosește doar regula veche: modul = are import/export.

module node16/node18/node20/nodenext fixează force, iar tsc --init din 5.9 scrie "moduleDetection": "force".

Parametri

Parametru	Descriere
auto	Valoarea implicită. Modul dacă are import/export, import.meta, JSX nou sau este ESM după package.json.
force	Orice fișier este modul.
legacy	Modul doar dacă are import/export.

Exemple

Exemplul 1: Două scripturi cu aceeași variabilă

Cu auto, ambele fișiere sunt scripturi, deci oras este global și declarat de două ori. Cu force, fiecare fișier are scope propriu și nu mai e nicio eroare.

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2022",
    "moduleDetection": "auto",
    "noEmit": true
  }
}

// a.ts
const oras = "Iași";
console.log(oras);

// b.ts
const oras = "Cluj";
console.log(oras);

Rezultat (tsc 5.9)

$ npx tsc
a.ts(1,7): error TS2451: Cannot redeclare block-scoped variable 'oras'.
b.ts(1,7): error TS2451: Cannot redeclare block-scoped variable 'oras'.

$ npx tsc --moduleDetection force

Exemplul 2: Efectul la generare

Cu force și module: commonjs, fișierul devine modul CommonJS, cu antetul obișnuit. Cu auto, rămâne script.

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

// a.ts
const oras = "Iași";
console.log(oras);

Rezultat (tsc 5.9)

$ npx tsc && cat a.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const oras = "Iași";
console.log(oras);

$ npx tsc --moduleDetection auto && cat a.js
const oras = "Iași";
console.log(oras);

Greșeli frecvente

• Să adaugi export {} în fiecare fișier ca să scapi de TS2451. "moduleDetection": "force" face același lucru pentru tot proiectul.

Comenzi înrudite

• module: Alege formatul de module din JavaScript-ul generat (ES modules, CommonJS) și regulile de import pe care le verifică tsc.
• alwaysStrict: Verifică fiecare fișier în modul strict al JavaScript și scrie „use strict” în fișierele .js generate.
• isolatedModules: Dă eroare pentru codul care nu poate fi transformat corect fișier cu fișier (de esbuild, Babel, swc sau Node.js).