Skip to Content
Meubles Morinière

The codeArchitecture(in French)19 min read

Next.js et React

Comment l’ERP et le site utilisent Next.js 16 et React 19 (composants serveur et client, rendu, lectures, cache, flux, navigation, état) : le problème que règle chaque choix, ce qu’il change et ses limites.

Not translated yet

This page is shown in its original French. Code excerpts, tests and figures read the same in either language.

L’ERP et le site ont la même stack : Next.js 16 en App Router et React 19, avec une seule version pour tout le dépôt (catalog: de pnpm-workspace.yaml). Leurs next.config.ts activent les mêmes options : cacheComponents, partialPrefetching, reactCompiler et typedRoutes. La doc, ce sont des pages statiques, donc elle n’active que le compilateur React.

Par contre, les deux applications ne s’en servent pas de la même façon. Le site sert le même catalogue à tout Internet, donc il met en cache tout ce qui est commun à ses visiteurs. L’ERP sert une équipe qui modifie ce qu’elle lit, donc il ne met presque rien en cache et il relit la base à chaque écran. Les règles d’écriture qui vont avec sont là où on les applique : Interface de l’ERP pour l’ERP, Site public pour le site.

ChoixProblème régléCe qui le fait respecter
Composants serveur par défautla base et les clés ne doivent jamais arriver dans le navigateur, et le site doit rester léger sur téléphoneimport "server-only" au build, couches vérifiées par ESLint
Coquille statique, trous à la requêteune lecture de cookie ou de l’heure rendait toute la route dynamique, ou la figeait sans le direle build refuse une lecture de la requête hors Suspense
Lectures serveur, une fois par rendudes lectures en cascade, et les mêmes lectures répétées dans un renduPromise.all, cache() de React, garde de session en tête de chaque lecture
Cache par tags sur le site, presque aucun dans l’ERPle site doit tenir la charge sans servir un prix périmé, et l’équipe doit voir ce qu’elle vient d’écriretests de couverture des invalidations et d’appariement des tags
Un Suspense par bloc secondaireune lecture lente bloquait tout l’écranRevealSuspense, ReadFailureBoundary, un loading.tsx par route de l’ERP
Préchargement partiel, <Activity>, transitions de vueune application rendue au serveur doit naviguer sans attendre ni perdre sa placepartialPrefetching, typedRoutes
L’état au serveur et dans l’adresseune donnée recopiée côté client devient périmée, et il faut l’invalider à la mainaucun cache client, et useMemo, useCallback et memo interdits par ESLint

Composants serveur et composants client

Les deux applications lisent une base Postgres, avec des clés qui ne doivent jamais sortir du serveur. Et le site s’ouvre surtout sur téléphone, où chaque kilo-octet de JavaScript compte. Dans une application React rendue dans le navigateur, tous les composants y partent, et chaque donnée passe par une API qu’il faut écrire, protéger et maintenir.

Ici, un composant reste serveur tant qu’il n’a pas besoin du navigateur. "use client" ne sert que pour ce qui est interactif (formulaires, volets, galerie, recherche, palette). Un composant serveur lit la base avec une fonction de modules/*/data, sans API au milieu. Ensuite, il passe au composant client des données sérialisables ou des éléments déjà rendus. Par exemple, sur la fiche d’un meuble, le bouton d’achat et les conditions de chaque déclinaison sont rendus au serveur (ProductOfferList). Le sélecteur client (ProductOfferPicker) choisit juste lequel montrer. Les écritures passent par des Server Actions ("use server", modules/*/actions).

Du coup, il n’y a pas d’API REST entre l’ERP et sa base. Le type d’un select Prisma va jusqu’au composant qui l’affiche. Prisma, les clés et les règles de calcul restent au serveur, donc ils ne pèsent rien dans le JavaScript envoyé. Ce poids, pnpm size et pnpm site:size le mesurent après le build. Un fichier serveur commence par import "server-only". Si on l’importe par erreur dans un composant client, le build échoue et le fichier ne part pas dans le navigateur. Les fichiers de paquet que des scripts Node lisent aussi (packages/auth/src/server.ts, l’adaptateur Prisma) ne l’importent pas : c’est le fichier de l’application qui les enveloppe qui porte la garde. Et le lint interdit Prisma dans app/, et dans l’ERP aussi dans les actions et les composants (Rangement du code).

