Global Augmentation for Third-Party Libraries

The plain-language idea

The declaration-merging lesson showed the mechanism — two interface declarations with the same name combine — using Express's Request as the example. This lesson is about applying that same mechanism deliberately, and there are really two different things you might be augmenting, which use slightly different syntax:

1. The global scope — adding a property to window, globalThis, or a global ambient type that isn't tied to any specific import.
2. A specific module's own exported types — adding a property to a type a library exports and you import, without touching the library's source.

Mixing these up is the single most common mistake when writing your first augmentation .d.ts file.

Augmenting the global scope: a custom window property

// globals.d.ts
export {}; // makes this file a module, which scopes the `declare global` block correctly

declare global {
  interface Window {
    dataLayer: Record<string, unknown>[];
  }
}

// anywhere in the app
window.dataLayer.push({ event: "page_view" });

window.dataLayer is a real runtime object a lot of analytics scripts (Google Tag Manager, GA4) expect you to push events onto — but TypeScript's built-in Window interface has no idea it exists. declare global { interface Window { ... } } merges your addition into TypeScript's own global Window interface, so every file in the project sees dataLayer as a real, typed property, without you editing a library's source or casting to any every time you touch it.

Augmenting a specific module's exports

// styled-components.d.ts
import "styled-components";

declare module "styled-components" {
  export interface DefaultTheme {
    colors: {
      primary: string;
      background: string;
    };
  }
}

This is a different target: styled-components exports its own DefaultTheme interface, empty by default specifically so consumers can fill it in with their app's actual theme shape. declare module "styled-components" { ... } reopens that specific module's types — not the global scope — and merges your colors shape into it. Every styled-components API that uses DefaultTheme (the theme prop, useTheme(), the css helper) now knows your app's real theme shape, fully typed, with zero changes to the library itself.

What people usually miss

Watch out

• declare global and declare module "specific-package" are not interchangeable — one merges into the ambient global scope, the other reopens one specific module's exports. Reaching for the wrong one is why an augmentation compiles but the new property never actually shows up where you expect it.
• You can only add new members this way, never change an existing member's type. Trying to redeclare DefaultTheme.colors with an incompatible shape across two augmentation files is a real conflict, the same restriction the declaration-merging lesson already covered with Express's Request — this isn't a new rule, just the same one applied to a different target.
• Where the augmentation .d.ts file physically lives matters less than whether it's included by tsconfig.json. A correctly-written augmentation that isn't inside the project's configured include paths (or isn't referenced from a file that is) silently doesn't merge at all — no error, just types that behave as if the file doesn't exist.
• Popular libraries frequently ship an intentionally-empty interface specifically to invite this pattern — styled-components's DefaultTheme and a number of testing-library global matcher interfaces are designed to be empty until your app's own .d.ts file fills them in. That emptiness is a deliberate extension point, not an oversight.

Why this matters in interviews

"How would you add a typed dataLayer to window, or give styled-components your app's real theme type?" tests the same underlying mechanism as the Express Request question from the declaration-merging lesson, but forces you to correctly choose between declare global and declare module "package-name" — which is exactly where people who've memorized one example without understanding the mechanism get stuck.