From 26b03a30fb8de256db0e3f1c57636f6751bbdeeb Mon Sep 17 00:00:00 2001
From: adriancuadrado <29214635+adriancuadrado@users.noreply.github.com>
Date: Mon, 19 Jan 2026 00:01:40 +0100
Subject: [PATCH 1/2] Explain declare global details

[The original PR](https://github.com/microsoft/TypeScript-Website/pull/3415) got closed because the author deleted his fork, but I wanted to save the work.
---
 .../templates/global-modifying-module.d.ts.md          | 10 +++++++++-
 1 file changed, 9 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..5cf4b3a4de3d 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,14 @@ 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 8d7204783649a4a31ad41e307b442ea670a0f638 Mon Sep 17 00:00:00 2001
From: adriancuadrado <29214635+adriancuadrado@users.noreply.github.com>
Date: Mon, 19 Jan 2026 00:09:40 +0100
Subject: [PATCH 2/2] Explain declare global details

[The original PR](https://github.com/microsoft/TypeScript-Website/pull/3415) got closed because the author deleted his fork, but I wanted to save the work.
---
 .../copy/en/declaration-files/By Example.md   | 38 +++++++++++++++++++
 1 file changed, 38 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..40190a6f96d5 100644
--- a/packages/documentation/copy/en/declaration-files/By Example.md	
+++ b/packages/documentation/copy/en/declaration-files/By Example.md	
@@ -249,3 +249,41 @@ 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;
+  }
+}
+```