Utilisation de types provenant de bibliothèques tierces (`@types/...`)

Le défi : Typer le monde JavaScript extérieur

Votre application React ne vit probablement pas en vase clos. Vous utilisez sans doute de nombreuses bibliothèques JavaScript tierces pour diverses fonctionnalités : gestion d'état (Redux, Zustand), manipulation de données (Lodash), requêtes HTTP (Axios), routage (React Router), animation (Framer Motion), etc. La plupart de ces bibliothèques ont été écrites à l'origine en JavaScript pur, sans informations de type pour TypeScript.

Lorsque vous importez et utilisez une bibliothèque JavaScript standard dans votre code TypeScript, ce dernier n'a aucune information sur les fonctions disponibles, leurs paramètres, ou les types de données qu'elles retournent. Par défaut, TypeScript considérera souvent ces importations comme ayant le type `any`, ce qui désactive toute vérification de type et annule une grande partie des avantages de TypeScript pour ces interactions.

Pour résoudre ce problème et permettre une intégration sûre et typée avec l'écosystème JavaScript existant, la communauté TypeScript s'appuie sur un système de fichiers de déclaration de types (`.d.ts`).

DefinitelyTyped et le scope `@types`

La principale source de fichiers de déclaration de types pour les bibliothèques JavaScript populaires est le projet communautaire massif appelé DefinitelyTyped. Maintenu par des milliers de contributeurs, ce dépôt GitHub héberge les fichiers `.d.ts` pour des dizaines de milliers de paquets npm.

Ces fichiers de déclaration de types sont publiés sur npm sous le scope `@types`. Pour une bibliothèque nommée `ma-librairie`, ses types, s'ils existent sur DefinitelyTyped, seront généralement disponibles dans un paquet séparé nommé `@types/ma-librairie`.

Lorsque vous installez un paquet `@types`, le compilateur TypeScript (et votre éditeur de code) le détecte automatiquement et utilise les informations de type qu'il contient lorsque vous importez la bibliothèque JavaScript correspondante. Vous n'avez généralement rien d'autre à faire une fois le paquet `@types` installé.

Installation des paquets `@types`

Les paquets `@types` sont des dépendances de développement (devDependencies) car ils ne sont nécessaires que pendant la phase de développement et de compilation, pas à l'exécution.

Pour installer les types d'une bibliothèque, utilisez npm ou yarn :

# Exemple pour la bibliothèque lodash
npm install --save-dev @types/lodash

# Exemple pour une ancienne version de react-router-dom
# (Note: les versions récentes incluent leurs propres types)
# npm install --save-dev @types/react-router-dom 

# Exemple pour styled-components
npm install --save-dev @types/styled-components

Vous pouvez rechercher les types disponibles sur le site de DefinitelyTyped ou directement sur npm en cherchant `@types/nom-de-la-bibliotheque`.

Exemple d'utilisation

Supposons que vous utilisiez la bibliothèque `lodash` dans votre projet React TypeScript.

1. Installez la bibliothèque et ses types :

   npm install lodash
   npm install --save-dev @types/lodash

2. Utilisez la bibliothèque dans votre code. Grâce à `@types/lodash`, TypeScript connaît maintenant la signature des fonctions de lodash :

   import React from 'react';
   import _ from 'lodash'; // Importation standard
   
   function DataProcessor({ data }: { data: number[] }) {
     // TypeScript connaît la fonction 'debounce' de lodash
     // et peut vérifier les arguments et le type de retour.
     const debouncedHandler = _.debounce(() => {
       console.log('Handling debounced event');
     }, 300);
   
     // TypeScript connaît la fonction 'uniq' et son type.
     const uniqueData = _.uniq(data);
   
     // _.nonExistentFunction(data); // Erreur TypeScript: la fonction n'existe pas
     // _.uniq("abc"); // Erreur TypeScript: attend un tableau, pas une chaîne
   
     return (
       
   
         Unique items: {uniqueData.join(', ')}
         Trigger Debounce
       
     );
   }
   export default DataProcessor;

Sans `@types/lodash`, TypeScript aurait probablement considéré `_` comme étant de type `any`, et aucune des erreurs ou de l'autocomplétion n'aurait fonctionné.

Bibliothèques avec types intégrés

Il est important de noter qu'un nombre croissant de bibliothèques modernes, en particulier celles écrites directement en TypeScript, incluent leurs propres fichiers de déclaration de types directement dans leur paquet npm. Dans ce cas, vous n'avez pas besoin d'installer un paquet `@types` séparé.

Exemples courants incluant leurs propres types :

• `axios`
• `react-router-dom` (v6+)
• `redux`
• `zustand`
• `react-query` / `@tanstack/react-query`
• Et bien sûr, `react` et `react-dom` eux-mêmes.

Comment savoir si une bibliothèque inclut ses types ?

• Consultez sa documentation.
• Regardez son `package.json` : cherchez une clé `"types"` ou `"typings"` pointant vers un fichier `.d.ts`.
• Explorez son dossier dans `node_modules` : cherchez la présence de fichiers `.d.ts`.
• Si l'installation d'un paquet `@types` pour une bibliothèque donne une erreur ou un avertissement indiquant qu'il est obsolète ou inutile, c'est que les types sont probablement inclus.

Que faire si aucun type n'existe ?

Dans de rares cas, pour des bibliothèques moins populaires ou plus anciennes, il se peut qu'il n'y ait ni types intégrés ni paquet `@types` disponible sur DefinitelyTyped. Vous avez alors plusieurs options :

• Déclarer un module basique : Vous pouvez créer votre propre fichier `.d.ts` (ex: `src/types/ma-librairie.d.ts`) et y déclarer le module avec un type `any` pour au moins faire taire les erreurs d'import de TypeScript, tout en perdant la sécurité de type : `declare module 'ma-librairie';`
• Utiliser `any` : Importer la bibliothèque et l'utiliser avec des assertions de type `any` lorsque nécessaire (import * as maLib from 'ma-librairie'; (maLib as any).uneFonction();), mais c'est à éviter autant que possible.
• Contribuer à DefinitelyTyped : Si vous avez le temps et les compétences, vous pouvez écrire vous-même les déclarations de types pour la bibliothèque et les soumettre à DefinitelyTyped pour en faire bénéficier toute la communauté.

Conclusion : Intégrer l'écosystème JavaScript en toute sécurité

L'utilisation des fichiers de déclaration de types, principalement via les paquets `@types` de DefinitelyTyped ou directement intégrés dans les bibliothèques modernes, est essentielle pour travailler efficacement avec des dépendances externes dans un projet React TypeScript.

Cela permet de bénéficier de l'autocomplétion, de la vérification statique des types et d'une meilleure compréhension des API tierces, rendant l'intégration de ces bibliothèques plus sûre, plus rapide et moins sujette aux erreurs.