Aller au contenu
Plutôt là

Développer : installer, tester, déployer

En bref
Pour qui
Développeurs qui reprennent le code.
Lecture
12 min
Mise à jour
12 novembre 2026

Installer, lancer, tester, l'intégration continue, Storybook, le style séparé, déployer sur Vercel, la licence et les conventions.

Données utilisées

Aucune.

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.

TerminalBash
pnpm install # à la racine : app/ et packages/ (docs/ a son propre espace)

pnpm install lance lefthook install (script prepare) : les crochets git sont posés.

Lancer

TerminalBash
pnpm dev # http://localhost:5174
AdresseÉcran
http://localhost:5174/#/application publique (espace visiteur)
http://localhost:5174/gestion/#/adminapplication du gestionnaire
http://localhost:5174/gestion/#/projectionprojection mobile (grand écran)
http://localhost:6006Storybook (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/gestion/index.html). Dans l'application publique, #/admin affiche la page d'erreur du visiteur.

Aperçu du build : pnpm --filter @flux/app preview (port 5175).

Port du portail

Le portail de documentation se lance en local par pnpm dev dans docs/, sur le port 3003 : ne lancez pas l'application sur ce port. En développement, l'espace gestionnaire y renvoie ses liens vers le portail, s'il tourne.

Tester et vérifier

TâcheCommande
Lint et format (Biome) puis typecheck de tous les paquetspnpm check
Corriger le formatpnpm fix
Tests (Vitest, happy-dom)pnpm test
Un fichier de testpnpm exec vitest run packages/core/src/affluence.test.ts
Typecheck d'un paquetpnpm --filter @flux/core typecheck
Build de l'applicationpnpm --filter @flux/app build
Style séparé du React et design simplifiénode scripts/check-styles.mjs --strict (ou avec une liste de fichiers) ; lancé par pnpm check
Storybook en local, port 6006pnpm storybook
Build de Storybook (dans storybook/dist, ignoré par git)pnpm build-storybook
Tout, avant de rendre la mainpnpm verify (check + test + build, Storybook compris, puis les budgets de poids)
Budget du script du widget (36 864 octets, soit 36 Ko)node scripts/check-embed.mjs (après le build ; lancé par pnpm verify)
Budget du premier chargement de l'application (600 Ko compressés)node scripts/check-app.mjs (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éesPYTHON=/chemin/vers/venv/bin/python pnpm data (voir les données)
Tests Rust de Tauricd app/src-tauri && cargo test

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-styles --strict, 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/design-system teste ses contrastes (83 couples) et ses jetons, @flux/illustrations 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.config.ts à 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/visiteur/src/test-utils.tsx). Un test de fumée tourne sur le vrai jeu embarqué.

Astuces :

  • @testing-library/react n'est dépendance que de @flux/ui ; les tests de l'application utilisent react-dom/client et act.
  • Sous happy-dom, un clic sur un lien #/… change l'adresse sans déclencher popstate : l'aide suivre() le déclenche à la main.
  • Un test qui monte une iframe doit poser window.happyDOM.settings.enableIframePageLoading = true.
  • Un Site de test doit avoir un lieuId (lieuId: id pour un site seul).
  • Les scénarios sur le vrai jeu (packages/core/src/scenarios.test.ts) rejouent recherche, affluence, alternatives et chemin avec chargerJeu(). @flux/core ne dépend pas de @flux/data (c'est l'inverse) : le test importe le jeu par chemin relatif (../../data/src/index). Après 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).

TerminalBash
npx --yes pnpm@12.15.0 build # app/dist (avec /gestion) et widget/dist npx --yes playwright@1.64.1 install chromium # une fois par version pnpm e2e # tous les scénarios, depuis la racine npx --yes playwright@1.64.1 test -c e2e/playwright.config.ts --project=app # ou widget, portail, accessibilite
FichierCe qu'il vérifie
e2e/app.spec.tsaccueil, 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/widget.spec.tsaccueil du site du widget ; page d'exemple qui charge le script d'intégration
e2e/portail.spec.tsaccueil du portail en français, une page DataViz, la galerie des présentations et un deck, la recherche « Paladru »
e2e/accessibilite.spec.tsaxe-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/serveur-statique.mjs 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/.resultats/.

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/workflows/verifier.yml), 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.