Ce choix a ses limites :

  • Entre le serveur et le client, tout est sérialisé. Une fonction (sauf une Server Action) ou une instance de classe ne passe pas. Un composant client ne peut pas importer un composant serveur. Il le reçoit en children ou en prop, donc il faut penser la page en emplacements.
  • Une Server Action, c’est un point d’entrée HTTP public. On peut l’appeler sans passer par l’écran. Donc chaque action revérifie la session (readAdminSession() dans l’ERP) et valide son entrée, comme une route d’API.
  • Une Server Action a un identifiant qui change à chaque déploiement. Du coup, un onglet ouvert avant une mise en prod appelle une action qui n’existe plus. useAdminAction reconnaît ce refus (unstable_isUnrecognizedActionError) et demande de recharger la page (STALE_DEPLOYMENT_MESSAGE). Sans ça, l’erreur ne se verrait pas.
  • Le corps d’une action a une taille maximale (SERVER_ACTION_BODY_LIMIT_BYTES). Donc les photos ne passent pas par une action. Elles partent directement du navigateur vers Vercel Blob (apps/erp/modules/media/lib/media-deposit.ts).

Une coquille statique, des trous servis à la requête

Sans cacheComponents, il suffisait d’une lecture de cookie, d’en-tête ou de l’heure pour que toute la route devienne dynamique. La barre et le pied de page, qui sont les mêmes pour tout le monde, étaient refaits à chaque visite. Et dans l’autre sens, une route pouvait devenir statique sans qu’on l’ait décidé, et servir une heure ou une disponibilité figées au build.

cacheComponents active le prérendu partiel. Chaque route a une coquille prérendue, et des trous qui sont servis à la requête. Tout ce qui lit une donnée de la requête (cookie, searchParams, en-têtes, heure) doit être sous son propre <Suspense> ou dans une fonction "use cache". Sinon, le build échoue. L’heure se lit avec requestNow() (packages/infra/src/request-clock.ts), après un await io() qui sort la suite de la coquille. Dans l’ERP, le layout est statique. La barre latérale et l’en-tête arrivent avec la coquille. La garde de session et les pastilles de compteurs suivent, chacune sous son Suspense (apps/erp/app/(console)/layout.tsx).

Résultat, une page s’affiche avec sa barre, son en-tête et ses squelettes avant même de lire la base. Dans le code, on voit composant par composant ce qui est statique et ce qui est dynamique, et le build refuse ce qui n’est pas clair. En dev, instantInsights signale ce qui empêcherait une navigation d’être instantanée : une lecture sans cache hors Suspense, ou un Suspense qui ne couvre qu’un des chemins par lesquels on arrive sur la page.

Ce découpage a aussi ses limites :

  • Chaque composant doit suivre la règle. Un new Date() sans io() juste avant fige l’heure dans la coquille, et le magasin y resterait « ouvert » toute la nuit.
  • Next refuse qu’une route à paramètre renvoie une liste vide depuis generateStaticParams. Quand le catalogue est vide, atLeastOneParam (apps/site/shared/lib/static-params.ts) lui donne un paramètre de remplacement.
  • Au début, la barre du site lisait l’adresse hors Suspense. La coquille générique d’une fiche (pour un paramètre que le build ne connaît pas) restait vide, et chaque fiche absente du build répondait 500 alors que la base marchait (constaté sur un build de prod). Du coup, ces routes déclaraient instant = false et attendaient leur rendu. Maintenant, ce qui lit l’adresse le fait sous sa propre frontière (apps/site/shared/components/address-reader.tsx). La coquille générique se prérend, et une adresse absente du build reçoit tout de suite la barre et le squelette. apps/site/test/param-routes-blocking.regression.test.ts vérifie qu’aucune route à paramètre ne remet la déclaration.
  • Le build prérend des pages qui lisent la base de prod, donc une migration se joue avant la fusion (Données).

