144 lines
7.7 KiB
Markdown
144 lines
7.7 KiB
Markdown
<!-- file: docs/skeletons/003-WEB_FRONTEND.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# Skeleton — Web frontend
|
|
|
|
## Objectif
|
|
|
|
Cette specification décrit une specialization composable pour créer une baseline frontend Web contrôlée sans confondre langage, package ecosystem, build tool, styles et host.
|
|
|
|
Elle se compose avec [`001-PROJECT_GOVERNANCE_FOUNDATION.md`](001-PROJECT_GOVERNANCE_FOUNDATION.md), sélectionne les owners Web réellement applicables de la famille `500` et utilise les templates/guides `008`, `009` et `010` lorsqu'ils correspondent aux choix du projet.
|
|
|
|
Le contrat transversal des skeletons reste possédé par [`../rules/220-SKELETONS.md`](../rules/220-SKELETONS.md).
|
|
|
|
## Applicabilité
|
|
|
|
Appliquer cette specialization lorsqu'un projet ou sous-projet possède un frontend Web autonome ou embarqué dont la baseline frontend est contrôlée par le projet.
|
|
|
|
Elle peut servir de fondation frontend à un host plus spécifique, par exemple Tauri, sans rendre ce host applicable par elle-même.
|
|
|
|
Pour un projet existant, cette specification sert de référence de comparaison : l'adoption suit [`../rules/230-ADOPTION.md`](../rules/230-ADOPTION.md) et classe les choix existants `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` plutôt que de réécrire son layout.
|
|
|
|
Ne pas appliquer ce skeleton à un backend sans frontend, à une page statique qui n'a besoin d'aucune de ces responsabilités, ni uniquement parce que Vite/TypeScript sont recommandés ailleurs.
|
|
|
|
## Owners sélectionnables
|
|
|
|
La composition de référence d'un frontend moderne contrôlé est :
|
|
|
|
```text
|
|
GENERAL
|
|
+ 500 language / ecosystem family
|
|
+ 530 TypeScript
|
|
+ 540 JavaScript package ecosystem
|
|
+ 550 Vite
|
|
+ 560 CSS / Sass
|
|
```
|
|
|
|
La sélection reste factuelle :
|
|
|
|
- `530` est sélectionné lorsque TypeScript est utilisé ; TypeScript **SHOULD** être préféré pour une baseline durable lorsqu'il est compatible avec le besoin ;
|
|
- `540` est sélectionné lorsqu'un `package.json`, un package manager ou des dépendances JavaScript sont réellement utilisés ;
|
|
- `550` est sélectionné uniquement si Vite est choisi ; Vite **SHOULD** être préféré pour les frontends compatibles, sans être obligatoire ;
|
|
- `560` est sélectionné si le frontend possède une chaîne CSS/Sass ; CSS seul reste valide et Sass reste optionnel, bien que recommandé pour une chaîne non triviale ou un package exposant une API Sass utile.
|
|
|
|
Le skeleton ne transforme pas une recommandation `SHOULD` en `MUST`.
|
|
|
|
## Fondation et fichiers de départ
|
|
|
|
Lorsque TypeScript + package ecosystem sont sélectionnés, le projet MAY partir des templates :
|
|
|
|
```text
|
|
templates/web-typescript/package.json
|
|
templates/web-typescript/tsconfig.json
|
|
```
|
|
|
|
Le guide [`../templates/008-WEB_TYPESCRIPT_PACKAGE.md`](../templates/008-WEB_TYPESCRIPT_PACKAGE.md) possède leur adaptation.
|
|
|
|
PGR ne fournit pas de `vite.config.ts` universel. Si Vite est sélectionné, créer ou adapter la configuration réelle à partir des décisions décrites dans [`../templates/009-WEB_VITE.md`](../templates/009-WEB_VITE.md).
|
|
|
|
PGR ne fournit pas non plus de `main.scss` ou de thème universel. Si CSS/Sass est sélectionné, organiser les sources selon les besoins réels et suivre [`../templates/010-WEB_CSS_SASS.md`](../templates/010-WEB_CSS_SASS.md).
|
|
|
|
Le nom `frontend/` est une convention possible, pas un chemin imposé par ce skeleton.
|
|
|
|
## Décisions destinataire avant matérialisation
|
|
|
|
Résoudre explicitement au minimum :
|
|
|
|
1. la racine et le scope exacts du frontend ;
|
|
2. TypeScript ou JavaScript ; pour une nouvelle baseline durable, considérer explicitement la recommandation TypeScript sans transformer un choix JavaScript en obligation de justification ou en `OVERRIDE` ;
|
|
3. le package manager réel et la politique de lockfile adaptée au rôle du package ;
|
|
4. les versions réelles de TypeScript et des dépendances, ainsi que les déclarations `@types/*` réellement nécessaires ;
|
|
5. Vite ou un build tool alternatif, avec ses chemins `root`, cache, outputs, `base`, ports, plugins et assets lorsqu'ils s'appliquent ;
|
|
6. CSS seul ou Sass, puis l'implémentation Sass réelle si sélectionnée ;
|
|
7. le framework CSS éventuel : aucun, Bootstrap, Tailwind CSS ou autre ; ce choix reste local au projet ;
|
|
8. les entrypoints de styles publics des dépendances et les overrides réellement nécessaires ;
|
|
9. les scripts de package réellement utiles (`typecheck`, `dev`, `build`, `preview` ou équivalents) ;
|
|
10. la gate frontend indépendante du host et les éventuels smokes navigateur utiles ;
|
|
11. les prérequis produits par d'autres owners, s'il en existe, sans les faire absorber par le frontend.
|
|
|
|
Aucune décision ouverte ne doit être remplacée silencieusement par une valeur observée dans Games ou KSP.
|
|
|
|
## Dépendances et manifest
|
|
|
|
Le package réel **SHOULD** rester privé lorsqu'il représente une application non publiée, conformément à `540`.
|
|
|
|
Les dépendances de développement telles que TypeScript, Vite, Sass ou packages de déclarations sont ajoutées uniquement si les choix du projet les rendent nécessaires. Le skeleton MUST NOT préremplir `@types/node`, `@types/bootstrap`, `sass-embedded`, Vite ou Bootstrap sans besoin réel ni version décidée.
|
|
|
|
Lorsqu'une dépendance fournit déjà ses propres types, ne pas ajouter un package `@types/*` redondant.
|
|
|
|
## Styles
|
|
|
|
CSS source et Sass source sont des entrées versionnées. Les CSS compilées/minifiées, sourcemaps et copies dans l'output sont générées sauf contrat de distribution explicite.
|
|
|
|
Pour du nouveau Sass contrôlé, `@use` / `@forward` sont préférés lorsque les dépendances le permettent. Une compatibilité `@import` peut être conservée pour un package existant qui l'exige encore.
|
|
|
|
Le choix d'un framework CSS ne rend ni Bootstrap, ni Tailwind CSS, ni un thème spécifique normatif pour les autres projets.
|
|
|
|
## Build et outputs
|
|
|
|
Lorsque Vite est sélectionné, le cache et `build.outDir` restent générés et hors Git. Les chemins exacts restent locaux.
|
|
|
|
`build.emptyOutDir = true` n'est utilisé que sur un output dédié. `vite preview` reste un smoke/prévisualisation locale et ne devient pas un serveur de production.
|
|
|
|
Un autre build tool possède ses propres décisions project-specific tant qu'aucun owner PGR dédié n'existe.
|
|
|
|
## Validation initiale
|
|
|
|
La validation suit [`../validation/005-WEB_FRONTEND_VALIDATION.md`](../validation/005-WEB_FRONTEND_VALIDATION.md).
|
|
|
|
Selon les profils sélectionnés, elle doit pouvoir prouver indépendamment du host, autant que possible :
|
|
|
|
```text
|
|
restore reproductible
|
|
TypeScript typecheck
|
|
compilation/transformation des styles
|
|
build frontend de production
|
|
smoke navigateur seulement si nécessaire
|
|
```
|
|
|
|
La commande concrète appartient au package manager et aux outils réellement sélectionnés.
|
|
|
|
Le host reçoit ensuite sa propre gate d'intégration. Un PASS frontend ne constitue pas un PASS Tauri ou plateforme.
|
|
|
|
Une instanciation temporaire MAY être utilisée pour un dry-run de cette specialization. Elle doit employer les toolchains officielles réelles plutôt qu'un audit Python simulant TypeScript/Vite/Sass.
|
|
|
|
## Composition avec un host
|
|
|
|
Un host peut composer ce skeleton comme fondation frontend, puis ajouter son propre profil/skeleton.
|
|
|
|
Cette composition ne transfère jamais au host l'ownership de TypeScript, du package manager, de Vite ou de Sass/CSS.
|
|
|
|
Le skeleton Tauri reste `DEFER` pendant `0.1.1`. La présence du présent skeleton Web satisfait une pièce de préparation mais ne décide pas à elle seule la promotion du candidat Tauri.
|
|
|
|
## Hors scope
|
|
|
|
Cette specification ne possède pas :
|
|
|
|
- Tauri ou un autre host natif ;
|
|
- WASM ou ses bindings/générations ;
|
|
- backend/serveur Web ;
|
|
- deployment/operations ;
|
|
- choix de framework UI/CSS universel ;
|
|
- configuration de sécurité propre à un host ;
|
|
- service worker/PWA tant qu'un owner distinct n'est pas justifié.
|