Diagramme

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/storybook) ; configuration dans storybook/.storybook/.

TerminalBash
pnpm storybook # http://localhost:6006 pnpm build-storybook # site statique dans storybook/dist
AccueilUn composantComposants du portail
Page d'accueil du Storybook « Plutôt là · Les Éclaireurs » : « Les Éclaireurs », le design minimaliste du 11 novembre 2026 en neuf puces (fond blanc, une seule couleur d'action, moins de boîtes, seul ce qui se clique ressemble à un bouton, aucune ombre au repos, contours fins, Nunito partout, coins moyens, toujours en clair), puis l'image d'origine des quatre Éclaireurs ; à gauche, les rubriques Design system (dont « Ombres, rayons et traits »), Illustrations et UIHistoire « GrilleChoix · Besoins » : la question « Avez-vous des besoins particuliers ? » avec six cartes de choix blanches à contour fin, chacune avec son dessin et un rond à cocher, et l'onglet Accessibility ouvert : 0 violation, 19 règles passées, « No accessibility violations found »Rubrique « Portail · Présentation », « Composants du portail » : les composants DataViz et de lecture du portail, montrés en lecture seule, comment ils sont branchés (alias, bouchon, thème du portail dont les règles du mode sombre sont retirées au passage), le décorateur toujours en clair, et ses limites

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/*/src/**/*.stories.tsx, plus l'accueil storybook/src/Introduction.mdx et la rubrique « Portail » 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: "error" : une règle violée fait échouer l'histoire.
  • Portail : les composants de docs/src/components sont importés en lecture seule par des alias (@portail/dataviz, @portail/lecture) ; le thème du portail est cantonné à ces histoires.
  • Adresse publiée : à venir. En attendant, pnpm storybook en local.

Écrire une histoire : un fichier Nom.stories.tsx à 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/check-styles.mjs le garde :

TerminalBash
node scripts/check-styles.mjs # app/, packages/ et storybook/src/ node scripts/check-styles.mjs chemin/Nom.tsx # seulement ces fichiers
RègleExemple refuséÀ la place
Pas de style={…} sauf des variables CSSstyle={{ color: "red" }}une classe du module ; style={{ "--taille": "4rem" }} 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/design-system/src/mantine/
Pas de CSS-in-JSemotion, styled-components, balise <style>un .module.css
Pas de couleur en dur hors du design system#FFC941, rgb(…), redvar(--ecl-soleil), var(--ecl-texte)
Pas de classe écrite en chaîneclassName="carte"className={classes.carte}

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_BLANCHE, 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èglesQuand le lireContenu
design-system-eclaireursavant de choisir une couleur, une ombre, un rayon, une taille de cible ou de textethème, palette, jetons --ecl-*, règle « interactif ou information », hiérarchie des boutons, contrastes
css-separeavant d'écrire du TSX ou du CSS, et quand check-styles échouela règle du style séparé et son gardien
ajouter-un-composantpour créer un composant ou en migrer un vers Mantinele dossier du composant : .tsx, .module.css, histoires, test, export
storybookpour ajouter ou corriger une histoire, vérifier un composant à 390 et 1 280 pxlancer, écrire, capturer et construire Storybook
illustrer-une-questionpour toute nouvelle image ou question posée en imagesdessiner, brancher au catalogue des plaquettes, rendre en PNG
questions-visiteur-en-imagespour modifier ou ajouter une question visiteurétat dans l'adresse, DemandeVisite, BesoinAcces
jeu-de-donneesavant de toucher packages/data/scripts/build.py, ou quand une donnée semble faussereconstruire 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.

Diagramme

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/gestionnaire/src/logique/sites.ts), pas une variable à régler.

Régler le projet

