preserveSymlinks în TypeScript

"compilerOptions": { "preserveSymlinks": true }

Ce face preserveSymlinks

În monorepo-uri și cu npm link, un pachet din node_modules este adesea o legătură simbolică spre alt director. Implicit, tsc (ca și Node.js) urmează legătura și folosește calea reală a fișierului. Același pachet, ajuns pe două căi, este astfel recunoscut ca fiind același.

Cu preserveSymlinks, tsc păstrează calea prin legătură, ca node --preserve-symlinks. Se folosește doar când și rularea folosește acest mod; altfel, tipurile pot ajunge duplicate. Implicit: false.

Parametri

Parametru	Descriere
true	Calea prin legătura simbolică este păstrată.
false	Valoarea implicită: se folosește calea reală.

Exemple

Exemplul 1: Calea fișierului de tipuri

node_modules/culori este o legătură spre pachete/culori. Implicit, tsc folosește calea reală; cu --preserveSymlinks, folosește calea din node_modules (iar fișierul real apare separat, prins de include).

// pachete/culori/package.json
{ "name": "culori", "type": "module", "types": "./index.d.ts" }

// pachete/culori/index.d.ts
export declare const rosu: string;

// index.ts  (tsconfig: "module": "nodenext", "noEmit": true)
import { rosu } from "culori";
console.log(rosu);

Rezultat (tsc 5.9)

$ ln -s ../pachete/culori node_modules/culori
$ npx tsc --listFilesOnly
/proiect/pachete/culori/index.d.ts
/proiect/index.ts

$ npx tsc --listFilesOnly --preserveSymlinks
/proiect/node_modules/culori/index.d.ts
/proiect/index.ts
/proiect/pachete/culori/index.d.ts

Greșeli frecvente

• Să pornești opțiunea fără motiv. Același pachet poate apărea de două ori, iar tipurile lui nu mai sunt compatibile între ele (erori de tipul „Type X is not assignable to type X”).

Comenzi înrudite

• moduleResolution: Alege regulile după care tsc găsește fișierul din spatele unui import („./calcul.js”, „react”, „@/utile”).
• --listFilesOnly: Afișează fișierele care fac parte din compilare; –listFilesOnly se oprește aici, –listFiles compilează și apoi le afișează.
• traceResolution: Afișează pas cu pas cum găsește tsc fișierul din spatele fiecărui import; util la erori TS2307.