declare en TypeScript : pourquoi et comment l'utiliser

Pourquoi TypeScript a-t-il besoin du mot-clé declare ?

Imaginez que vous construisez une maison, mais que certaines pièces existent déjà — elles ont été construites par quelqu'un d'autre (par exemple, une bibliothèque JavaScript). Vous ne pouvez pas entrer et refaire les murs, mais vous devez connaître leur agencement pour bien placer les meubles. C'est exactement le rôle du mot-clé declare en TypeScript.

Si vous avez déjà travaillé avec des bibliothèques populaires (jQuery, Lodash, D3.js), vous avez sûrement rencontré des fichiers .d.ts — ce sont les "plans" créés avec declare. Dans cet article, nous allons voir ce qu'est declare, pourquoi il est utile et comment l'utiliser en pratique. Préparez-vous — il y aura beaucoup de code et peu de blabla.

Qu'est-ce que declare en TypeScript ?

declare est un mot-clé qui indique au compilateur TypeScript : "Hé, cette chose (variable, fonction, classe ou module) existe, mais elle est définie ailleurs. Fais-moi confiance et laisse-moi l'utiliser dans le code."

Il est important de comprendre : declare ne génère aucun code JavaScript. C'est une construction purement informative pour le compilateur. Si vous écrivez declare const x: number = 5, après compilation, x disparaîtra — il ne sera pas dans le fichier final.

Quand l'utiliser ?

\n
• Travailler avec des variables globales — par exemple, window, document ou des variables ajoutées via un CDN.
\n
• Typer des bibliothèques JavaScript — quand une bibliothèque est écrite en JS pur, mais que vous voulez l'utiliser avec TypeScript.
\n
• Créer des types pour des fichiers de configuration — modules CSS, images, fichiers JSON.
\n

Syntaxe de declare : exemples de base

1. Déclaration de variables

Supposons que vous ayez une variable globale VERSION, définie dans un fichier HTML via <script>. TypeScript n'en sait rien, vous écrivez donc :

declare const VERSION: string;\n\nconsole.log(VERSION); // OK, TypeScript sait que c'est une chaîne\n

Après compilation, declare const VERSION: string disparaît, mais console.log(VERSION) reste.

2. Déclaration de fonctions

Imaginez une fonction globale trackEvent provenant d'un outil d'analyse :

declare function trackEvent(eventName: string, properties?: Record<string, any>): void;\n\n// Utilisation\ntrackEvent("button_click", { buttonId: "submit" });\n

Le compilateur ne vérifie pas l'implémentation — il connaît simplement la signature.

3. Déclaration de classes

Une bibliothèque fournit une classe Moment dans l'espace de noms global :

declare class Moment {\n    constructor(date: string);\n    format(pattern: string): string;\n}\n\n// Utilisation\nconst now = new Moment("2024-01-01");\nconsole.log(now.format("YYYY-MM-DD"));\n

4. Déclaration de modules

C'est le scénario le plus courant. Par exemple, avec des modules CSS ou des fichiers JSON :

// styles.d.ts\ndeclare module "*.css" {\n    const styles: Record<string, string>;\n    export default styles;\n}\n\n// images.d.ts\ndeclare module "*.png" {\n    const src: string;\n    export default src;\n}\n

Vous pouvez maintenant importer des CSS et des images sans erreur TypeScript.

declare et les fichiers .d.ts

Les fichiers avec l'extension .d.ts (déclarations de types) sont le "territoire" du mot-clé declare. Ils contiennent uniquement des déclarations et ne sont pas compilés en JavaScript. Ils se trouvent généralement dans un dossier types/ ou sont fournis avec la bibliothèque (par exemple, @types/lodash).

Exemple : créer des types pour jQuery