Skip to content

Explain declare global details | Feature: #3409 #3415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: v2
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions packages/documentation/copy/en/declaration-files/By Example.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,3 +249,46 @@ Use `declare function` to declare functions.
declare function greet(greeting: string): void;
```

## The `declare global` Statement

_Documentation_

> When you write a TypeScript declaration file or module (a file containing `import` or `export`), all declarations inside it are **local to that module** by default. This means any interfaces, types, or variables you declare won't be visible outside that file unless explicitly exported or globally declared.
>
> The `declare global` statement allows you to **augment or add declarations directly to the global scope** from within a module. This is especially useful for:
> - Extending built-in global interfaces like `Window` or `Document`.
> - Adding new global variables or types your project relies on.
> - Modifying existing global libraries without modifying their source files.
>
> This differs from a simple top-level `declare` statement, which only creates globals if the file is treated as a global script (no `import` or `export` present). Once your file is a module, the top-level declarations are scoped locally, so `declare global` is required to reach into the global scope.

---

### How it works under the hood

1. **Marking the file as a module**
By including at least one `import` or `export` statement (like an empty `export {};`), you tell TypeScript this file is a module, not a global script.

2. **Module scope vs. global scope**
Inside modules, declarations (interfaces, types, variables) are **local to the module** and won't affect the global environment unless explicitly exported.

3. **Using `declare global` block**
Wrapping declarations inside `declare global { ... }` tells TypeScript to take those declarations and **merge them into the global scope**, as if they were declared in a global script.

4. **Result**
The global types/interfaces are augmented or extended project-wide and can be used anywhere without import, just like built-in global types.

---

### Example

```ts
export {}; // Mark this file as a module

declare global {
interface Window {
myCustomProperty: string;
}
}
```

Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,19 @@ export interface StringFormatOptions {
/*~ For example, declaring a method on the module (in addition to its global side effects) */
export function doSomething(): void;

/*~ If your module exports nothing, you'll need this line. Otherwise, delete it */
/*~
If your module does not export anything, include this line to explicitly mark the file as a module.

By default, TypeScript treats files without any import or export statements as scripts,
meaning their declarations are considered global. This can cause conflicts, such as
duplicate identifier errors, especially when you are augmenting or extending global types.

Adding `export {}` tells TypeScript that this file is a module. This scopes the declarations
to the module, preventing them from leaking into the global scope and avoiding naming conflicts.

For more information on how TypeScript distinguishes between scripts and modules, see:
https://www.typescriptlang.org/docs/handbook/modules.html#code-organization
*/
export {};

```