Formations — 1 037 leçons en français

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.ts qui 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: string dit 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.ts de 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.ts sans aucun import ni export est un script : tout ce qu'il déclare est global. Ajouter un seul export le transforme en module, et ses déclarations cessent d'être visibles partout.

Lire l'explication détaillée et faire le quiz →

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.