Des lectures serveur, en parallèle, une fois par rendu

Une page de l’ERP fait souvent plusieurs lectures, qui ne coûtent pas du tout la même chose. Et dans un même rendu, plusieurs composants ont besoin de la même donnée. C’est le cas de la session : le layout, la page et chaque pastille la vérifient. C’est aussi le cas du panier, que la barre du site compte deux fois (téléphone et bureau).

Une lecture, c’est une fonction asynchrone de data/. Le composant serveur qui l’affiche l’appelle directement. Il n’y a pas de fetch vers sa propre API, ni de bibliothèque de lecture côté client. Les lectures indépendantes partent ensemble (Promise.all). Quand une lecture est partagée dans un rendu, elle passe par cache() de React. La session de l’ERP n’est donc lue qu’une fois par requête (openAdminSession, apps/erp/shared/server/admin-session.ts), et le cookie du panier n’est déchiffré qu’une fois (getCart). Dans l’ERP, une lecture qui touche une donnée sensible, et chaque get-admin-*, commence par la garde requireAdminReader(). Sur le site, une lecture get-* passe par le cache. Sa jumelle read-* le contourne, pour une transaction ou un paiement.

Du coup, pour les données de la page, il n’y a pas d’état de chargement côté client, ni de cascade de requêtes qui part du navigateur. Une lecture est une fonction, et les tests la simulent par son chemin. Et un bloc différé lit lui-même ses données, il n’attend pas que la page les lui passe.

Il reste des limites :

  • cache() ne dure que le temps d’un rendu. Dans une Server Action, la même fonction relit à chaque appel.
  • Une fois la page affichée, une donnée lue au serveur ne se met pas à jour toute seule. Il faut une navigation, un router.refresh() ou un refresh() depuis une action. Ils refont le rendu serveur de la route et rejouent ses lectures. C’est comme ça que le tableau de bord se rafraîchit quand une notification arrive sur l’appareil, avec un intervalle minimal pour ne pas marteler la base (DashboardLiveRefresh). Il n’y a pas d’abonnement en temps réel.
  • Aucun outil n’empêche un await en série inutile. La règle est écrite (Interface de l’ERP) et elle se vérifie à la relecture.

Le cache : tout sur le site, presque rien dans l’ERP

Le site sert le même catalogue à tous ses visiteurs. Relire la base à chaque visite coûterait du temps et de l’argent. Sauf qu’avec un prix, un stock ou une date promise périmés, on vend une pièce déjà partie ou on annonce un délai faux. Et le Merchant Center sanctionne un écart entre la page et le flux produits. L’ERP, lui, sert une équipe qui modifie ce qu’elle lit. Là, une valeur périmée, c’est une erreur.

Sur le site

Toute lecture commune aux visiteurs a "use cache", un profil de durée (cacheLife) et des tags (cacheTag). Les profils sont dans apps/site/shared/constants/cache-life.ts#CACHE_LIFE. Les tags sont dans packages/contracts/src/cache-tags.ts, et les deux applications les partagent. Après chaque écriture, l’ERP de prod envoie au site les tags à invalider (POST /api/revalidate). Tout ce qui porte un prix, un stock, un port ou une date expire tout de suite. La taxonomie, elle, est servie dans son ancienne version le temps de se refaire. La durée d’un profil sert seulement de filet, au cas où un avis se perd. Elle se raccourcit toute seule jusqu’à la fin d’une remise (catalogueLifeUntilDiscountEnds). Comme ça, une promotion s’arrête à l’heure sans que personne ait à prévenir le site. Quand une lecture dépend du visiteur, elle lit son cookie hors cache, puis elle passe la part commune à une fonction en cache, avec ses identifiants en argument.

