Accueil › TypeScript › Les fichiers .d.ts
Les fichiers .d.ts
Modules et déclarationsintermediaire
Un fichier .d.ts contient des types et rien d'autre : aucune
implémentation, aucun code produit. Il sert à décrire du JavaScript que
TypeScript ne peut pas analyser — une bibliothèque publiée en JS, une variable
injectée par l'empaqueteur, une globale posée par un script tiers.
// mesure.d.ts
export declare function moyenne(valeurs: number[]): number;
export interface Mesure { horodatage: number; valeur: number }
Ce qu'un .d.ts est
Une promesse. Le compilateur croit ce qu'il y lit, et ne le confronte jamais au JavaScript décrit.
// faux.d.ts — le code réel renvoie une chaîne
export declare function somme(a: number, b: number): number;
import { somme } from "./faux";
const t: number = somme(1, 2); // ✅ compile
t.toFixed(2); // 💥 à l'exécution : ce n'est pas un nombre
Aucune erreur de compilation. Un .d.ts faux est pire que l'absence de types :
il donne une confiance que rien ne justifie.
Ce qu'un .d.ts n'est pas
Ce n'est ni une validation, ni un contrôle à l'exécution, ni une garantie sur la version installée de la bibliothèque.
Script ou module
// globales.d.ts — aucun import, aucun export : VERSION_APPLI est global
declare const VERSION_APPLI: string;
Ajouter un seul export transforme le fichier en module, et la globale
disparaît. C'est la cause la plus fréquente des déclarations « qui ne sont plus
vues ».
Pour son propre code, on ne les écrit pas
{ "compilerOptions": { "declaration": true, "declarationMap": true } }
Le compilateur les dérive de la source : exacts par construction.
Les termes à connaître
- Fichier de déclaration
Un fichier
.d.tsqui ne contient que des déclarations de types, sans aucune implémentation. Il décrit la forme d'un code JavaScript existant.- `declare`
Le mot-clé qui annonce l'existence d'une chose sans la définir.
declare const VERSION: stringdit qu'une variable globale existe ; il ne la crée pas.- Déclaration ambiante
Une déclaration qui parle de quelque chose défini ailleurs — une globale du navigateur, une variable injectée par l'empaqueteur, un module sans types.
- Promesse non vérifiée
Ce qu'est un
.d.ts: le compilateur croit ce qu'il y lit, sans jamais le confronter au JavaScript décrit. Une déclaration fausse ne provoque aucune erreur à la compilation.- `declaration`
L'option de compilation qui fait générer par TypeScript les
.d.tsde votre propre code. Ils sont alors exacts par construction, puisque dérivés de la source.- Fichier de script contre fichier de module
Un
.d.tssans aucunimportniexportest un script : tout ce qu'il déclare est global. Ajouter un seulexportle transforme en module, et ses déclarations cessent d'être visibles partout.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.