pgr/docs/templates/009-WEB_VITE.md

Guide d'adaptation Vite

Rôle

Ce document accompagne le profil 550-VITE.md lorsqu'un projet sélectionne réellement Vite.

Il ne fournit volontairement pas de vite.config.ts copiable universel. Les corpus montrent une responsabilité réutilisable claire pour Vite, mais pas des valeurs universelles pour les chemins, ports, aliases, plugins ou hosts.

L'objectif est donc de normaliser ce qui doit être décidé et validé, sans figer arbitrairement la valeur de chaque décision.

Manifest

Le manifest réel du projet doit utiliser le package manager choisi par le projet et ajouter Vite comme outil de développement avec une version explicitement décidée.

Les scripts usuels, lorsqu'ils correspondent au workflow réel, sont conceptuellement :

{
    "scripts": {
        "dev": "vite",
        "build": "vite build",
        "preview": "vite preview"
    }
}

Ce fragment n'est pas un template complet de package.json et ne sélectionne aucun package manager.

dev et build sont naturels lorsqu'un frontend Vite existe. preview MAY être omis si aucun smoke/prévisualisation locale ne l'utilise.

Le type-check TypeScript reste une preuve séparée :

typecheck -> tsc --noEmit
build     -> vite build

Une CI peut exécuter successivement ces deux scripts sans imposer une syntaxe npm particulière.

Décider root

Si index.html et les sources se trouvent à la racine comprise par Vite, aucune valeur explicite n'est nécessaire uniquement pour respecter PGR.

Si le package contient une racine frontend dédiée, le projet doit configurer root vers cette racine. Le nom frontend/ observé dans Games est une convention locale utile mais pas une obligation générique.

Décider base

base doit suivre le mode réel de service/embarquement :

site servi à la racine       souvent /
site sous un sous-chemin     chemin public correspondant
host embarqué                valeur relative si réellement requise

PGR ne copie donc pas automatiquement base: "./" depuis Games dans tous les projets Vite.

Cache

Le cache Vite est reproductible et ne doit pas devenir un source versionné.

Ordre de préférence PGR :

1. placer cacheDir hors de l'arborescence source lorsqu'un emplacement de build externe existe déjà et reste simple à utiliser ;
2. sinon accepter un cache interne dédié et l'ignorer explicitement ;
3. ne jamais versionner le cache uniquement pour accélérer une machine locale.

L'effacement du cache doit rester sans conséquence fonctionnelle autre qu'un recalcul.

Output de production

build.outDir contient des artefacts générés.

Ordre de préférence PGR :

1. utiliser un répertoire de build externe au source tree si l'environnement du projet le permet proprement ;
2. sinon utiliser un répertoire interne dédié, tel que dist/, explicitement ignoré ;
3. ne versionner un output que si un autre contrat de distribution l'exige réellement et documente cet artefact comme livrable.

Si build.emptyOutDir est activé, outDir doit être dédié à Vite. Le build ne doit pas pouvoir vider un répertoire partagé avec du WASM, des artefacts Rust, Android ou d'autres owners.

Assets

Trois catégories doivent rester distinguées :

asset source importé/référencé      source versionné
asset source dans publicDir         source statique versionné
asset copié/transformé dans outDir  output généré

publicDir MAY rester au défaut Vite, être déplacé ou être désactivé avec false selon le besoin du projet.

Une copie réalisée par plugin n'autorise pas à supprimer la source de son owner ni à versionner la copie de build comme second source.

Dev server et exposition réseau

Pour un développement local simple, rester sur une écoute locale/loopback est préférable.

N'élargir server.host au LAN/toutes interfaces que lorsqu'un besoin réel l'impose, par exemple un test sur device ou un host externe. Dans ce cas, revoir aussi les contraintes de hosts autorisés, CORS, TLS, proxy et HMR selon l'intégration réelle.

PGR déconseille les raccourcis globaux :

server.allowedHosts = true
server.cors = true

Ils ne doivent pas devenir des valeurs de template universelles.

Ports déterministes

Un port fixe n'est pas une règle PGR universelle.

Si rien ne consomme une URL déterministe, laisser Vite gérer son port peut être suffisant.

Si un host ou un smoke attend un port connu, utiliser ensemble :

server.port       valeur locale choisie
server.strictPort true

Ainsi, un conflit de port échoue explicitement au lieu de déplacer silencieusement le dev server.

La même logique peut s'appliquer à preview.port + preview.strictPort lorsqu'un smoke de preview exige une URL stable.

Preview

vite preview sert à vérifier localement le build produit. Il ne constitue pas un serveur de production PGR.

Un smoke MAY lancer preview après un build lorsque cette observation apporte une preuve nécessaire. Le deployment/serving réel reste hors du présent owner.

Ce qui reste local

La configuration suivante n'est pas normalisée par ce guide sans preuve supplémentaire :

ports exacts
host exact
base exact
aliases
plugins
noms de chunks/assets
minification
sourcemaps
proxy
TLS
HMR / WebSocket
filesystem allowlists
intégration WASM
intégration Tauri

Games fournit des exemples utiles pour plusieurs de ces points, mais PGR ne transforme pas ces valeurs en défauts génériques.

Validation dans PGR et dans un projet destinataire

PGR ne livre pas encore de vite.config.ts exécutable générique dans cette tranche ; il n'installe donc pas Vite uniquement pour valider un fichier fictif.

Dans un projet réel qui adopte ce profil, la gate applicable doit sélectionner l'outil réel et peut comprendre :

typecheck séparé
build Vite de production
inspection du outDir attendu
preview/smoke seulement si nécessaire
validation du host séparée

Les commandes concrètes passent par le package manager sélectionné par le projet. Un exemple npm dans une documentation tierce ne devient pas une obligation PGR.