Les pages du catalogue sont donc servies depuis le cache, et on ne lit la base que quand une entrée expire. Un prix retouché dans l’ERP se voit à la visite suivante. Si la base est lente au moment d’une écriture, la barre de chaque page ne tombe pas, parce que la taxonomie garde sa dernière copie. Quand l’ajout au panier découvre que la fiche affichée est périmée (la pièce vient d’être vendue au magasin), l’action fait expirer elle-même l’entrée (updateTag, apps/site/modules/cart/actions/add-to-cart.ts), et sa réponse redessine la fiche avec l’état actuel. Une limite de débit par connexion empêche de s’en servir pour vider le cache.

Ce cache a ses limites :

  • Tout repose sur les tags. Une lecture qui montre un prix sans avoir le tag variants resterait périmée jusqu’à la fin de son profil. apps/erp/test/cache-invalidation.regression.test.ts relève les actions qui doivent invalider. Et apps/erp/test/silent-failure-harness/cache-tag-pairing.test.ts vérifie que chaque tag lu est invalidé par au moins une écriture.
  • L’invalidation passe par le réseau. L’ERP réessaie dans after(), une fois sa réponse partie (SITE_REVALIDATE_RETRY_DELAYS_MS), puis il journalise l’échec. Si le site reste injoignable plus longtemps, il sert sa copie jusqu’à la fin du profil. Une preview ou un poste de dev ne purge jamais le site public (Échanges).
  • Quand un prix expire tout de suite, c’est le visiteur suivant qui paie un rendu sans cache.
  • Les arguments d’une fonction "use cache" font partie de sa clé. Une donnée propre au visiteur ne doit jamais y entrer. Donc chaque lecture qui en dépend doit être coupée en deux.

Dans l’ERP

Les lectures de l’ERP ne passent pas par "use cache", parce que la créatrice édite ce qu’elle lit (apps/erp/modules/colors/data/get-admin-colors.ts). Une action qui écrit appelle refresh() (next/cache). Ça refait le rendu de la route ouverte avec les données fraîches, dans la même réponse. Il n’y a que deux choses en cache : la grille de port et les fermetures du magasin, que lisent les devis, la livraison et Fisher. Leurs actions les font expirer sur place avec updateTag et préviennent le site dans le même geste (tagRevalidator, apps/erp/shared/lib/catalogue-cache.ts).

Après un geste, l’écran montre donc l’état de la base. Il n’y a pas de cache client à invalider ni de copie à réconcilier. Et aucune lecture gardée par la session ne se retrouve partagée entre deux personnes à cause d’un cache.

Par contre, chaque navigation et chaque geste relisent la base. L’ERP fait plus de requêtes pour avoir des données fraîches. Il peut se le permettre, parce que ses utilisateurs, c’est une équipe et pas tout Internet. La vitesse qu’on ressent vient du flux et du préchargement de la coquille. Elle ne vient pas du cache.

Le flux : la page n’attend pas sa lecture la plus lente

Si une page attend toutes ses lectures avant de s’afficher, elle met le temps de la plus lente. C’est ce qui se passait avec la liste des commandes : un compteur de bas de page la retenait.

Du coup, la page part en flux. Ce qu’on connaît d’avance s’affiche tout de suite. Chaque bloc secondaire lit ses données dans son propre composant serveur, sous son Suspense, et il arrive à son rythme. Dans l’ERP, RevealSuspense passe du squelette au contenu avec une transition de vue, et ReadFailureBoundary entoure chaque bloc différé. Chaque route a son loading.tsx, fait avec le vrai en-tête et les squelettes de ses blocs. Sauf les listes des commandes et des meubles (et le tableur des meubles) : la page rend son en-tête tout de suite et met sa liste sous RevealSuspense. Le détail des règles est dans Interface de l’ERP. Dans les deux applications, les bornes d’erreur par bloc utilisent catchError (next/error), et pas une borne React écrite à la main. Son retry() refait le rendu dans une transition sans perdre l’état autour. Et il laisse passer redirect() et notFound(), que Next lève comme des erreurs. C’est pour la même raison qu’une lecture facultative qui attrape une erreur la relance d’abord avec unstable_rethrow (apps/erp/shared/server/read-failure.ts).

