error TS2669: Augmentations for the global scope can only be directly nested in external modules or ambient module declarations.
Ai scris declare global { ... } într-un fișier care nu e modul (nu are niciun import sau export). Adaugă export {}; în fișier ca să devină modul, sau, într-un script, scoate wrapper-ul și scrie direct declare var nume: Tip;.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
declare global { ... } adaugă declarații în domeniul global dintr-un modul. Un fișier e modul dacă are cel puțin un import sau export la nivel de top. Altfel e un script, iar în script tot ce declari la nivelul de sus e deja global, deci un bloc declare global nu are sens și TypeScript dă TS2669.
Eroarea apare des în fișiere de tipuri ca global.d.ts sau types.d.ts, copiate dintr-un exemplu care avea un import sus, sau după ce ai șters ultimul import dintr-un fișier. Codul care folosește variabila globală dă de obicei și TS7017, pentru că declarația a fost ignorată.
Reparația standard e un export {}; în fișier, care îl face modul fără să exporte nimic. Alternativ, dacă vrei să rămână script, declari direct: declare var versiuneApp: string;.
De ce apare: cauzele frecvente
1Fișier de tipuri fără import / export
// global.d.ts
declare global {
var versiuneApp: string;
}// global.d.ts
declare global {
var versiuneApp: string;
}
export {};export {} face fișierul modul, iar declare global devine o extindere validă a domeniului global.
2Script care poate declara direct
declare global {
var apiUrl: string;
}
globalThis.apiUrl = '/api';declare var apiUrl: string;
globalThis.apiUrl = '/api';Într-un script, declare var la nivelul de sus e deja global, fără wrapper.
3Extinderea interfeței Window
declare global {
interface Window { analytics: unknown }
}export {};
declare global {
interface Window { analytics: unknown }
}Și la extinderea interfețelor globale fișierul trebuie să fie modul.
Repară eroarea, direct în pagină
Codul de mai jos dă eroarea TS2669: Augmentations for the global scope can only be directly nested in external modules or ambient module declarations. Variabila globală versiuneApp trebuie declarată cu tipul ei. Repară fișierul, păstrând blocul declare global, ca programul să afișeze Versiune: 1.4.0.
declare global {
var versiuneApp: string;
}
globalThis.versiuneApp = '1.4.0';
console.log(`Versiune: ${globalThis.versiuneApp}`);Versiune: 1.4.0
Indiciu
Fișierul trebuie să devină modul, chiar dacă nu exportă nimic.
Reparația
declare global {
var versiuneApp: string;
}
globalThis.versiuneApp = '1.4.0';
console.log(`Versiune: ${globalThis.versiuneApp}`);
export {};De ce merge
declare global e permis doar într-un modul, iar fișierul nu avea niciun import sau export, deci era script. export {}; îl face modul fără să exporte nimic. Acum blocul adaugă versiuneApp în tipul obiectului global, atribuirea e verificată ca string, iar programul afișează Versiune: 1.4.0.
Cum o eviți pe viitor
- Ține extinderile globale într-un singur fișier (de exemplu
src/types/global.d.ts) care începe sau se termină cuexport {};. - Verifică dacă fișierul e inclus în proiect (
includedintsconfig.json), altfel declarațiile nu au efect. - Când ștergi ultimul
importdintr-un fișier cudeclare global, adaugăexport {}. - Preferă module și importuri în locul variabilelor globale, acolo unde se poate.
Întrebări frecvente
Ce face export {} dacă nu exportă nimic?
Marchează fișierul ca modul ES. Nu adaugă cod util la rulare, dar schimbă regulile de domeniu: declarațiile devin locale, iar declare global devine permis pentru ce vrei să fie global.
Am pus export {} și variabila tot nu e găsită. De ce?
Probabil fișierul nu e inclus în compilare. Verifică include / files din tsconfig.json și să nu fie exclus. Dacă e un .d.ts dintr-un folder separat, adaugă folderul în include sau în typeRoots.
Erori înrudite
error TS7017: Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature. Citești sau scrii o variabilă globală (globalThis.config, this.x la nivel de fișier) pe care TypeScript nu o cunoaște. Declar-o: declare var config: Config; într-un script sau în declare global { } într-un modul. error TS1183: An implementation cannot be declared in ambient contexts. Ai scris cod cu corp într-o declarație cu declare sau într-un fișier .d.ts. declare doar descrie ceva care există deja; nu poate conține implementare. Scoate declare dacă vrei să scrii funcția, sau scoate corpul dacă doar o descrii. error TS2584: Cannot find name 'document'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'. TypeScript nu are tipurile pentru browser (DOM), deci nu cunoaște document, window sau HTMLElement. Într-un proiect web adaugă "dom" la lib în tsconfig; dacă rulezi în Node sau într-o consolă (ca editorul nostru), nu există DOM și folosești console.log. Învață TypeScript de la zero, cu exerciții la fiecare lecție
Curs TypeScript: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.
