Augmentations for global scope can only be directly nested

avatar

Borislav Hadzhiev

Last updated: Mar 1, 2022

banner

Photo from Unsplash

Augmentations for global scope can only be directly nested #

The error "Augmentations for the global scope can only be directly nested in external modules or ambient module declarations" occurs when we try to modify the global scope outside of an external module. To solve the error, add export {} to make the file an external module.

Here is an example of how the error occurs.

types.d.ts
// ⛔️ Error: Augmentations for the global // scope can only be directly nested in external // modules or ambient module declarations.ts(2669) declare global { interface Window { example: any; } }

I'm trying to modify the global scope (window) outside of an external module.

To solve the error, add an export {} line to make the file an external module.

types.d.ts
// ✅ Works now export {}; // 👈️ add this declare global { interface Window { example: any; } }

An external module is a file that contains an import or export statement.

If you use an import or export statement anywhere in the file, it becomes a module.

In the first code snippet, the types.d.ts file didn't contain an import or export statement, so the error was thrown.

The error message means that we can only augment the global scope in external modules or ambient module declarations.

The second part of the error message states "or ambient module declarations".

Here is an example of an ambient module.

uuid.ts
declare module 'uuid' { export function v4(): string; }

Ambient modules are meant to add typings for third-party modules, for which there is no @types/module-name package available and aren't written in TypeScript.

In other words, they are used to add TypeScript types for JavaScript code, so the package can be integrated in your TS codebase.

The uuid.ts ambient module above declares types for a module named uuid and states that the module contains a function named v4 that has a return type of string.

Even if the uuid package is written in JavaScript and does not have a @types/uuid package, I am now able to import the module and use the v4() function and have its return type be string.

index.ts
import * as uuid from 'uuid'; // 👇️ function v4(): string const result = uuid.v4();

This is the use case for ambient modules in TypeScript.

The error message "Augmentations for the global scope can only be directly nested in external modules or ambient module declarations" means that we can only change the global scope in:

  1. Files that contain an import or export statement (external modules).
  2. Ambient modules - modules that describe the shape of libraries not written in TypeScript.

Conclusion #

The error "Augmentations for the global scope can only be directly nested in external modules or ambient module declarations" occurs when we try to modify the global scope outside of an external module. To solve the error, add export {} to make the file an external module.

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.
book cover
You can use the search field on my Home Page to filter through all of my articles.