allowJs în TypeScript

"compilerOptions": {
  "allowJs": true,
  "outDir": "dist"
}

Ce face allowJs

La trecerea unui proiect de la JavaScript la TypeScript, nu rescrii totul dintr-odată. Cu allowJs, fișierele .js fac parte din program: le poți importa din .ts, tsc le deduce tipurile (inclusiv din comentariile JSDoc, @param {number}) și le scrie în outDir împreună cu restul.

Fără allowJs, importul unui fișier .js local dă eroarea TS7016 (cu noImplicitAny), iar fișierul nu este copiat. Erorile de tip din fișierele .js nu sunt raportate decât cu checkJs. Ai nevoie de outDir: altfel tsc ar scrie vechi.js peste el însuși (TS5055).

maxNodeModuleJsDepth (implicit 0) privește pachetele din node_modules care au doar JavaScript, fără .d.ts. Cu 0, tsc nu le citește. Cu 1 sau mai mult, citește fișierele lor JavaScript până la acea adâncime de dependențe și le deduce tipurile. Funcționează doar cu allowJs. Implicit allowJs este false.

Parametri

Parametru	Descriere
allowJs: true	Fișierele .js/.jsx sunt incluse în program.
maxNodeModuleJsDepth: n	Cât de adânc în node_modules citește tsc pachetele fără tipuri. Implicit 0.

Exemple

Exemplul 1: Funcție din JavaScript folosită în TypeScript

vechi.js are tipurile descrise în JSDoc. Cu allowJs, tsc le folosește: un argument text este refuzat. Fără allowJs, importul ar da eroarea TS7016.

// tsconfig.json
{
  "compilerOptions": {
    "module": "nodenext",
    "strict": true,
    "allowJs": true,
    "outDir": "dist"
  }
}

// src/vechi.js
/**
 * @param {number} pret
 * @param {number} cantitate
 */
export function total(pret, cantitate) {
  return pret * cantitate;
}

// src/index.ts
import { total } from "./vechi.js";

console.log(total(12.5, 4));
console.log(total("12", 4));

Rezultat (tsc 5.9)

$ npx tsc
src/index.ts(4,19): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

$ npx tsc --allowJs false
src/index.ts(1,23): error TS7016: Could not find a declaration file for module './vechi.js'. '/proiect/src/vechi.js' implicitly has an 'any' type.

Exemplul 2: Fișierele generate

După ce scoți apelul greșit, dist conține și fișierul JavaScript copiat, iar programul rulează.

// src/index.ts
import { total } from "./vechi.js";

console.log(total(12.5, 4));

Rezultat (tsc 5.9)

$ npx tsc && find dist -type f | sort
dist/index.js
dist/vechi.js

$ node dist/index.js
50

Exemplul 3: Pachet fără tipuri și maxNodeModuleJsDepth

Pachetul vechi din node_modules are doar index.js. Cu adâncimea implicită 0, tsc nu îl citește. Cu 1, îl citește și deduce tipurile.

// node_modules/vechi/index.js
export function dublu(x) { return x * 2; }

// index.ts  (tsconfig: "module": "nodenext", "allowJs": true, "strict": true, "noEmit": true)
import { dublu } from "vechi";
console.log(dublu(21));

Rezultat (tsc 5.9)

$ npx tsc
index.ts(1,23): error TS7016: Could not find a declaration file for module 'vechi'. '/proiect/node_modules/vechi/index.js' implicitly has an 'any' type.

$ npx tsc --maxNodeModuleJsDepth 1 --listFilesOnly
/proiect/node_modules/vechi/index.js
/proiect/index.ts

Greșeli frecvente

• Să pornești allowJs fără outDir când fișierele .js sunt lângă sursă: eroarea TS5055 („would overwrite input file”).
• Să crezi că allowJs verifică fișierele .js. Doar le include; pentru erori ai nevoie de checkJs.

Comenzi înrudite

• checkJs: Raportează erorile de tip și în fișierele .js, folosind tipurile deduse și comentariile JSDoc.
• outDir: Directorul în care tsc scrie fișierele generate, cu aceeași structură de subdirectoare ca sursele.
• declaration: Generează lângă fiecare fișier .js un fișier .d.ts cu tipurile lui, ca alte proiecte să-l poată folosi cu tipuri.
• noImplicitAny: Dă eroare când TypeScript nu poate deduce un tip și ar folosi în tăcere any (de obicei la parametrii fără tip).