The codeArchitecture(in French)10 min read
Paquets partagés
Ce que contient chaque paquet et ce qu’il s’interdit, comment une application l’utilise et le câble, et pourquoi les paquets sont publiés en source.
Not translated yet
Un paquet contient ce que les applications doivent dire ou calculer de la même façon. Il ne connaît aucune application. Tout ce qui dépend d’une application (son environnement, son client Prisma, son adresse publique), on le lui passe en paramètre. Le graphe des dépendances est sur la page Architecture.
Ce que contient chaque paquet
Chaque paquet s’appelle @meublesmoriniere/<nom> et n’expose que les entrées de son exports. Un fichier qui n’y est pas, on ne peut pas l’importer.
| Paquet | Ce qu’il contient | Ce qu’il s’interdit |
|---|---|---|
db | le schéma Prisma, les migrations, le client généré et ses énumérations | toute logique. Il n’exporte que client et enums |
domain | les règles métier pures (TVA, prix, remises, port, totaux, numéros de pièce, délais et date promise, horaires, rétractation, conservation des données) et les formes de requête que les deux applications doivent lire pareil | toute connexion, le réseau, l’environnement. Ses lectures communes reçoivent le client Prisma de l’application. Il ne dépend que de zod, et des énumérations et des types de db |
contracts | ce que les deux applications s’échangent : chemins publics et machine, tags de cache, schémas des corps HTTP, signature des événements, clés des verrous Postgres communs, version de l’API Stripe | toute dépendance d’exécution autre que zod |
auth | Better Auth : les fabriques des comptes du personnel (createAuth) et des comptes clients (createCustomerAuth), les rôles, la politique de session, les limites de débit | le client Prisma. C’est l’application qui le lui passe |
infra | l’outillage sans métier : journaux et traces, collecteur d’erreurs, fabrique d’envoi d’e-mail, adaptateur et arrêt de Prisma, en-têtes de sécurité, comparaison à temps constant, horloges | les clés et les réglages d’une application. On lui passe la clé Resend, l’expéditeur et le client Prisma. Il ne lit que des variables de la plateforme (déploiement, commit, DSN public du collecteur) |
orders | les traitements de commande que les deux applications font pareil : la rétractation | tout ce qu’un test d’application simule (base, e-mail, alerte, horloge, journal). Ce sont des ports |
ui | le kit d’interface : composants, hooks, palette de couleurs | la base et l’environnement. Sa seule lecture réseau, c’est l’autocomplétion d’adresse (use-address-suggestions.ts) |
testing | l’outillage de test des deux applications : fixtures de la suite Postgres, doubles et contrôle d’accessibilité des tests e2e, gardes de base locale | le code de prod. Les applications ne le prennent qu’en devDependencies |
config | le tsconfig de base, les fabriques ESLint (frontières des couches, relais), les motifs .gitignore | toute dépendance vers un autre paquet |
Dans auth, infra et orders, les fichiers qui ne servent qu’à Next commencent par import "server-only". Si on en importe un depuis un composant client, le build échoue. Ceux que des scripts Node lisent aussi (packages/auth/src/server.ts, prisma-adapter.ts) ne peuvent pas l’importer. Pour eux, c’est le fichier de l’application qui les enveloppe qui porte la garde (apps/erp/shared/server/auth.ts).
Le code commun vit dans packages/
Le site est né d'un fork élagué de l'ERP. Le code que les deux apps partagent sort dans packages/*, et chaque app n'en garde qu'un relais d'une ligne (export * from "@meublesmoriniere/<paquet>/<entrée>";), au chemin que ses imports et ses vi.mock visent déjà. pnpm check:twins empêche le fork de se reformer. Il classe ce qui est identique dans les deux apps, et consigne le reste dans scripts/twins.manifest.json :
- les relais ne font que rouvrir une entrée de paquet. Ils n'ont aucune logique et ne sont pas consignés ;
- le code identique dans les deux apps (
code) est refusé, sauf les fichiers que le manifeste tolère encore : le câblage propre à chaque app (env,prisma, e-mail et alerte branchés sur la marque, lectures en base), les points d'entrée que Next exige dans l'app (instrumentation-client.ts,app/not-found.tsx,postcss.config.mjs), et les formulaires (voir plus bas). Cette liste ne fait que diminuer :--writerefuse d'y ajouter un fichier, qui doit sortir dans un paquet. Chaque fichier toléré doit rester identique, et une copie qui bouge seule fait échouer le contrôle ; - les fichiers statiques identiques (
static: icônes, polices embarquées, images de démonstration, réglages d'outils), que Next et Vercel servent depuis le dossier de chaque app, doivent rester identiques ; - pour les fichiers qui diffèrent déjà, toute déclaration de premier niveau présente des deux côtés (fonction, constante, type, exportée ou non) doit garder le même texte. Un fichier élagué d'un côté est donc sans effet, mais une règle de calcul corrigée dans une seule copie est refusée.
Les jumeaux se comparent au même chemin dans les deux apps, sauf pour ce que le site range ailleurs : SITE_RENAMES (scripts/check-twins.mjs) apparie alors les deux chemins, et le manifeste garde celui de l'ERP. Le tunnel de commande du site vit ainsi dans modules/checkout, face au modules/payments de l'ERP ; ses promotions et sa livraison dans modules/promotions et modules/shipping, face aux fichiers de shared/ de l'ERP ; son catalogue (liste, filtres, recherche, carte d'une pièce, catégories) dans modules/catalogue, face aux products et categories de l'ERP. Un fichier déplacé dont seuls les imports changent quitte la liste des jumeaux, mais ses déclarations restent comparées une à une.
Un écart assumé est consigné avec l'empreinte de son texte dans chaque app : s'il bouge encore, d'un côté ou de l'autre, le contrôle échoue à nouveau. pnpm check:twins --write régénère le manifeste ; il refuse d'entériner un jumeau ou une déclaration qui a divergé sans --accept-divergence, à relire dans le diff du manifeste avant de commiter.
Le contrôle ne compare que des fichiers rangés au même chemin dans les deux apps : un code commun aux deux sort dans un paquet, et ne se recopie pas sous un autre chemin pour échapper au contrôle.
Le code qui n'a plus de raison d'exister en double sort dans packages/* : packages/domain pour les règles métier et les sélections Prisma communes (un fichier d'app qui en garde une partie à lui réexporte le reste : export * from "@meublesmoriniere/domain/…"), packages/ui pour le kit d'interface, ses composants et ses hooks, packages/infra pour l'outillage technique sans métier (gardes de type, horloges, journal, adresses de la Base Adresse Nationale), packages/testing pour l'outillage de test des deux apps (fixtures de la suite Postgres, doubles et contrôle axe des tests e2e, gardes de base locale). Un paquet qui a ses propres tests les garde dans son src/__tests__/, et pnpm packages:check les joue ; les règles de packages/domain, elles, sont testées depuis les applications, à travers leurs relais. packages/contracts pour les adresses, les tags et le contrat HTTP que les deux apps s'échangent : chaque canal (/api/evenements-site, /api/devis-site, /api/factures-site, /api/revalidate) y a le schéma de son corps, que le récepteur valide. L'émetteur du cache et des événements le vérifie en plus par satisfies ; les deux demandes de PDF passent par requestErpPdf (apps/site/shared/server/erp-pdf.ts), qui prend un objet sans type. L'ERP n'a pas de route publique dans ROUTES : un lien vers le site s'écrit ${BRAND.website.url}${SITE_PATHS.X}, et un chemin relatif du site ne compile pas comme lien de l'ERP.
Dans une app, une entrée de paquet s'importe par son relais quand il existe (shared/lib/vat.ts : export * from "@meublesmoriniere/domain/vat";), jamais en direct : la règle ESLint moriniere/prefer-relay (packages/config/eslint.mjs) le corrige d'elle-même. Un relais rangé dans un module ne sert qu'à ce module.
packages/infra et packages/orders ne lisent ni l'environnement ni la base d'une app, à une exception près : le journal et le collecteur d'erreurs de infra lisent les variables publiques de la plateforme (NEXT_PUBLIC_SENTRY_DSN, VERCEL_ENV, VERCEL_GIT_COMMIT_SHA), que Next ne remplace dans le code du navigateur que lues littéralement. Ce qui dépend de l'app (clé Resend, expéditeur, client Prisma, alerte, horloge) leur est passé par l'app (createEmailSender, createWithdrawalNotices, createWithdrawalRequests), câblé dans le fichier de l'app que les tests simulent déjà (shared/server/email.ts, modules/orders/services/withdrawal.service.ts…). Un paquet n'importe jamais directement une brique qu'un test de l'app simule : un vi.mock de l'app atteint ainsi toujours son code. env, prisma et alert restent dans les apps.
Les formulaires (shared/components/forms) restent des jumeaux gardés : environ 140 fichiers de test mockent @/shared/lib/toast, et des formulaires sortis dans un paquet contourneraient ces mocks.
L’application passe ses briques au paquet
Un traitement commun aux deux applications n’importe ni l’envoi d’e-mail ni le client Prisma. On le construit avec une fabrique, et l’application lui passe ses propres briques. Voici le câblage des avis de rétractation dans le site (les demandes se câblent pareil, dans withdrawal-request.service.ts) :
import "server-only";
import { createWithdrawalNotices } from "@meublesmoriniere/orders/withdrawal";
import { emailSignature } from "@/shared/lib/email-signature";
import { describeError } from "@/shared/lib/log";
import { wallClock } from "@/shared/lib/wall-clock";
import { sendAlert } from "@/shared/server/alert";
import { isCertainlyUnsent, keyAlreadyUsed, sendEmail, sendUnderway } from "@/shared/server/email";
import { prisma } from "@/shared/server/prisma";
export const { sendWithdrawalAcknowledgement, sendWithdrawalOutOfTimeNotice } =
createWithdrawalNotices({
prisma,
sendEmail: (input) => sendEmail(input),
keyAlreadyUsed: (error) => keyAlreadyUsed(error),
sendUnderway: (error) => sendUnderway(error),
isCertainlyUnsent: (error) => isCertainlyUnsent(error),
sendAlert: (line) => sendAlert(line),
describeError: (error) => describeError(error),
wallClock: () => wallClock(),
emailSignature: () => emailSignature(),
});Le paquet orders reçoit prisma, sendEmail, sendAlert ou wallClock de l’application. Il ne les importe jamais. Donc un test du site qui simule @/shared/server/email simule aussi l’e-mail que la rétractation envoie. L’ERP, lui, câble la même fabrique avec ses propres briques. Pour l’e-mail, c’est le même principe un étage plus bas : à chaque envoi, createEmailSender (packages/infra/src/email.ts) reçoit la clé, l’expéditeur et la marque que l’application lit dans son environnement.
Du coup, le paquet se teste sans environnement. Chaque application garde un seul env, un seul prisma et une seule alert. Et les tests qui existaient couvrent le code sorti dans le paquet, sans qu’on ait eu à les retoucher.
Des paquets publiés en source
Les exports d’un paquet pointent sur ses fichiers TypeScript (./src/vat.ts), ou sur le client généré pour db. Il n’y a pas de dist, pas d’étape de build, pas de version interne. Next compile un paquet avec l’application qui l’importe, comme si c’était son propre code.
L’avantage, c’est que quand on retouche un paquet, ça se voit au rechargement suivant de l’application. Il n’y a pas de mode watch à lancer. « Aller à la définition » ouvre le code, et pas un fichier de déclarations. Et il n’y a pas de version de paquet à publier ni à aligner entre les applications.
Par contre, chaque application recompile les paquets qu’elle importe. Un paquet doit aussi compiler avec les réglages TypeScript de toutes les applications. C’est pour ça que config a un tsconfig commun, strict, avec exactOptionalPropertyTypes et noUncheckedIndexedAccess. Et aucun paquet ne peut servir en dehors de ce dépôt.
Les garde-fous
pnpm packages:checklance le typage, le lint et les tests paquet par paquet, pour ceux qui en ont, puis knip sur l’ensemble. Il échoue s’il trouve une dépendance utilisée mais pas déclarée, une entrée exportée que personne n’importe ou un fichier orphelin.- Dans une application, on importe une entrée de paquet par son relais quand il y en a un. La règle
moriniere/prefer-relaycorrige l’import toute seule. - Certaines entrées sont réservées aux comptes du personnel. Le site ne peut importer ni
auth/server, niauth/client, niauth/next, niauth/session-cookie(ERP_AUTH_ENTRIES,apps/site/eslint.config.mjs). - Les jumeaux, c’est du code identique dans les deux applications. Le push les refuse, et il faut les sortir dans un paquet (Deux applications nées d’un fork).