How to extend the window object in TypeScript

TypeScript allows us to extend existing objects with custom properties. In the context of web development, a frequent need is to extend the window object. This guide will walk you through the process of extending the window object in TypeScript.

What's the window object?

The window object represents the browser's window in which the current webpage is displayed. It contains properties and methods that allow developers to interact with the browser and manipulate the DOM (Document Object Model).

Why extend the window object?

There are several reasons why developers might want to extend the window object:

• To attach global properties or methods available throughout the application.
• To add type definitions for libraries or frameworks that attach themselves to the window object.
• To work with custom properties or methods added by third-party scripts.

Extending window with TypeScript

To extend the window object in TypeScript, you'd typically use declaration merging. Here's how to do it:

Create a type declaration file

Start by creating a type declaration file. The conventional name is globals.d.ts, but you can choose any name, as long as it has the .d.ts extension.

// globals.d.ts
declare global {
  interface Window {
    customProperty: string;
  }
}

In this example, we're adding a customProperty of type string to the window object.

Use your extended window object

With the type declaration file in place, you can now use the customProperty without any TypeScript errors:

window.customProperty = "Hello, World!";
console.log(window.customProperty); // "Hello, World!"

Tips and precautions

• Avoid unnecessary extensions: While extending the window object can be useful, it's best to limit the number of custom properties added. This helps maintain readability and avoids potential naming conflicts with future browser additions or third-party scripts.

• Use namespacing: Instead of adding multiple properties directly to the window object, consider using a single namespace (an object) to group your custom properties.

  // globals.d.ts
  declare global {
    interface Window {
      myNamespace: {
        customProperty: string;
        anotherProperty: number;
      };
    }
  }

  Then, you can access properties like this:

  window.myNamespace.customProperty = "Test";

• Be mindful of runtime errors: TypeScript type definitions, including those for extending objects, don't have any impact at runtime. They exist purely for compile-time checks. Always ensure that the actual properties and methods you're referencing exist at runtime.

Integrate with third-party libraries

If you're using third-party libraries that attach properties or methods to the window object, you'll likely need to extend the window object's type definitions. If the library doesn't come with its TypeScript type declarations, or if those declarations are incomplete, you can supplement them using the technique described above.

For instance, if you integrate with a tool like Basedash which might add certain methods or properties to the window object for initialization or configuration, you'd use this approach to avoid type errors in your TypeScript code.

Remember to always check the documentation of third-party libraries for any existing TypeScript type definitions or recommended approaches for TypeScript integration.

Final words

Extending the window object in TypeScript is a straightforward process, thanks to declaration merging. With this guide, you should be able to add custom properties or methods to the window object and ensure type safety in your TypeScript projects.