L’en-tête, les titres et les libellés s’affichent tout de suite. Le squelette a la typographie du texte qu’il remplace, donc la page ne saute pas quand les données arrivent. Si une lecture échoue, seul son bloc s’éteint, avec de quoi réessayer, et l’erreur part au collecteur.

Le flux a aussi un coût :

  • Pour chaque bloc différé, il faut un composant, un squelette et une borne d’erreur. Ça fait plus de fichiers, et le squelette doit suivre son bloc. C’est pour ça qu’il est rangé à côté du bloc et qu’il sert aussi au loading.tsx.
  • Une fois que le flux a commencé, le statut HTTP est déjà parti. Un notFound() appelé sous un Suspense garde le statut 200, et Next ajoute seulement une balise noindex. Donc la fiche d’un meuble disparu répond 200, et certains moteurs classent ça en « soft 404 ».
  • Quand les frontières se résolvent l’une après l’autre, la page clignote. Donc une pastille prend fallback={null} pour ne réserver aucune place, et un bloc visible arrive en fondu.

La navigation

Avec une application rendue au serveur, on risque d’attendre le serveur à chaque clic. Sauf que l’équipe se sert de l’ERP toute la journée, pour des gestes répétés. Et le site se visite sur des réseaux mobiles, avec des allers-retours entre le catalogue et les fiches.

  • Avec le préchargement partiel (partialPrefetching), Next précharge une coquille par route, et tous les liens qui y mènent la réutilisent. Ça évite un préchargement par lien visible. Ce qui dépend de l’adresse (paramètres, searchParams) arrive après le clic. Un lien demande plus quand l’intention est forte : la ligne active de la recherche rapide du site précharge sa fiche entière (prefetch={active ? true : "auto"}, quick-search-rows.tsx).
  • Avec cacheComponents, une page qu’on quitte est gardée sous <Activity>. Elle n’est pas démontée, elle est cachée, avec son DOM et son état. Quand on revient au catalogue, on retrouve le fil comme on l’a laissé, à la même hauteur (apps/site/modules/catalogue/lib/catalogue-return.ts).
  • Chaque clic a un retour immédiat. Un lien en attente le montre avec useLinkStatus (LinkLoadingIndicator), mais seulement après un délai, pour qu’une navigation rapide ne clignote pas. Un onglet de liste change d’aspect avant la réponse (useOptimistic). Et la recherche remplace l’adresse dans une transition, sans remonter la page (router.replace(href, { scroll: false })).
  • Les transitions de vue (<ViewTransition> et les types de transition de React, addTransitionType) servent à plusieurs choses. La photo d’une carte voyage jusqu’à sa fiche, le trait glisse sous l’onglet courant, et dans l’ERP le résultat d’un geste est marqué (GESTURE_RESULT). Tout est en default="none", donc une transition qui n’a rien à voir, comme un filtre ou un rafraîchissement, n’anime rien.
  • Les adresses sont vérifiées. Avec typedRoutes, un lien vers une route qui n’existe pas ne compile pas. Et Next génère le type des paramètres de chaque page (PageProps<"/commandes">).
  • Le proxy (proxy.ts, c’est le nom que Next 16 donne au middleware) écarte, avant tout rendu, une requête de l’ERP qui n’a pas de cookie de session signé. Il la renvoie vers la connexion avec son adresse de retour. C’est juste un filtre rapide. La vraie garde, c’est chaque lecture et chaque action qui revérifient la session. Les redirections simples sont déclarées dans next.config.ts, qui passe avant le proxy.

Au final, un clic dans l’ERP montre tout de suite la coquille de l’écran suivant, avec ses titres et ses squelettes. Sur le site, le retour arrière est instantané et on retrouve sa place. Et quand une erreur part au collecteur, elle emporte les dernières navigations (onRouterTransitionStart, apps/erp/instrumentation-client.ts).

