0.1.1-alpha.3
This commit is contained in:
118
docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md
vendored
Normal file
118
docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md
vendored
Normal file
@@ -0,0 +1,118 @@
|
||||
<!-- file: docs/templates/008-WEB_TYPESCRIPT_PACKAGE.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Templates de package Web TypeScript
|
||||
|
||||
## Rôle
|
||||
|
||||
Cette spécification accompagne les deux fichiers copiables :
|
||||
|
||||
- [`package.json`](../../templates/web-typescript/package.json) ;
|
||||
- [`tsconfig.json`](../../templates/web-typescript/tsconfig.json).
|
||||
|
||||
Ils constituent une baseline **minimale** pour une application frontend TypeScript privée. Ils ne constituent ni un projet complet, ni un skeleton Web, ni un choix de Vite, Sass, framework UI ou package manager.
|
||||
|
||||
Les owners normatifs restent [`530-TYPESCRIPT.md`](../rules/530-TYPESCRIPT.md) et [`540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](../rules/540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md).
|
||||
|
||||
## Pourquoi les templates restent minimaux
|
||||
|
||||
PGR ne possède pas encore, à ce niveau générique, les décisions suivantes :
|
||||
|
||||
```text
|
||||
package manager concret
|
||||
version du package manager
|
||||
version TypeScript
|
||||
target ECMAScript
|
||||
module / moduleResolution
|
||||
lib / types
|
||||
framework frontend
|
||||
Vite ou autre bundler
|
||||
Sass ou CSS direct
|
||||
layout source final
|
||||
aliases
|
||||
WASM
|
||||
host Tauri ou autre
|
||||
```
|
||||
|
||||
Les templates MUST donc rester parsables sans figer arbitrairement ces choix.
|
||||
|
||||
`package.json` et `tsconfig.json` n'acceptent pas un header commentaire PGR sans sortir de leur grammaire standard. Leur chemin et leur rôle sont donc possédés par le présent document plutôt que par des commentaires internes `file/version`.
|
||||
|
||||
## `package.json`
|
||||
|
||||
Le template représente un package privé et contient uniquement :
|
||||
|
||||
```text
|
||||
name valeur d'exemple à remplacer
|
||||
private true
|
||||
scripts typecheck
|
||||
```
|
||||
|
||||
Avant utilisation :
|
||||
|
||||
1. remplacer `project-web` par le nom réellement choisi ;
|
||||
2. sélectionner explicitement le package manager ;
|
||||
3. ajouter TypeScript comme dépendance de développement avec une version compatible réellement décidée par le projet ;
|
||||
4. laisser le package manager choisi produire son lockfile si la politique applicable le recommande ;
|
||||
5. ajouter les dépendances fonctionnelles seulement lorsqu'elles sont réellement nécessaires ;
|
||||
6. ajouter `dev`, `build`, `preview` ou autres scripts uniquement lorsque leurs owners existent.
|
||||
|
||||
Le template ne contient pas de champ `version` parce qu'une application privée n'a pas besoin d'inventer une version npm distincte. Un projet qui aligne volontairement ce manifest sur sa release globale peut l'ajouter selon sa gouvernance locale.
|
||||
|
||||
## `tsconfig.json`
|
||||
|
||||
Le template active uniquement les contrôles considérés génériques pour une baseline stricte :
|
||||
|
||||
```text
|
||||
strict
|
||||
noEmit
|
||||
noUnusedLocals
|
||||
noUnusedParameters
|
||||
noFallthroughCasesInSwitch
|
||||
```
|
||||
|
||||
Avant utilisation, le projet doit décider explicitement les options qui dépendent de sa target et de son host : `target`, `module`, `moduleResolution`, `lib`, `types`, `jsx`, `include`, `exclude`, aliases et éventuels chemins générés.
|
||||
|
||||
Le template ne copie donc pas les valeurs Games `ES2022`, `ESNext`, `bundler`, `vite/client`, `node` ou les aliases WASM. Ces valeurs restent des preuves de corpus et pourront être reprises seulement par l'owner qui les justifie.
|
||||
|
||||
## Type-check indépendant
|
||||
|
||||
Après installation locale de TypeScript, le script générique est :
|
||||
|
||||
```text
|
||||
typecheck -> tsc --noEmit
|
||||
```
|
||||
|
||||
Le type-check SHOULD pouvoir être exécuté indépendamment du bundler. Un futur script `build` MAY l'appeler avant le build de production, mais cela ne supprime pas sa responsabilité propre.
|
||||
|
||||
Exemples d'appel selon le package manager sélectionné :
|
||||
|
||||
```text
|
||||
npm run typecheck
|
||||
pnpm typecheck
|
||||
yarn typecheck
|
||||
```
|
||||
|
||||
Ces lignes sont des exemples, pas une sélection de package manager par PGR.
|
||||
|
||||
## Lockfile
|
||||
|
||||
Pour une application privée/deployable issue de ce template, le lockfile du package manager sélectionné SHOULD normalement être versionné.
|
||||
|
||||
Si le projet conserve volontairement une autre politique, l'écart doit être traité comme décision locale ou `OVERRIDE` lors d'une adoption PGR, avec justification proportionnée.
|
||||
|
||||
PGR MUST NOT conserver plusieurs lockfiles concurrents uniquement pour rendre le template compatible avec plusieurs package managers.
|
||||
|
||||
## Validation minimale du template dans PGR
|
||||
|
||||
Le dépôt PGR vérifie seulement que les deux fichiers sont du JSON parsable et qu'ils conservent les champs génériques attendus.
|
||||
|
||||
La validation réelle d'un projet destinataire sélectionne ensuite :
|
||||
|
||||
- le package manager choisi ;
|
||||
- la résolution/install de dépendances si nécessaire ;
|
||||
- le mode gelé/immutable lorsque le lockfile est versionné ;
|
||||
- le script `typecheck` ;
|
||||
- les validations Vite/CSS/Sass/host applicables dans leurs owners respectifs.
|
||||
|
||||
Le futur `alpha.5` de `0.1.1` réconciliera la validation frontend complète sans transformer cette paire de templates en skeleton prématuré.
|
||||
Reference in New Issue
Block a user