Conquérir `window` en TypeScript : comment ajouter sa propre propriété sans casser le code

Introduction : Pourquoi ajouter une propriété à window est un casse-tête pour chaque développeur TypeScript ?

Imaginez la situation : vous écrivez une application SPA moderne en TypeScript. Tout se passe bien, jusqu'à ce que vous ayez besoin de sauvegarder un état global ou une intégration avec un script externe (par exemple, analytics, cartes ou passerelle de paiement). Vous écrivez :

window.myAppConfig = { apiKey: '123' };

Et là, TypeScript vous affiche une erreur rouge : "Property 'myAppConfig' does not exist on type 'Window & typeof globalThis'". Cela vous dit quelque chose ? Cette question a recueilli des milliers de vues sur Stack Overflow, et aujourd'hui nous n'allons pas seulement donner une solution toute faite, mais aussi regarder sous le capot de TypeScript pour comprendre pourquoi cela se produit et comment y remédier de manière élégante et sécurisée.

Dans cet article, nous allons aborder plusieurs approches — des « béquilles » pour débutants aux motifs professionnels utilisés par les développeurs seniors. C'est parti !

Sous le capot : pourquoi TypeScript râle-t-il sur window.myProp ?

Pour comprendre le problème, il faut se rappeler que TypeScript est une surcouche de JavaScript qui ajoute un typage statique. L'objet window dans le navigateur est un objet global qui a un type prédéfini (Window). Ce type est décrit dans les bibliothèques standard de TypeScript (lib.dom.d.ts) et inclut toutes les propriétés standard : document, location, setTimeout et des centaines d'autres.

Lorsque vous essayez d'assigner window.myProp, TypeScript vérifie : « Est-ce que cette propriété existe dans l'interface Window ? ». Non — donc erreur. C'est une protection contre les fautes de frappe et la pollution accidentelle de la portée globale. Mais que faire si vous voulez intentionnellement étendre window ?

Méthode 1 : La plus simple, mais dangereuse — as any

La première option qui vient à l'esprit d'un débutant est simplement de « faire taire » TypeScript en utilisant un cast de type :

(window as any).myAppConfig = { apiKey: '123' };

Avantages : rapide, fonctionne, ne nécessite pas de définitions supplémentaires.

Inconvénients : vous perdez tous les avantages de TypeScript. Pas d'autocomplétion, pas de vérification de type. Si vous écrivez accidentellement myAppConfigg, il n'y aura pas d'erreur, mais l'application plantera à l'exécution. C'est comme désactiver les airbags dans une voiture — on peut rouler, mais c'est risqué.

Quand l'utiliser : uniquement pour un prototypage rapide ou si vous êtes sûr que la propriété sera utilisée une seule fois et supprimée.

Méthode 2 : Extension de l'interface globale (Interface Merging)

TypeScript prend en charge la fusion d'interfaces (declaration merging). C'est un mécanisme clé qui permet d'« ajouter » de nouvelles propriétés à un type existant Window. Pour cela, il faut déclarer une interface avec le même nom dans la portée globale.

Créez un fichier global.d.ts (ou ajoutez-le dans n'importe quel fichier .d.ts de votre projet) :

// global.d.tsinterface Window {    myAppConfig: {        apiKey: string;        debugMode?: boolean;    };    myAnalyticsFunction: (event: string, data: object) => void;}

Maintenant, vous pouvez écrire :

window.myAppConfig = { apiKey: '123' };window.myAnalyticsFunction('page_view', { page: '/home' });

// TypeScript suggérera que apiKey est une stringconsole.log(window.myAppConfig.apiKey); // ✅ Sans erreur

Comment cela fonctionne-t-il sous le capot ? TypeScript fusionne automatiquement toutes les déclarations d'interfaces portant le même nom. Si lib.dom.d.ts contient déjà interface Window { ... }, votre interface avec le même nom ajoutera simplement de nouvelles propriétés à celle-ci. C'est ce qu'on appelle glob