How to Add a Custom Property to window in TypeScript

By the end of this page, you will understand why TypeScript rejects unknown properties on window, how to extend the Window type correctly, and how to safely attach your own global objects while keeping type checking intact.

TypeScript does not allow you to access arbitrary properties on built-in objects unless those properties are part of the object's type.

In JavaScript, this is valid:

window.MyNamespace = window.MyNamespace || {};

JavaScript is dynamic, so you can attach new properties to objects at runtime.

TypeScript is static, so it checks whether MyNamespace is declared on the Window interface before allowing that code.

That means the problem is not whether JavaScript can do it. It can. The problem is whether TypeScript knows about it.

To make TypeScript happy, you usually augment the global Window interface so the compiler knows that window.MyNamespace is a valid property.

This matters in real projects because:

• it preserves type safety
• it avoids using any everywhere
• it documents global variables clearly
• it helps editors provide autocomplete and error checking

Instead of bypassing the compiler, the better solution is to teach the compiler about your global property.

Think of window as a predefined storage cabinet with a labeled inventory list.

• JavaScript lets you open the cabinet and throw in a new folder named MyNamespace
• TypeScript checks the inventory list first
• if MyNamespace is not on the list, TypeScript says: "I don't know that this folder belongs here"

So the fix is not to stop using the cabinet. The fix is to update the inventory list.

In TypeScript, updating that inventory list means extending the Window interface.

The standard solution is to declare the property on Window.

Basic syntax

declare global {
  interface Window {
    MyNamespace: Record<string, unknown>;
  }
}

Then you can use:

window.MyNamespace = window.MyNamespace || {};

Complete example

export {};

declare global {
  interface Window {
    MyNamespace: {
      version?: string;
    };
  }
}

window.MyNamespace = window.MyNamespace || {};
window.MyNamespace.version = "1.0.0";

console.log(..);

Consider this code:

interface Window {
  MyNamespace: { count?: number };
}

window.MyNamespace = window.MyNamespace || {};
window.MyNamespace.count = 1;

Here is what happens step by step:

1. TypeScript reads the Window interface extension.
2. It learns that window may contain a property named MyNamespace.
3. The assignment window.MyNamespace = window.MyNamespace || {} is now valid because MyNamespace is a known property.
4. If window.MyNamespace already exists, it is reused.
5. If it does not exist yet, {} is assigned.
6. The next line sets count to 1.

Runtime view

If window.MyNamespace starts as :

Custom properties on window are common when code needs a browser-wide shared value.

Common examples

• Third-party script integration

  • storing analytics objects
  • exposing SDKs loaded by script tags

• Application bootstrapping

  • attaching configuration loaded before the app starts
  • storing server-injected settings

• Legacy code migration

  • old JavaScript apps often use window.App, window.Utils, or window.Config
  • TypeScript can support this safely with interface augmentation

• Debugging hooks

  • exposing a development helper globally for testing in the browser console

Example: runtime config

interface Window {
  AppConfig: {
    apiBaseUrl: string;
  };
}

window.AppConfig = {
  apiBaseUrl: "https://api.example.com"
};

fetch();

In real projects, developers usually avoid creating many globals, but when they do need one, they type it explicitly.

Common patterns

1. Global declaration file

A common setup is a global.d.ts file:

interface Window {
  MyNamespace: {
    log: (message: string) => void;
  };
}

This keeps global type definitions separate from runtime logic.

2. Guarded initialization

window.MyNamespace = window.MyNamespace || {
  log(message: string) {
    console.log(message);
  }
};

This avoids overwriting an existing object.

3. Configuration container

interface Window {
  AppSettings: {
    environment:  | ;
  };
}

1. Using window without extending Window

Broken code:

window.MyNamespace = {};

Why it fails:

• TypeScript does not know that MyNamespace exists.

Fix:

interface Window {
  MyNamespace: {};
}

2. Using as any everywhere

Broken approach:

(window as any).MyNamespace = {};
(window as any).MyNamespace.value = 123;

Why it is a problem:

• you lose type checking
• typos will not be caught
• autocomplete becomes weaker

Better:

Add a custom property to window

In a declaration file

interface Window {
  MyNamespace: {
    version?: string;
  };
}

In code

window.MyNamespace = window.MyNamespace || {};
window.MyNamespace.version = "1.0.0";

Module-style global augmentation

export {};

declare global {
  interface Window {
    MyNamespace: Record<string, unknown>;
  }
}

Quick workaround

(window as any).MyNamespace = {};

Use only when necessary.

Why does TypeScript complain about window.MyNamespace?

Because MyNamespace is not part of the built-in Window interface, so TypeScript treats it as an unknown property.

How do I declare a custom property on window in TypeScript?

Extend the Window interface, usually in a .d.ts file:

interface Window {
  MyNamespace: {};
}

Can I use (window as any) instead?

Yes, but it disables type safety for that access. It is better to extend Window properly.

Does extending Window create the property at runtime?

No. It only informs the TypeScript compiler. You still need to assign the property in code.

Should I use declare var MyNamespace instead of window.MyNamespace?

Only if you want a direct global variable. If you specifically want a property on window, extend .

• Global scope — custom window properties are part of browser global state.
• TypeScript interfaces — extending Window relies on interface declarations.
• Declaration merging — TypeScript combines multiple interface declarations with the same name.
• Ambient declarations — useful for describing values that exist outside the current file.
• any vs unknown — relevant when choosing how loosely to type global properties.
• Type assertions — (window as any) is a type assertion-based workaround.
• Module vs script files — affects how declare global works.
• Browser globals — window, document, and similar objects are predefined browser APIs.