7.1 KiB
Profil TypeScript
Rôle et applicabilité
Ce profil possède les règles réutilisables propres à TypeScript lorsqu'un projet sélectionne TypeScript pour du code frontend ou un autre package JavaScript typé.
Il complète 500-LANGUAGES.md. Il ne possède ni le package manager, ni package.json, ni le bundler/dev server, ni la chaîne CSS/Sass, ni le host natif ou navigateur.
Le profil s'applique lorsqu'une partie du source contrôlé est écrite en TypeScript ou lorsque la validation du projet inclut explicitement la toolchain TypeScript.
Recommandation pour les projets contrôlés
Pour un frontend que l'organisation contrôle, TypeScript SHOULD être préféré à du JavaScript non typé dès que le frontend porte une logique durable non triviale.
Cette préférence n'est pas une obligation universelle. Du JavaScript direct MAY rester approprié pour un artefact très petit, un script isolé, une contrainte externe ou un environnement où l'introduction de TypeScript n'apporte pas une valeur proportionnée. Choisir JavaScript ne constitue donc pas à lui seul une non-conformité, n'exige pas automatiquement un OVERRIDE et ne crée pas une obligation de justification ; la décision MAY être documentée lorsqu'elle apporte une valeur durable.
La justification de la recommandation est fonctionnelle : TypeScript ajoute une vérification statique avant exécution et permet de détecter une partie des incohérences de types pendant la validation plutôt qu'au runtime.
Frontières typées avec d'autres écosystèmes
TypeScript facilite également les frontières où des types doivent être partagés avec un autre langage ou runtime.
Lorsqu'un projet Rust expose des DTO, structures ou énumérations destinés au frontend et qu'un générateur de bindings tel que TS-RS est applicable, la génération de déclarations TypeScript depuis la source de vérité Rust SHOULD être préférée à la duplication manuelle des mêmes contrats.
Cette recommandation ne transforme pas TS-RS en dépendance générale de TypeScript. L'owner Rust, le framework ou le sous-système qui possède la frontière décide si cette génération est requise. Le profil Tauri peut notamment renforcer ce contrat dans son propre scope.
Déclarations de types externes et intégration IDE
Les dépendances TypeScript ne nécessitent pas toutes un package @types/* séparé. Avant d'ajouter une déclaration externe, le projet MUST déterminer si le package consommé fournit déjà ses propres fichiers de déclaration TypeScript. Une déclaration déjà fournie par le package ne doit pas être doublée arbitrairement par un package @types/*.
Lorsqu'une dépendance utilisée par du code TypeScript ne fournit pas de déclarations suffisantes, le projet SHOULD rechercher une source de types maintenue et compatible, typiquement le package @types/<nom> publié depuis DefinitelyTyped lorsqu'il existe. Cette dépendance améliore le contrôle statique, la compréhension des API par le language service TypeScript et, par conséquent, les diagnostics, la navigation et la complétion dans les IDE compatibles.
Pour une application privée ou de l'outillage local, les packages de déclarations qui ne sont nécessaires qu'au développement SHOULD normalement être placés dans devDependencies. Exemples d'applicabilité :
@types/node code, configuration ou outillage TypeScript utilisant réellement des API/globales Node
@types/bootstrap code TypeScript utilisant les API JavaScript Bootstrap lorsque Bootstrap ne fournit pas lui-même les déclarations requises
Ces exemples ne sont pas des dépendances PGR universelles. Un frontend navigateur qui n'analyse aucun code Node MUST NOT ajouter @types/node uniquement par habitude. Un projet qui ne consomme que le CSS/Sass de Bootstrap n'a pas besoin de @types/bootstrap pour cette seule raison.
Lorsqu'un tsconfig.json utilise explicitement compilerOptions.types, les packages de déclarations globales nécessaires au contexte analysé doivent être sélectionnés de manière cohérente avec cette liste. Les types importés depuis un module restent gouvernés par la résolution de modules applicable.
Pour une bibliothèque publiée, la classification diffère : si les déclarations publiques produites par la bibliothèque référencent un package de types externe requis par les consommateurs, ce package MUST rester disponible à ces consommateurs. Il ne doit donc pas être caché en devDependencies par simple convention d'application ; sa classification dans dependencies, peerDependencies ou une autre relation appropriée doit suivre le contrat de publication réel.
Les versions des déclarations externes SHOULD rester compatibles avec le package runtime concerné et avec la version TypeScript sélectionnée. PGR MUST NOT inventer une version @types/* dans un template générique sans dépendance réelle à typer.
Configuration et validation
tsconfig.json, les options de compilation/type-check, les fichiers inclus/exclus et la commande TypeScript canonique appartiennent à ce profil.
Pour un nouveau package TypeScript contrôlé, la baseline PGR SHOULD activer au minimum :
strict = true
noEmit = true
strict exprime la volonté d'utiliser le contrôle de types renforcé de TypeScript. noEmit sépare le type-check de la production des artefacts JavaScript lorsque cette production appartient à un bundler ou à un autre outil.
Pour une baseline stricte, PGR SHOULD également activer les contrôles simples suivants lorsqu'ils sont pertinents pour le package :
noUnusedLocals = true
noUnusedParameters = true
noFallthroughCasesInSwitch = true
Les choix target, module, moduleResolution, lib, types, jsx, chemins/aliases, include et exclude dépendent du runtime, du bundler, du framework et du layout réel. PGR MUST NOT les figer dans le profil TypeScript générique uniquement parce qu'ils apparaissent dans Games.
Le package SHOULD exposer une validation TypeScript indépendante sous un script canonique :
typecheck
Lorsque le compilateur local est installé dans le package, le pattern recommandé est :
tsc --noEmit
Un build Vite, Tauri ou autre ne remplace pas automatiquement cette preuve ciblée lorsqu'une propriété de typage doit être validée indépendamment.
Le modèle minimal ../../templates/web-typescript/tsconfig.json active uniquement les options génériques ci-dessus. Le guide ../templates/008-WEB_TYPESCRIPT_PACKAGE.md liste les décisions à compléter avant adoption réelle.
Ce que le profil n'impose pas
Ce profil ne rend obligatoire :
- ni Vite ;
- ni npm ou un autre package manager particulier ;
- ni Sass ou un framework CSS ;
- ni TS-RS pour un projet qui ne partage aucun contrat avec Rust ;
- ni un framework frontend particulier ;
- ni WASM ;
- ni Tauri.
Les choix correspondants restent possédés par leurs owners applicables.