# 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`](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. 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. ## 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 : ```text 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 sauf incompatibilité documentée : ```text 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 : ```text typecheck ``` Lorsque le compilateur local est installé dans le package, le pattern recommandé est : ```text 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`](../../templates/web-typescript/tsconfig.json) active uniquement les options génériques ci-dessus. Le guide [`../templates/008-WEB_TYPESCRIPT_PACKAGE.md`](../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.