"declaration"

Génère des fichiers .d.ts avec les types à côté du JavaScript compilé.

Sur cette page

Exemple

#
JSON
{
  "compilerOptions": {
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

Définition et utilisation

#

Avec declaration: true, le compilateur écrit un fichier .d.ts à côté de chaque fichier .js. Il ne contient que des types : signatures de fonctions, interfaces, types de classes et de constantes, sans aucune implémentation.

C’est indispensable pour publier une bibliothèque sur npm. L’utilisateur reçoit un JavaScript fonctionnel et les types grâce auxquels l’éditeur propose des suggestions et vérifie les appels. Le chemin vers les déclarations est indiqué dans package.json par le champ types ou par la condition types du champ exports.

Options voisines : declarationDir écrit les déclarations dans un dossier séparé, emitDeclarationOnly ne génère que les fichiers .d.ts (lorsque le JavaScript est construit par un autre outil), et declarationMap permet, dans l’éditeur, de passer d’un type directement au fichier source .ts.

Syntaxe

#
Syntaxe
"declaration": true

Plus d’exemples

#
La source et la déclaration générée
TypeScript
// src/progress.ts
export interface Progress {
  done: number
  total: number
}

export function percent(progress: Progress): number {
  return Math.round((progress.done / progress.total) * 100)
}

// dist/progress.d.ts (généré) :
// export interface Progress {
//     done: number;
//     total: number;
// }
// export declare function percent(progress: Progress): number;
Le package.json d’une bibliothèque
JSON
{
  "name": "@codeworlds/progress",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/progress.d.ts",
      "default": "./dist/progress.js"
    }
  }
}

Bonnes pratiques

#
  • Les applications, par exemple sur Next.js ou Vite, n’ont pas besoin de déclarations. Activez declaration dans les bibliothèques et les paquets partagés d’un monorepo.
  • Écrivez explicitement les types de retour des fonctions exportées. Les déclarations sont alors plus lisibles, et l’option isolatedDeclarations (TypeScript 5.5) l’exige même, afin que d’autres outils puissent générer des .d.ts sans vérification complète des types.

Entrées associées

#

Pratiquer dans les leçons

#

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.