ansiblenginx/app/bricolociaac/docs/architecture/ADR/002-framework-frontend.md

ADR-002 : Next.js 14 comme Framework Frontend

Statut : ✅ Accepté
Date : Octobre 2025
Décideurs : Équipe Architecture
Tags : frontend, framework, react

---

Contexte

L'application moderne nécessite un framework React performant avec :

• Support TypeScript natif
• Server-Side Rendering (SSR) pour SEO
• API Routes intégrées (Backend For Frontend)
• Performance optimale
• DX (Developer Experience) excellente

Options considérées

1. Next.js 14 (App Router)
2. Remix
3. Vite + React Router
4. Create React App (CRA)

---

Décision

✅ Nous adoptons Next.js 14 avec App Router

---

Justification

Pourquoi Next.js ?

1. Écosystème Mature 🌟

• Framework le plus populaire React (utilisé par Vercel, Netflix, TikTok, etc.)
• Communauté énorme
• Documentation excellente
• Ressources d'apprentissage abondantes

2. Performance Exceptionnelle ⚡

• SSR/SSG natifs (SEO optimal)
• Streaming (React 18 Server Components)
• Image Optimization automatique (next/image)
• Code Splitting automatique
• Lazy Loading built-in

3. App Router (Next.js 14) 🚀

• Server Components par défaut (moins de JS client)
• Nested Layouts (partage de UI)
• Loading UI et Error Boundaries intégrés
• Parallel Routes et Intercepting Routes
• Routing basé sur le système de fichiers (convention over configuration)

4. Backend Intégré (BFF Pattern) 🔧

• API Routes (app/api/)
• Parfait pour notre API Gateway / BFF
• Déploiement unifié (frontend + backend)
• Middleware pour auth, logging, etc.

5. TypeScript First 📘

• Support TypeScript natif
• Typage automatique des routes
• Autocomplétion des imports

6. Déploiement Simplifié ☁️

• Vercel (hébergement optimisé)
• Déploiement en 1 clic
• Preview deployments automatiques
• Edge Functions disponibles

7. Écosystème Intégré 🛠️

• Compatible avec shadcn/ui
• Intégration Tailwind CSS excellente
• Support React Query, Zustand, etc.

---

Comparaison des Alternatives

Critère	Next.js 14	Remix	Vite + RR	CRA
SSR/SSG	✅✅✅ Natif	✅✅ Natif	⚠️ Manuel	❌ CSR only
API Routes	✅ Oui	✅ Oui	❌ Non	❌ Non
Performance	✅✅✅	✅✅	✅✅	⚠️
DX	✅✅✅	✅✅	✅✅	⚠️
Communauté	✅✅✅ Énorme	✅ Croissante	✅✅	⚠️ Déprécié
Déploiement	✅✅✅ Vercel	✅ Fly.io	⚠️ Manuel	⚠️
Courbe apprentissage	⚠️ Moyenne	⚠️ Moyenne	✅ Faible	✅ Faible
Popularité 2025	✅✅✅	✅	✅✅	❌

---

App Router vs Pages Router

Nous choisissons App Router (Next.js 13+) :

Feature	Pages Router	App Router
Server Components	❌ Non	✅ Oui
Nested Layouts	⚠️ Layout HOC	✅ Natif
Streaming	❌ Non	✅ Oui
Loading States	⚠️ Manuel	✅ Natif
Error Handling	⚠️ _error.js	✅ error.tsx
Parallel Routes	❌ Non	✅ Oui
Metadata API	⚠️ Head	✅ Metadata object
Futur	⚠️ Legacy	✅ Recommandé

Conclusion : App Router est le futur de Next.js

---

Architecture avec Next.js

Structure

apps/modern-app/
├── src/
│   ├── app/                    # App Router
│   │   ├── (auth)/            # Route group (auth pages)
│   │   ├── (main)/            # Route group (main app)
│   │   ├── api/               # API Routes (BFF)
│   │   ├── layout.tsx         # Root layout
│   │   └── page.tsx           # Home page
│   │
│   ├── components/            # React Components
│   ├── services/              # Microservices logic
│   └── lib/                   # Utilities

BFF Pattern avec API Routes

// app/api/reservations/route.ts
export async function POST(request: Request) {
  // API Gateway logic
  const data = await request.json()
  
  // Orchestrate microservices
  const availability = await inventoryService.check(data)
  const reservation = await reservationService.create(data)
  const payment = await paymentService.createIntent(reservation)
  
  return Response.json({ reservation, payment })
}

---

Conséquences

✅ Avantages

1. Performance : Lighthouse scores > 95
2. SEO : SSR natif
3. DX : Hot reload, Fast Refresh
4. BFF : API Routes intégrées
5. Déploiement : Vercel en 1 clic
6. Maintenance : Framework mainstream
7. Portfolio : Technologie recherchée

⚠️ Inconvénients

1. Complexité initiale : App Router = courbe d'apprentissage
2. Magie : Conventions à connaître (Server Components, etc.)
3. Vendor lock-in : Optimisé pour Vercel (mais pas obligatoire)

🛠️ Mitigations

• Formation App Router (documentation Next.js)
• Exemples de code commentés
• Isolation de la logique métier (services indépendants)

---

Alternatives Rejetées

❌ Remix

Avantages :

• Excellente gestion des forms
• Nested routes puissants
• Philosophie web-native

Raisons du rejet :

• Communauté plus petite
• Moins de ressources/exemples
• Déploiement moins simple que Vercel
• Moins connu = moins impressionnant pour portfolio

❌ Vite + React Router

Avantages :

• Build ultra-rapide (Vite)
• Flexibilité maximale
• Lightweight

Raisons du rejet :

• Pas d'API Routes intégrées (besoin backend séparé)
• SSR manuel à configurer
• Moins de conventions (plus de décisions)
• Pas de BFF pattern natif

❌ Create React App (CRA)

Raisons du rejet :

• Déprécié officiellement par React
• CSR only (pas de SSR)
• Performance médiocre
• Pas d'API Routes
• Pas adapté 2025

---

Références

• Next.js 14 Documentation
• App Router vs Pages Router
• Server Components
• Vercel Deployment

---

Validations

• POC App Router réalisé
• Tests performance (Lighthouse)
• Compatibilité avec Supabase validée
• shadcn/ui compatible ✅

---

Prochaine révision : Si Next.js 15 sort avec changements majeurs