Il y a des contreparties :

  • Une page cachée sous <Activity> reste dans le document. Elle prend de la mémoire, et ses effets se rejouent à chaque retour. Un effet qui ne doit jouer qu’une fois doit donc s’en protéger. C’est le cas du replacement du fil (catalogue-feed.tsx), de la réouverture du volet après un ajout (add-to-cart-form.tsx) et du basculement d’un favori (toggle-wishlist-item.ts).
  • Le préchargement ne tourne pas en dev. Donc pour juger la vitesse d’une navigation, il faut un build de prod.
  • Avec la coquille seule, le contenu propre à l’adresse arrive après le clic. On voit donc un squelette un court instant, alors qu’un préchargement complet aurait tout montré.
  • Un nom de transition doit être unique dans la page, parce que deux éléments avec le même nom annulent toute la transition. Et un navigateur qui n’a pas les transitions de vue change juste d’écran d’un coup.
  • Plusieurs options sont encore expérimentales ou marquées unstable_ (instantInsights, instrumentationClientRouterTransitionEvents, le compilateur React en Rust de Turbopack, unstable_rethrow, unstable_isUnrecognizedActionError). Il faut les relire à chaque montée de version. partialPrefetching deviendra le comportement par défaut à la prochaine version majeure, et l’option disparaîtra.

L’état

Quand on recopie une donnée dans un état client, elle devient périmée et il faut l’invalider à la main.

  • La donnée reste au serveur. Ce que la base sait, on ne le recopie pas dans un store. Le composant serveur le relit, et refresh() le redessine après une écriture.
  • L’adresse garde ce qui doit survivre. Les filtres, la recherche, les onglets, la pagination et l’aperçu sont dans searchParams, et la page serveur les lit. Un rechargement ou un lien les gardent, et l’e-mail du matin mène directement à une liste filtrée.
  • Pendant un geste, useOptimistic montre le résultat avant la réponse : réordonner une liste (useOptimisticOrder), ouvrir ou fermer la boutique, changer d’onglet. Si l’action échoue, l’affichage revient tout seul en arrière à la fin de la transition.
  • Dans un formulaire, c’est useActionState qui reçoit la réponse de l’action. Dans l’ERP, useAdminAction l’enveloppe une fois pour toutes. Il gère la politique des toasts, le retour haptique, la session expirée (la saisie reste à l’écran), le conflit à rejouer et le déploiement dépassé. Les champs, c’est TanStack Form qui les gère.
  • Zustand sert pour ce que partagent des composants éloignés, qui n’ont pas de parent commun : le dialogue ouvert, la requête de la palette, Fisher, les toasts, et sur le site le compte du panier et le volet ouvert. Un store n’existe que dans le navigateur, donc sa valeur de départ vient du serveur. C’est le cas du compte du panier, lu au rendu (cart-sheet-trigger.tsx).
  • Les sources du navigateur (requêtes média, stockage local) se lisent avec useSyncExternalStore. Et avec useEffectEvent, un effet peut lire les dernières valeurs sans se réabonner.
  • Le compilateur React mémoïse tout seul. ESLint interdit useMemo, useCallback et memo (packages/config/eslint.mjs), et c’est le compilateur qui pose les mémoïsations utiles.

Du coup, il n’y a pas de cache client à invalider, ni de copie de la base à réconcilier. Après un geste, l’écran montre la base. Et un composant n’a plus de tableaux de dépendances à maintenir pour ses calculs.

Ce modèle a ses limites :

  • Chaque écriture coûte un aller-retour au serveur et refait le rendu de la route, avec ses lectures. Ça va pour le rythme d’une équipe. Par contre, une édition continue, qui écrirait à chaque mouvement, en souffrirait.
  • Un état gardé sous <Activity> survit au retour, même quand il ne faudrait pas : un formulaire déjà envoyé, un volet resté ouvert.
  • Le compilateur part du principe que le code suit les règles de React (pas de mutation pendant le rendu, des hooks toujours dans le même ordre). Un composant qui ne les respecte pas n’est pas optimisé. Les règles react-hooks du lint signalent la plupart de ces cas.
  • Un store Zustand vit dans l’onglet. Deux onglets ne le partagent pas, et un rechargement le vide, sauf s’il s’enregistre lui-même dans le stockage local (le dernier moyen de paiement du jour, last-off-site-sale-store.ts).

On this page