hermann/expria-frontend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
expria-frontend/docs/adr/006-stack-versions-2026.md

6.5 KiB
Raw Blame History

ADR 006 — Stack frontend : versions 2026 (React 19, Vite 8, TypeScript 6, Tailwind 4, RR7)

Statut : Accepté Date : 2026-04-17 Décideur : Hermann Contexte : Révélé par l'état des lieux Claude Code au démarrage du Sprint 0 frontend

Contexte

La première version d'ARCHITECTURE.md §2 listait une stack basée sur les versions "connues stables" :

  • React 18
  • Vite 5
  • TypeScript 5
  • Tailwind 3
  • React Router v6

L'état des lieux effectué par Claude Code au démarrage du Sprint 0 (2026-04-17) a révélé que le scaffold installé plusieurs semaines auparavant utilisait des versions plus récentes :

  • React 19.2.4
  • Vite 8.0.4
  • TypeScript 6.0.2
  • Tailwind 4.2.2
  • React Router v7.14.1

Cette divergence doit être résolue : soit downgrader le scaffold, soit mettre à jour la documentation.

Options envisagées

Option A — Downgrader vers les versions de la doc originale

Aligner le scaffold sur React 18, Vite 5, TypeScript 5, Tailwind 3, React Router v6.

  • Avantages : documentation historique respectée, versions "éprouvées" en production.
  • Inconvénients :
    • Casse un node_modules qui fonctionne
    • Perd l'optimisation du compilateur React 19 (Actions, useOptimistic)
    • Perd le moteur Oxide de Tailwind 4 (builds 3,5x plus rapides)
    • Perd le typage strict amélioré de TypeScript 6
    • Downgrade effectué pour des raisons qui n'existent plus (les versions récentes sont matures en avril 2026)

Option B — Mettre à jour la documentation

Accepter les versions installées et mettre à jour ARCHITECTURE.md §2 pour refléter la réalité.

  • Avantages :
    • Préserve le travail de scaffold déjà fait
    • Bénéficie des améliorations de performance des versions récentes
    • Écosystème mature : shadcn/ui supporte complètement Tailwind 4 et React 19 depuis début 2025
    • Alignement avec l'écosystème 2026 (les nouveaux tutoriels, docs, et ressources communautaires supposent ces versions)
  • Inconvénients :
    • Versions légèrement plus récentes = moins de StackOverflow disponible pour les cas exotiques
    • Mitigation : Claude Opus 4.7 connaît bien ces versions (cf. knowledge cutoff janvier 2026)

Option C — Hybride

Garder React 19, Vite 8, TypeScript 6 mais downgrader Tailwind 4 → 3 pour "compatibilité shadcn/ui classique".

  • Avantages : apparemment plus prudent.
  • Inconvénients : injustifié depuis que shadcn/ui supporte complètement Tailwind 4 avec configuration CSS-first via @theme. Ajoute de la complexité sans bénéfice.

Décision

Option B — accepter les versions installées et mettre à jour la documentation.

Stack frontend officielle au 2026-04-17

Couche Version Notes
React 19.2.x Server Components N/A (SPA pur), Actions et useOptimistic disponibles
React DOM 19.2.x
Vite 8.0.x Moteur Rolldown stable, config simplifiée
TypeScript 6.0.x Typage strict activé (voir tsconfig.app.json)
Tailwind CSS 4.2.x Configuration CSS-first via @theme, pas de tailwind.config.ts
@tailwindcss/vite 4.2.x Plugin Vite officiel (préféré au plugin PostCSS)
React Router v7.14.x Compatible API v6, data loaders disponibles
Supabase JS 2.103.x

Dépendances à ajouter lors du scaffold

Package Rôle Cf. ADR
@tanstack/react-query Cache serveur, refetch, mutations ARCHITECTURE.md §2
zod Validation des inputs formulaires SECURITY.md SEC-04
react-markdown Rendu sécurisé des rapports IA SECURITY.md SEC-05
class-variance-authority, clsx, tailwind-merge Utilitaires shadcn/ui —
lucide-react Icônes (standard shadcn/ui) —
Packages @radix-ui/react-* Primitives shadcn/ui (installés à la demande) —
@sentry/react Monitoring TECH_DEBT.md FTD-07 (après MVP)

Dépendances de développement

Package Rôle
vitest Tests unitaires
@vitest/coverage-v8 Couverture
@testing-library/react Tests React
@testing-library/jest-dom Matchers DOM
@testing-library/user-event Simulation user
jsdom Environnement DOM pour Vitest
prettier Formatage
eslint-config-prettier Intégration ESLint ↔ Prettier

Configuration Tailwind 4

Pas de tailwind.config.ts. La configuration se fait exclusivement dans src/index.css via les directives :

@import "tailwindcss";

@theme {
  --color-primary: #1B4FD8;           /* Couleur brand Expria */
  --font-sans: "Plus Jakarta Sans", system-ui, sans-serif;
  /* Autres variables de thème */
}

shadcn/ui avec Tailwind 4

La CLI shadcn/ui supporte Tailwind 4 depuis début 2025 :

npx shadcn@latest init
npx shadcn@latest add button dialog form

Les composants générés utilisent les conventions Tailwind 4 (pas de forwardRef, attributs data-slot). Le fichier de configuration reste components.json à la racine.

Conséquences

Positives :

  • Pas de perte de travail sur le scaffold existant
  • Performances optimales (build Tailwind 4 : microsecondes sur builds incrémentaux)
  • Stack aligné sur l'écosystème 2026 — facile pour un dev externe qui arrivera
  • Compilateur React 19 apporte des optimisations gratuites

Négatives :

  • Les versions récentes peuvent avoir quelques bugs non encore découverts. Mitigation : mise à jour ponctuelle vers la dernière version patch en cas de bug signalé (ex : 19.2.4 → 19.2.5).
  • Si un dev arrive avec une expertise sur React 17/18 uniquement, courbe d'apprentissage légère. Mitigation : ONBOARDING.md liste les ressources officielles pour React 19 et Tailwind 4.

À revisiter si :

  • Une faille de sécurité critique apparaît dans une version spécifique
  • Une incompatibilité bloquante est découverte entre deux packages (peu probable en avril 2026)

Actions de mise en cohérence

  1. Mettre à jour ARCHITECTURE.md §2 avec les versions ci-dessus (réalisé en session actuelle)
  2. Mettre à jour ONBOARDING.md pour référencer React 19 et Tailwind 4 dans les ressources (à faire)
  3. Aucune action sur TESTS_AUTOMATISES.md — Vitest fonctionne identiquement
  4. Aucune action sur les ADRs 001-005 — ils ne référencent pas de versions précises

Références