L’un des plus gros soucis, lorsqu’on code un projet avec TypeScript, concerne la gestion des librairies externes. Si votre projet a pour dépendance une librairie codée en JavaScript, TypeScript ne peut pas connaître tout seul le typage de cette librairie et de ce qu’elle expose… il est nécessaire de le lui indiquer !
La première question à se poser est relativement simple : est-ce que la librairie JavaScript qu’on utilise définit et expose ses types TypeScript ?
Vérifiez si des types TypeScript sont définis pour une librairie JavaScript donnée
Chaque dépendance que vous installez via npm possède sa propre page sur le site de cet outil. Cherchez, depuis la barre de recherche du site de npm, le nom de librairie que vous souhaitez utiliser, pour trouver sa page dédiée :
Une fois arrivé sur la page npm de la librairie, regardez l’en-tête des informations : à droite du nom de la librairie se trouve une icône bleue “TS” si des types TypeScript sont disponibles pour cette librairie :
Si à la place de ce symbole se trouve une icône blanche “DT”, cela signifie que les déclarations de types peuvent être installées via npm :
Enfin, s’il n’y a aucun symbole à côté du nom de la librairie… désolé pour vous, aucun type TypeScript n’est disponible, vous allez devoir les écrire vous-même.
Si vous avez bien suivi, nous avons donc trois cas possibles :
Soit la librairie propose déjà les types TypeScript.
Soit il faut les installer via npm.
Soit on doit les écrire nous-mêmes.
Voyons plus en détail ces différents scénarios !
Cas n° 1 : le développeur de la librairie a déjà écrit les types de sa librairie JavaScript
Ceci est le cas idéal. S’il n’est pas possible de migrer un projet JavaScript en TypeScript, quelle que soit la raison, il reste la solution de créer un fichier index.d.ts à la racine de ce projet.
Nous verrons un peu plus loin comment écrire ce type de fichier. Quoi qu’il en soit, lorsqu’un projet JavaScript possède ce type de fichier à sa racine, TypeScript est capable de le lire automatiquement, et donc de connaître les types manipulés par la librairie : si vous utilisez un projet dans ce cas, vous n’avez donc rien de plus à faire !
Cas n° 2 : les types de la librairie JavaScript sont disponibles dans une autre librairie
Le cas le plus fréquent : il n’y a pas de fichier .d.ts directement dans le projet de librairie JavaScript, mais il existe ailleurs.
Pour inclure ces définitions dans votre projet, il est nécessaire de les installer via npm : npm install @types/NOM_DE_LA_LIBRAIRIE .
Par exemple, si vous voulez utiliser les types de la librairie React, la commande à entrer est : npm install @types/react .
Une fois installées, TypeScript peut prendre en compte ces nouvelles définitions, sans que vous ayez rien de plus à faire de votre côté.
Cas n° 3 : les types de la librairie JavaScript ne sont disponibles nulle part
C’est le cas le plus rare, mais aussi le plus ennuyeux : il va vous demander de créer vous-même le fichier de déclaration de types !
Une pratique courante est de mettre ce genre de fichier dans un dossier /types . Si nous souhaitons créer le typage de la librairie to-no-case que nous avons vue tout à l’heure, nous créerons donc le fichier /types/to-no-case.d.ts . Dans ce fichier, nous devons définir le module correspondant à notre librairie. Et là, normalement je vous ai perdu, car on n’a jamais parlé de module durant ce cours.
Sans entrer dans les détails, dans un projet traditionnel les dépendances sont importées sous la forme de modules. Dans notre exemple, la librairie to-no-case s’utilise ainsi :
import toNoCase from 'to-no-case';
const str = toNoCase('my-string');Vous voyez le 'to-no-case' à droite du from ? C’est le nom du module.
C’est ce module que nous allons définir dans le fichier /types/to-no-case.d.ts .
Commençons donc par le déclarer, et ce via les mots-clés declare module :
declare module "to-no-case" {
// Déclaration des types ici
}Nous avons vu à l’usage ( import toNoCase from 'to-no-case'; ) que ce module exporte une fonction.
Nous allons donc décrire la signature de cette fonction. Rappelez-vous : la signature d’une fonction est sa combinaison “nom de la fonction + types des paramètres + type du retour”. Cela signifie que nous n’allons pas écrire le corps logique de la fonction (et heureusement, nous ne voulons pas réécrire la totalité des librairies que nous devons typer !).
Commençons donc par déclarer cette fameuse signature, sans prendre en compte les types pour le moment :
declare module "to-no-case" {
export default function toNoCase(): unknown;
}Il ne reste plus qu’à typer correctement cette signature. D’après la documentation de la librairie, la fonction s’attend à recevoir une string en paramètre, et retourne une string en réponse. Cela peut donc se traduire ainsi :
declare module "to-no-case" {
export default function toNoCase(param: string): string;
}Le typage de la librairie est désormais terminé, il faut maintenant dire à TypeScript de s’en servir !
La solution la plus simple est de juste importer le fichier que nous venons d’écrire depuis le fichier se servant de la librairie :
import './types/to-no-case.d.ts';
import toNoCase from 'to-no-case';
const str = toNoCase('my-string');En résumé
Il est possible d’utiliser des librairies écrites en JavaScript dans un projet TypeScript.
La déclaration des types se fait dans des fichiers de définition de types, avec l’extension .d.ts.
La plupart des librairies JavaScript connues ont déjà des types TypeScript définis.
Il s’agissait du dernier véritable chapitre du cours : vous avez donc terminé ce cours, félicitations ! Vous avez désormais les bases pour appréhender TypeScript sereinement. La prochaine étape est un quiz pour valider vos nouvelles connaissances.
Il vous reste cela dit encore beaucoup de choses à voir à propos de TypeScript. Dans le prochain et dernier chapitre, qui est optionnel, on verra les prochaines étapes pour vous permettre d’aller plus loin.
