Rescrierea importurilor TypeScript nu rezolvă toate căile de rulare

Un program TypeScript care rulează direct din sursă și un pachet JavaScript construit din acea sursă au nevoie de căi de import compatibile. TypeScript 5.7 a rezolvat o nepotrivire precisă, rescriind extensiile relative TypeScript la generarea fișierelor. Aceasta poate simplifica lucrul atât cu sursa, cât și cu rezultatul compilării. Nu face însă ca orice cale înțeleasă de compilator să poată fi găsită și la rulare. O verificare de tipuri reușită rămâne o dovadă insuficientă că pachetul distribuit va porni.

Privind din noiembrie 2026, reperul istoric este anunțul versiunii finale Microsoft din 22 noiembrie 2024. Anunțul beta a apărut la 9 octombrie. Proiectarea era deci vizibilă înaintea săptămânii analizate; noiembrie marchează versiunea finală, nu prima discuție publică despre opțiune.

Rescrierea are o țintă deliberat restrânsă

Microsoft descria rewriteRelativeImportExtensions pentru căi relative care încep cu ./ sau ../ și se termină cu extensii TypeScript, excluzând fișierele de declarații. Opțiunea rescrie căile eligibile folosind extensia JavaScript corespunzătoare. O referință la ./helper.ts, de exemplu, poate deveni ./helper.js în fișierul JavaScript generat. Căile deja JavaScript și cele fără extensie rămân neschimbate.

Notele versiunii finale exclud explicit căile dependente de baseUrl sau paths și explică dificultățile importurilor calculate dinamic. Separă și rezolvarea prin câmpurile imports și exports ale pachetelor de această rescriere locală. Versiunea beta oferă contextul anterior al proiectării, fără să dovedească disponibilitatea separată în noiembrie a fiecărei funcționalități conexe din mediile de rulare.

Articolul privește limita căilor, separat de diagnosticele pentru condiții suspecte discutate la TypeScript 5.6. Un compilator poate respinge o expresie greșită și poate lăsa totuși aplicația cu un traseu de livrare pe care nimeni nu l-a verificat. Corectitudinea celor două limite cere dovezi diferite.

Un import din sursă face o promisiune unui anumit încărcător

Luați ca exemplu ipotetic o bibliotecă ai cărei dezvoltatori rulează direct fișierele TypeScript în timpul lucrului și distribuie JavaScript generat. Un fișier sursă care importă ./helper.ts are sens pentru instrumentul care execută sursa. Aplicația generată are nevoie de o cale spre un fișier generat. Rescrierea extensiei relative face legătura locală și clară dintre cele două structuri de fișiere.

Valoarea pentru afacere este reducerea neconcordanțelor dintre lucrul comod în dezvoltare și obiectul livrat. Limita rămâne locală: echipa trebuie să păstreze structura de ieșire așteptată și să distribuie fișierul referit. Rescrierea textului unui import nu poate salva un pachet care omite acel fișier din distribuție.

Consumatorul are și propriul mediu de rulare. Notele lansării discută instrumente și capacități experimentale Node așa cum erau în 2024. Existența lor atunci nu înseamnă că orice versiune Node instalată, mod de module sau browser putea executa orice sursă TypeScript. Consemnați mediul susținut efectiv, în loc să împrumutați o promisiune mai largă din instrumentele actuale.

Acesta este un exemplu de arhitectură, nu un pachet construit sau executat pentru articol. Scopul lui este să identifice cele două trasee pe care trebuie să le acopere verificarea unui proiect: executarea sursei și folosirea rezultatului generat.

Aliasurile au nevoie de un responsabil după compilare

Un alias poate face importurile mai ușor de citit într-un depozit mare. Dacă un compilator folosește aliasul pentru a găsi un fișier, aceasta este o dovadă despre compilare. Mediul de rulare trebuie în continuare să înțeleagă calea primită. Un import care începe cu un alias specific aplicației nu devine relativ doar fiindcă se referă, în cele din urmă, la un fișier apropiat.

Pentru un serviciu propus care folosește aliasuri, alegeți cine le rezolvă la livrare. Un bundler poate răspunde de transformare sau mediul de rulare poate folosi o asociere explicit susținută prin pachete. Alegerea potrivită depinde de modul de instalare a produsului. Greșeala este să lăsați responsabilitatea neatribuită fiindcă editorul ajunge corect la sursă.

Problema devine mai importantă între pachete. Configurația de dezvoltare poate depinde accidental de surse aflate în afara pachetului publicat. Aplicația locală funcționează deoarece întregul depozit este prezent. Consumatorul primește un obiect mai mic și descoperă relația lipsă. Limitele pachetelor trebuie examinate alături de scrierea importurilor.

Notele finale Microsoft discută exporturile condiționate ca posibilă abordare pentru structuri cu mai multe pachete. Este o decizie de configurare care cere atenție, nu o instrucțiune universală de a activa peste tot o condiție generică de dezvoltare. Păstrați explicite condițiile consumatorului și cele pentru lucrul cu sursa, astfel încât să nu selecteze accidental fișiere sursă indisponibile.

Căile calculate merită o verificare explicită

Un import dinamic a cărui cale este stabilită de logica programului nu poate fi tratat ca o simplă înlocuire statică a numelui. Anunțul final ilustrează limita cu o funcție care alege o cale. O migrare ar trebui să examineze aceste locuri, fără să presupună că opțiunea nouă rescrie orice șir care ar putea ajunge ulterior la import().

Pentru un încărcător de extensii propus, notați de unde vin numele extensiilor și cum corespund modulelor livrate. Preferați un set explicit de referințe permise când se potrivește produsului. Recomandarea privește o rezolvare ușor de întreținut; nu afirmă că rescrierea oferă singură o politică de securitate pentru nume de extensii neverificate.

Verificarea practică este folosirea rezultatului construit în mediul vizat, separat de facilitățile disponibile numai pentru sursă. Verificați un punct de intrare obișnuit și o cale relevantă încărcată dinamic. Sunt verificări propuse pentru proiect, nu experimente efectuate aici. Separați aceste eșecuri de erorile de tipuri, pentru ca limita nerezolvată să fie găsită repede.

O aplicație gestionată prin bundler poate să nu aibă nevoie de schimbare

Cel mai puternic contraargument este că sistemul existent de construire răspunde deja de rezolvare și produce corect fișierele pentru instalare. Activarea altei opțiuni poate adăuga complexitate fără să îmbunătățească produsul. Nu există obligația adoptării doar pentru că versiunea finală o include.

Folosiți opțiunea când importurile relative eligibile sunt obstacolul precis dintre executarea sursei și distribuția JavaScript. Păstrați sistemul de construire care rezolvă deja o problemă mai largă, dacă o nevoie măsurată de mentenanță nu justifică schimbarea. În dezvoltarea software la comandă, cereți o explicație scurtă despre cine rezolvă importurile la fiecare etapă și dovezi că rezultatul livrat rulează. Explicația valorează mai mult decât un fișier de configurare care doar arată coerent în editor.