Développer : installer, tester, déployer
Installer
Prérequis : Node 22 ou plus (24 conseillé), pnpm 12.15 (packageManager du package.json racine). Pour reconstruire les données : Python 3 avec pandas, openpyxl, duckdb, numpy, pyproj, shapely. Pour Tauri : voir la page Mobile.
Bash
pnpm install lance lefthook install (script prepare) : les crochets git sont posés.
Lancer
Bash
| Adresse | Écran |
|---|---|
http:// | application publique (espace visiteur) |
http:// | application du gestionnaire |
http:// | projection mobile (grand écran) |
http:// | Storybook (pnpm storybook) |
Ports locaux de l'application et de Storybook
Comment lire
Une ligne par écran d'entrée, plus Storybook. Les deux applications tournent sur le même serveur de développement ; celle du gestionnaire a sa propre page (app/). Dans l'application publique, #/admin affiche la page d'erreur du visiteur.
Aperçu du build : pnpm -- (port 5175).
Tester et vérifier
| Tâche | Commande |
|---|---|
| Lint et format (Biome) puis typecheck de tous les paquets | pnpm check |
| Corriger le format | pnpm fix |
| Tests (Vitest, happy-dom) | pnpm test |
| Un fichier de test | pnpm exec vitest run packages/ |
| Typecheck d'un paquet | pnpm -- |
| Build de l'application | pnpm -- |
| Style séparé du React et design simplifié | node scripts/ (ou avec une liste de fichiers) ; lancé par pnpm check |
| Storybook en local, port 6006 | pnpm storybook |
Build de Storybook (dans storybook/, ignoré par git) | pnpm build- |
| Tout, avant de rendre la main | pnpm verify (check + test + build, Storybook compris, puis les budgets de poids) |
| Budget du script du widget (36 864 octets, soit 36 Ko) | node scripts/ (après le build ; lancé par pnpm verify) |
| Budget du premier chargement de l'application (600 Ko compressés) | node scripts/ (après le build ; lancé par pnpm verify) |
| Tests de bout en bout (Playwright, dans les vrais builds) | pnpm e2e (voir plus bas) |
| Reconstruire le jeu de données | PYTHON=/ (voir les données) |
| Tests Rust de Tauri | cd app/ |
Commandes à lancer depuis la racine du dépôt
Comment lire
Une ligne par tâche courante, avec la commande à lancer depuis la racine du dépôt.
État au 10 novembre 2026 : pnpm verify est vert, avec check-, 1 191 tests sur 1 191, et le build de l'application, du widget et de Storybook. @flux/core a ses scénarios sur le vrai jeu, @flux/ teste ses contrastes (83 couples) et ses jetons, @flux/ vérifie chaque dessin (un SVG, pas de texte ni de script, couleurs de la palette).
Les tests sont à côté du code (*.test.ts, *.test.tsx), lancés en une fois par vitest. à la racine. Les tests d'écrans montent les routes réelles avec un jeu, un stockage en mémoire et une horloge injectés (creerRoutesVisiteur, packages/). Un test de fumée tourne sur le vrai jeu embarqué.
Astuces :
@testing-n'est dépendance que delibrary/ react @flux/ui; les tests de l'application utilisentreact-etdom/ client act.- Sous happy-dom, un clic sur un lien
#/…change l'adresse sans déclencherpopstate: l'aidesuivre()le déclenche à la main. - Un test qui monte une
iframedoit poserwindow..happyDOM. settings. enableIframePageLoading = true - Un
Sitede test doit avoir unlieuId(lieuId: idpour un site seul). - Les scénarios sur le vrai jeu (
packages/) rejouent recherche, affluence, alternatives et chemin aveccore/ src/ scenarios. test. ts chargerJeu().@flux/corene dépend pas de@flux/data(c'est l'inverse) : le test importe le jeu par chemin relatif (../../data/). Aprèssrc/ index pnpm data, ils disent si les règles tiennent encore sur le nouveau jeu.
Tests de bout en bout
Depuis le 12 novembre 2026, 13 scénarios Playwright parcourent les vrais builds dans Chromium : l'application publique, l'application du gestionnaire, le site du widget et le portail. Playwright n'est pas une dépendance du dépôt : il est lancé par npx, à une version figée (1.64.1).
Bash
| Fichier | Ce qu'il vérifie |
|---|---|
e2e/ | accueil, recherche « pala », fiche de Paladru, résultat, alternatives, chemin ; #/admin de l'application publique mène à la page d'erreur ; l'application du gestionnaire : tableau de bord, signalement rapide, vu côté visiteur |
e2e/ | accueil du site du widget ; page d'exemple qui charge le script d'intégration |
e2e/ | accueil du portail en français, une page DataViz, la galerie des présentations et un deck, la recherche « Paladru » |
e2e/ | axe-core sans violation (règles A et AA) sur l'accueil et le résultat de l'application, l'accueil du widget et l'accueil du portail |
Source : e2e/LISEZMOI.md
Comment lire
Une ligne par fichier de test. Chaque build est servi par e2e/ sur un port libre, jamais le 3003 ; le réseau extérieur est coupé, et l'horloge est fixée au dimanche 15 août 2027 à 15 h (Paladru très fréquenté). En cas d'échec, les traces et captures vont dans e2e/..
Le portail doit être construit avant les scénarios portail (pnpm build dans docs/) : une seule personne lance cette commande à la fois.
Intégration continue
Chaque push et chaque demande de fusion sur main lancent le flux Vérifier de GitHub Actions (.github/), avec les mêmes outils qu'en local : Node 24, pnpm 12.15.0 exactement, lockfiles figés, aucune variable d'environnement ni aucun secret.
Source : .github/workflows/verifier.yml
Comment lire
De gauche à droite, dans l'ordre du flux ; la première étape qui échoue arrête le reste. Les scripts Python de données ne tournent pas : les données brutes du SSP Cloud ne sont pas dans le dépôt, et les fichiers qu'elles produisent sont versionnés.
Storybook
Storybook 10 montre chaque composant seul, dans tous ses états, à la taille d'un téléphone et à 1 280 px, toujours en clair. Paquet storybook/ (@flux/) ; configuration dans storybook/..
Bash
| Accueil | Un composant | Composants du portail |
|---|---|---|
![]() | ![]() | ![]() |
Captures du 12 novembre 2026, 1 440 × 900 px, Storybook construit
Comment lire
À gauche, l'accueil et l'image d'origine ; au milieu, une histoire de @flux/ui avec l'onglet « Accessibility » de l'addon a11y ; à droite, la rubrique qui montre les composants du portail sans les copier.
- Où sont les histoires : à côté des composants,
packages/, plus l'accueil*/ src/ **/ *. stories. tsx storybook/et la rubrique « Portail »src/ Introduction. mdx storybook/.src/ portail/ - Rubriques : Design system (palette, typographie, ombres et rayons, états d'affluence, composants Mantine thémés), Illustrations (plaquettes, galerie, illustration), UI (structure, affluence, actions, questions en images, sites, formulaires, avis, états, chemin, expériences, accessibilité), Portail (DataViz, lecture).
- Barre d'outils : fonds (blanc et gris d'information pour l'interface, crème et sable pour les dessins) et tailles d'écran (390 × 844, 360 × 780, tablette 820 × 1 180, ordinateur 1 280 × 800).
- Accessibilité : l'addon a11y tourne sur chaque histoire en mode
test:: une règle violée fait échouer l'histoire."error" - Portail : les composants de
docs/sont importés en lecture seule par des alias (src/ components @portail/,dataviz @portail/) ; le thème du portail est cantonné à ces histoires.lecture - Adresse publiée : à venir. En attendant,
pnpm storybooken local.
Écrire une histoire : un fichier Nom. à côté du composant, au format CSF, avec un état par histoire (vide, rempli, erreur, mobile, desktop s'il change). Le décorateur global enveloppe déjà chaque histoire dans <ThemeEclaireurs>.
Le style séparé du React
Tout le style vit dans des fichiers CSS (*.module.css à côté de chaque composant ou écran, ou les .css globaux du design system). Le script scripts/ le garde :
Bash
| Règle | Exemple refusé | À la place |
|---|---|---|
Pas de style={…} sauf des variables CSS | style= | une classe du module ; style= est permis |
| Pas de styles Mantine en objet ni de « style props » | sx=, styles={{…}}, mt="md", c="red" | une classe du module, ou le fichier du composant Mantine dans packages/ |
| Pas de CSS-in-JS | emotion, styled-components, balise <style> | un .module.css |
| Pas de couleur en dur hors du design system | #FFC941, rgb(…), red | var(--, var(-- |
| Pas de classe écrite en chaîne | className= | className= |
Source : scripts/check-styles.mjs
Comment lire
Une ligne par règle du script, avec ce qu'il refuse et ce qu'il faut écrire. Les exceptions justifiées (palette du design system, dessins SVG, repères des tests d'écrans) sont listées et commentées dans LISTE_, en tête du script.
Le script n'utilise que typescript (déjà installé) pour lire les .tsx en arbre syntaxique. Il est lancé par pnpm check avec --strict : une ombre hors élément flottant ou une règle de mode sombre bloque le push.
Règles par sujet
Les règles du dépôt sont dans AGENTS.md, à la racine : dossiers, fichiers partagés, style. Elles renvoient à une fiche de règles par sujet, nommée dans le tableau.
| Fichier de règles | Quand le lire | Contenu |
|---|---|---|
design- | avant de choisir une couleur, une ombre, un rayon, une taille de cible ou de texte | thème, palette, jetons --ecl-*, règle « interactif ou information », hiérarchie des boutons, contrastes |
css-separe | avant d'écrire du TSX ou du CSS, et quand check-styles échoue | la règle du style séparé et son gardien |
ajouter- | pour créer un composant ou en migrer un vers Mantine | le dossier du composant : .tsx, .module.css, histoires, test, export |
storybook | pour ajouter ou corriger une histoire, vérifier un composant à 390 et 1 280 px | lancer, écrire, capturer et construire Storybook |
illustrer- | pour toute nouvelle image ou question posée en images | dessiner, brancher au catalogue des plaquettes, rendre en PNG |
questions- | pour modifier ou ajouter une question visiteur | état dans l'adresse, DemandeVisite, BesoinAcces |
jeu- | avant de toucher packages/, ou quand une donnée semble fausse | reconstruire et contrôler le jeu embarqué |
Source : règles du dépôt (AGENTS.md, à la racine)
Comment lire
Une ligne par fichier de règles, avec sa description raccourcie.
Déployer sur Vercel
L'application se déploie sur Vercel comme un projet à part, distinct de celui du portail, mais branché sur le même dépôt.
Source : app/vercel.json, packages/gestionnaire/src/logique/sites.ts
Comment lire
De gauche à droite. Les flèches pleines suivent le build de l'application ; la flèche pointillée dit que l'adresse du portail est une constante du code (packages/), pas une variable à régler.
Régler le projet
| Réglage Vercel | Valeur | Pourquoi |
|---|---|---|
| Root Directory | app | le projet ne construit que l'application |
| Include source files outside of the Root Directory | activé (par défaut) | l'application n'est qu'une coquille : tout son code est dans packages/ (@flux/, @flux/, @flux/core…) |
| Framework Preset | Vite (repris de app/) | |
| Node.js Version | 22 ou plus (24 conseillé) | comme en local |
| Variables d'environnement | aucune | l'adresse du portail est écrite dans le code (décision de l'équipe projet du 9 novembre 2026) |
Écran « Settings » du projet Vercel de l'application
Comment lire
Une ligne par réglage de l'écran « Settings » du projet Vercel. Les commandes d'installation et de build ne se règlent pas à la main : elles viennent de app/.
Ce que fait app/ vercel. json
- Installation :
npx --. pnpm 12 n'est pas toujours celui de Vercel :yes pnpm@ 12. 15. 0 install -- frozen- lockfile npxprend la version exacte du dépôt, et--frozen-refuse unlockfile pnpm-qui ne correspond plus auxlock. yaml package.json. - Build :
npx --(vérification TypeScript, puisyes pnpm@ 12. 15. 0 run build vite buildpour l'application publique etvite build --pour celle du gestionnaire).mode gestion - Sortie :
dist(doncapp/dist), avec l'application du gestionnaire dans son sous-dossier ; une redirection et une réécriture la servent avec ou sans barre finale, sans indexation par les moteurs de recherche. - En-têtes de cache :
no-cachepoursw.js(avecService-),Worker- Allowed: / manifest.,webmanifest /etindex.html, pour qu'une nouvelle version arrive tout de suite ; un an,immutable, pourassets/(noms avec empreinte). - En-têtes de sécurité sur tout le site :
X-,Content- Type- Options: nosniff Referrer-,Policy: strict- origin- when- cross- origin Permissions-qui n'autorise que la géolocalisation (caméra et micro refusés).Policy
Le routage par fragment (#/…) n'a besoin d'aucune autre règle : le serveur ne voit que la page de chaque application.
Le jeu de données est versionné
Vercel n'a ni Python ni le dossier data/ du SSP CloudDonnées et outils : Plateforme de travail de l'Insee pour la statistique publique (logiciel Onyxia) : RStudio, Jupyter ou VS Code dans le navigateur, et un stockage S3 où sont déposées les données du hackathon. (environ 6,8 Go, non versionné). Le build de Vercel utilise donc packages/ tel qu'il est dans le dépôt, avec son cache generated/. Pour publier de nouvelles données :
- reconstruire en local :
PYTHON=/;chemin/ vers/ venv/ bin/ python pnpm data - vérifier :
pnpm test(taille sous 2 Mo, règles de lieux, absence d'adresses et de téléphones) ; - commiter
jeu.json, les autres fichiers degenerated/etgenerated/.cache/
L'adresse du portail
Décision de l'équipe projet (9 novembre 2026) : aucune variable d'environnement à configurer sur Vercel. L'adresse du portail publié est la constante PORTAIL_ (https://, dans packages/).
| Situation | Liens vers le portail |
|---|---|
| Build de production | vers PORTAIL_ : pages DataViz, Sites, Données SSP Cloud et cet onglet |
VITE_ définie au build (facultatif) | vers l'adresse donnée, prioritaire |
| Développement | vers le portail local http://, s'il tourne |
Source : PORTAIL_PUBLIC (packages/gestionnaire/src/logique/sites.ts)
Comment lire
Une ligne par cas. Un build de production sans variable connaît l'adresse publique du portail.
Vérifier un déploiement
/#/affiche « Vous voulez visiter quel site ? » et/#/adminla page d'erreur du visiteur ; l'application du gestionnaire ouvre le tableau de bord, et sa projection les deux téléphones ;- les en-têtes de
/sw.jsdisentCache-;Control: no- cache - après une première visite, l'application s'ouvre sans réseau ;
- l'écran « Données ouvertes » du gestionnaire mène au portail publié.
Licence
Le code du dépôt est sous licence MIT (fichier LICENSE à la racine, champ license de chaque package.json) : on peut le reprendre, le modifier et le redistribuer, en gardant la mention de licence. Les données, photos, polices et pages d'exemple des partenaires gardent la licence de leurs auteurs : voir la page Licences.
Conventions
- TypeScript strict (
tsconfig.:base. json strict,noUncheckedIndexedAccess,noUnusedLocals…). - Biome (
biome.json) : format (2 espaces, 120 colonnes, guillemets doubles, points-virgules), lint recommandé avec le domaine React,noConsoleen avertissement. Les fichiers.mdetpackages/ne sont pas formatés.data/ generated - Lefthook (
lefthook.yml) : au commit, Biome sur les fichiers indexés (corrigés et réindexés) ; au push,pnpm checkpuispnpm test. Les passer :LEFTHOOK=ou0 git commit … git push --.no- verify - Français partout : code métier (
estimerAffluence,proposerAlternatives), commentaires, interface. Phrases courtes, « (estimé) » quand c'est une estimation. L'application publique a une version anglaise sous/en/: chaque texte passe partr("Texte français")(@flux/), sa traduction est danscore/ i18n packages/, et<paquet>/ src/ traductions/ en/ scripts/vérifie qu'il ne manque rien.check- traductions. mjs - Mouvement : un seul moment vivant par écran, avec les composants
Apparition,CocheDessineeetTamponde@flux/ui, jamais d'animation écrite à la main ; voir Mouvement et moments vivants. - Mobile d'abord : 360 à 430 px, cibles de 44 px (48 px par défaut), un seul bouton plein par écran (l'action principale), contraste AA, clavier et lecteur d'écran, toujours en clair.
- Design minimaliste « Les Éclaireurs » (fond blanc, encre, une seule couleur d'action, quatre couleurs d'affluence) : composants Mantine 9 thémés par
@flux/, un dossier par composant, style dans desdesign- system .module.css, jetons--ecl-*, jamais de couleur en dur, une seule ombre (--ecl-), aucun mode sombre (ombre- flottant node scripts/) ; chaque composant a ses histoires Storybook. Voir le design system.check- styles. mjs -- strict - Une seule pile : pas de nouvelle dépendance si une existante suffit ; les versions sont dans le catalogue de
pnpm-.workspace. yaml - Données : agrégats et données ouvertes seulement ; aucune adresse électronique, aucun téléphone, aucune clé ; citer la source de chaque chiffre.
- Git : un push sur
maindéclenche les déploiements Vercel : contrôles au vert avant de pousser.
Travailler à plusieurs
- Chaque paquet a un responsable ; ce qui n'est à personne est un fichier partagé (
package.jsonracine,pnpm-,workspace. yaml pnpm-,lock. yaml biome.json,lefthook.yml,tsconfig.,base. json vitest.,config. ts packages/,core/ src/ types. ts packages/,stockage/ src/ cles. ts app/,src/ App. tsx app/,src/ routes. tsx widget/) : on le change sur décision. Le détail est danssrc/ App. tsx AGENTS.md. - Relire un fichier juste avant de l'écrire, et ne jamais défaire un changement qu'on n'a pas fait.
pnpm checkpeut échouer à cause du travail en cours de quelqu'un d'autre : vérifier son propre dossier avecpnpm exec biome check <dossier>et le typecheck de son paquet.- Une seule personne lance les commandes qui réécrivent beaucoup de fichiers (
pnpm data,pnpm fixsur tout le dépôt, et côté portailnode scripts/etgenerate. mjs pnpm build).
Limites
À garder en tête
- La couverture de tests n'est pas mesurée (
@vitest/absent).coverage- v8 - Les tests de bout en bout ne parcourent que 13 scénarios, dans Chromium seulement : ni Safari, ni Firefox, ni un vrai téléphone.
- Le déploiement Vercel de l'application est décrit d'après
app/; l'adresse publiée du Storybook n'est pas encore fixée.vercel. json


