_Assistant_Lead_Tech/knowledge/backend/risques/nextjs.md

Backend — Risques & vigilance : Next.js

Extrait de la base de connaissance Lead_tech. Voir knowledge/backend/risques/README.md pour l'index complet.

---

Prisma initialisé au chargement de module — casse le build Next.js

Risques

• Un import global qui initialise Prisma immédiatement peut faire échouer la collecte de pages/routes au build si DATABASE_URL n'est pas disponible dans l'environnement de build

Symptômes

• PrismaClientInitializationError ou Error: Environment variable not found: DATABASE_URL au next build
• L'app tourne en dev mais le build CI échoue

Bonnes pratiques / mitigations

• Préférer une initialisation lazy-safe : retarder l'accès DB au moment de l'appel métier

• Retourner un proxy qui lève une erreur claire uniquement lors du premier accès réel à la DB

• Ne jamais instancier new PrismaClient() au top-level d'un module importé par Next.js

• Contexte technique : Next.js App Router / Prisma — app-template-resto 16-03-2026

---

server-only dans les repositories — bloque les tests unitaires

Risques

• import "server-only" empêche l'exécution des fichiers hors runtime Next.js
• Les tests Node.js échouent avec Error: This module cannot be imported from a Client Component module

Symptômes

• Tests qui passent via le dev server mais échouent via jest en mode node
• Erreur au require() d'un repository depuis un test unitaire

Bonnes pratiques / mitigations

• Ne mettre server-only que dans les fichiers qui utilisent des APIs Next.js runtime (cookies(), headers(), redirect())

• Ne pas mettre server-only dans les repositories purs (qui n'appellent que Prisma)

• Alternative de secours : créer un stub node_modules/server-only/index.js no-op pour les tests

• Contexte technique : Next.js App Router / Jest — app-template-resto 16-03-2026

---

Redirect vers la page désactivée elle-même (boucle infinie feature flags)

Risques

• Une page désactivée redirige vers elle-même via le fallback — boucle infinie silencieuse absorbée par Next.js mais UX cassée

Symptômes

• Page / désactivée → redirect vers buildLocalizedPath("home") = / → boucle
• Next.js absorbe la boucle mais l'utilisateur voit un écran bloqué ou vide

Bonnes pratiques / mitigations

// Si la page est sa propre destination de fallback, ne pas rediriger
if (pageKey === "home") return null; // évite redirect home → home
return buildLocalizedPath(locale, "home");

• Règle : dans tout mécanisme de redirection sur page désactivée, toujours vérifier que pageKey !== fallbackKey

• Retourner null (accès non bloqué) plutôt que de boucler

• Contexte technique : Next.js App Router / feature flags tenant — app-template-resto 17-03-2026