Réglage VercelValeurPourquoi
Root Directoryapple projet ne construit que l'application
Include source files outside of the Root Directoryactivé (par défaut)l'application n'est qu'une coquille : tout son code est dans packages/ (@flux/visiteur, @flux/gestionnaire, @flux/core…)
Framework PresetVite (repris de app/vercel.json)
Node.js Version22 ou plus (24 conseillé)comme en local
Variables d'environnementaucunel'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/vercel.json.

Ce que fait app/vercel.json

  • Installation : npx --yes pnpm@12.15.0 install --frozen-lockfile. pnpm 12 n'est pas toujours celui de Vercel : npx prend la version exacte du dépôt, et --frozen-lockfile refuse un pnpm-lock.yaml qui ne correspond plus aux package.json.
  • Build : npx --yes pnpm@12.15.0 run build (vérification TypeScript, puis vite build pour l'application publique et vite build --mode gestion pour celle du gestionnaire).
  • Sortie : dist (donc app/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-cache pour sw.js (avec Service-Worker-Allowed: /), manifest.webmanifest, / et index.html, pour qu'une nouvelle version arrive tout de suite ; un an, immutable, pour assets/ (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-Policy qui n'autorise que la géolocalisation (caméra et micro refusés).

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/data/generated/jeu.json tel qu'il est dans le dépôt, avec son cache generated/cache/. Pour publier de nouvelles données :

  1. reconstruire en local : PYTHON=/chemin/vers/venv/bin/python pnpm data ;
  2. vérifier : pnpm test (taille sous 2 Mo, règles de lieux, absence d'adresses et de téléphones) ;
  3. commiter jeu.json, les autres fichiers de generated/ et generated/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_PUBLIC (https://hackathon-flux-touristique.vicode.fr, dans packages/gestionnaire/src/logique/sites.ts).

SituationLiens vers le portail
Build de productionvers PORTAIL_PUBLIC : pages DataViz, Sites, Données SSP Cloud et cet onglet
VITE_PORTAIL_URL définie au build (facultatif)vers l'adresse donnée, prioritaire
Développementvers le portail local http://localhost:3003, 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 /#/admin la 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.js disent Cache-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é.
Application du gestionnaire sans connexion

L'application du gestionnaire, donnée aux offices de tourisme, est servie par le même déploiement, sans connexion : n'importe qui qui connaît son adresse peut y signaler un site, dans son propre navigateur seulement. L'application publique n'y mène pas. Ne pas diffuser cette adresse tant qu'il n'y a pas de connexion (voir les limites).

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, noConsole en avertissement. Les fichiers .md et packages/data/generated ne sont pas formatés.
  • Lefthook (lefthook.yml) : au commit, Biome sur les fichiers indexés (corrigés et réindexés) ; au push, pnpm check puis pnpm test. Les passer : LEFTHOOK=0 git commit … ou 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 par tr("Texte français") (@flux/core/i18n), sa traduction est dans packages/<paquet>/src/traductions/en/, et scripts/check-traductions.mjs vérifie qu'il ne manque rien.
  • Mouvement : un seul moment vivant par écran, avec les composants Apparition, CocheDessinee et Tampon de @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/design-system, un dossier par composant, style dans des .module.css, jetons --ecl-*, jamais de couleur en dur, une seule ombre (--ecl-ombre-flottant), aucun mode sombre (node scripts/check-styles.mjs --strict) ; chaque composant a ses histoires Storybook. Voir le design system.
  • 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 main dé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.json racine, 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/src/App.tsx) : on le change sur décision. Le détail est dans AGENTS.md.
  • Relire un fichier juste avant de l'écrire, et ne jamais défaire un changement qu'on n'a pas fait.
  • pnpm check peut échouer à cause du travail en cours de quelqu'un d'autre : vérifier son propre dossier avec pnpm 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 fix sur tout le dépôt, et côté portail node scripts/generate.mjs et pnpm build).

Limites

À garder en tête

  • La couverture de tests n'est pas mesurée (@vitest/coverage-v8 absent).
  • 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/vercel.json ; l'adresse publiée du Storybook n'est pas encore fixée.
Limites communes des données →