...
Eroare TypeScript · Mediu, biblioteci și module

error TS2669: Augmentations for the global scope can only be directly nested in external modules or ambient module declarations.

Pe scurt

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

Greșit
TypeScript
// global.d.ts
declare global {
  var versiuneApp: string;
}
Corect
TypeScript
// 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

Greșit
TypeScript
declare global {
  var apiUrl: string;
}
globalThis.apiUrl = '/api';
Corect
TypeScript
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

Greșit
TypeScript
declare global {
  interface Window { analytics: unknown }
}
Corect
TypeScript
export {};
declare global {
  interface Window { analytics: unknown }
}

Și la extinderea interfețelor globale fișierul trebuie să fie modul.

Repară tu

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.

Codul care dă eroarea
TypeScript
declare global {
  var versiuneApp: string;
}

globalThis.versiuneApp = '1.4.0';
console.log(`Versiune: ${globalThis.versiuneApp}`);
După reparație, programul afișează
Versiune: 1.4.0
Indiciu

Fișierul trebuie să devină modul, chiar dacă nu exportă nimic.

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ă cu export {};.
  • Verifică dacă fișierul e inclus în proiect (include din tsconfig.json), altfel declarațiile nu au efect.
  • Când ștergi ultimul import dintr-un fișier cu declare 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

← Toate erorile TypeScript

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Î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.