From ae5ee746f290f6d7f7022a6b2b5277deff672f60 Mon Sep 17 00:00:00 2001 From: Ishant Mishra Date: Sat, 12 Jul 2025 14:13:35 +0545 Subject: [PATCH 1/2] docs: clarify export {} comment in global-modifying-module template Improvements: #3410 (Issue) --- .../templates/global-modifying-module.d.ts.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/packages/documentation/copy/en/declaration-files/templates/global-modifying-module.d.ts.md b/packages/documentation/copy/en/declaration-files/templates/global-modifying-module.d.ts.md index 7b2d004e3798..773134a8e168 100644 --- a/packages/documentation/copy/en/declaration-files/templates/global-modifying-module.d.ts.md +++ b/packages/documentation/copy/en/declaration-files/templates/global-modifying-module.d.ts.md @@ -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 {}; + ``` From 93a48e0f9f192f8e9abcfcb3e40c45aec73f91e3 Mon Sep 17 00:00:00 2001 From: Ishant Mishra Date: Sat, 12 Jul 2025 14:36:57 +0545 Subject: [PATCH 2/2] docs: add detailed explanation of declare global statement Feature: #3409 (Issue) --- .../copy/en/declaration-files/By Example.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/packages/documentation/copy/en/declaration-files/By Example.md b/packages/documentation/copy/en/declaration-files/By Example.md index 6717d697f834..d93031fccb65 100644 --- a/packages/documentation/copy/en/declaration-files/By Example.md +++ b/packages/documentation/copy/en/declaration-files/By Example.md @@ -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; + } +} +``` +