declaration în TypeScript

"compilerOptions": { "declaration": true }

tsc --declaration
tsc -d

Ce face declaration

Un fișier .d.ts conține doar tipurile unui modul: semnăturile funcțiilor, interfețele, tipurile constantelor, fără cod. Când publici o bibliotecă pe npm, publici JavaScript-ul (care rulează) și fișierele .d.ts (care dau tipuri celor care o folosesc). Cu declaration, tsc le generează automat din surse.

Comentariile JSDoc (/** ... */) sunt păstrate în .d.ts, deci apar în editorul celui care folosește biblioteca. Tipurile deduse (de exemplu tipul de return number al lui cuTva) sunt scrise explicit.

Implicit este false, dar devine true când composite este true. tsc --init din 5.9 o pornește. Fișierele .d.ts ajung lângă .js, în outDir, sau în declarationDir dacă este setat.

Parametri

Parametru	Descriere
true	Se generează câte un .d.ts pentru fiecare fișier sursă.
false	Valoarea implicită (dacă composite nu este pornit).

Exemple

Exemplul 1: Biblioteca și declarațiile ei

Din magazin.ts rezultă magazin.js și magazin.d.ts. În .d.ts, funcția are tipul de return scris și comentariul păstrat, iar constanta are tipul literal "lei".

// tsconfig.json
{
  "compilerOptions": {
    "module": "nodenext",
    "target": "es2022",
    "declaration": true,
    "outDir": "dist"
  }
}

// src/magazin.ts
export interface Produs {
  nume: string;
  pret: number;
}

/** Prețul cu TVA (19%). */
export function cuTva(p: Produs) {
  return Math.round(p.pret * 1.19 * 100) / 100;
}

export const MONEDA = "lei";

Rezultat (tsc 5.9)

$ npx tsc && find dist -type f | sort
dist/magazin.d.ts
dist/magazin.js

$ cat dist/magazin.d.ts
export interface Produs {
    nume: string;
    pret: number;
}
/** Prețul cu TVA (19%). */
export declare function cuTva(p: Produs): number;
export declare const MONEDA = "lei";

Greșeli frecvente

• Să scrii de mână fișierele .d.ts pentru codul tău TypeScript. Lasă tsc să le genereze; scrise de mână se desincronizează repede.
• Să publici pachetul fără câmpul "types" (sau exports cu condiția "types") în package.json. Cei care îl folosesc nu găsesc declarațiile.

Comenzi înrudite

• declarationMap: Generează hărți .d.ts.map, ca „Go to Definition” din editor să ducă la sursa .ts, nu la fișierul .d.ts.
• emitDeclarationOnly: tsc scrie doar fișierele .d.ts, fără .js; JavaScript-ul este produs de altă unealtă (esbuild, Babel, swc).
• declarationDir: Directorul în care se scriu fișierele .d.ts, separat de outDir unde ajunge JavaScript-ul.
• isolatedDeclarations: Cere tipuri scrise explicit pe exporturi, ca fișierele .d.ts să poată fi generate fișier cu fișier, fără verificarea tipurilor.
• stripInternal: Scoate din fișierele .d.ts declarațiile marcate cu /** @internal */, ca să nu apară în API-ul public.