ADR-0003 — Monorepo unique Turborepo + pnpm, mobile en npm hors workspace

Status : Accepted Date : 2026-02 (rétroactif) Deciders : équipe plateforme Nex Tickets : —

Contexte

La plateforme Nex compte 5 apps (3 mobiles, 2 dashboards web), 11 microservices et 9 packages partagés. Trois options s’offraient au démarrage :

1. Polyrepo — un repo par projet.
2. Monorepo unifié pnpm + Turborepo.
3. Monorepo Nx.

L’expérience avec Expo / React Native a montré que Metro bundler et pnpm cohabitent mal : pnpm utilise des symlinks et un store global, Metro fait du resolution flat et ne supporte pas bien les symlinks. Les apps mobiles ont besoin de leurs propres node_modules plats.

Décision

1. Monorepo unique nex/ avec pnpm workspaces + Turborepo pour les packages et services.
2. Les 3 apps mobiles (mobile-client, mobile-business, mobile-pro) sont exclues du workspace pnpm (pnpm-workspace.yaml les exclut explicitement) et utilisent npm avec leur propre node_modules.
3. Les packages partagés @nex/tokens, @nex/ui-mobile, @nex/mobile-auth, @nex/shared-types, @nex/shared-utils sont liés par file: link dans les package.json mobiles, pas par workspace protocol.
4. Pour Metro : watchFolders pointé vers la racine monorepo et nodeModulesPaths inclut app + racine.

Conséquences

Positives

• Cohabitation Expo / monorepo qui fonctionne sans patch natif.
• Réutilisation des packages partagés entre web (pnpm) et mobile (npm) via file: link.
• Turborepo accélère les builds des packages et services backend.
• Une seule source de vérité pour les conventions, configs ESLint et TS.

Négatives / risques

• Confusion possible pour un nouveau dev : « pourquoi npm ici et pnpm là-bas ? ». Mitigation : documenté dans /dev/getting-started et CLAUDE.md.
• Les mobiles doivent installer leurs deps séparément (npm install par app).
• Pas de hoisting cross-app pour mobile (chaque app a son node_modules).

Alternatives écartées

• Polyrepo — coordination MR multi-repos, partage de packages via npm-publish ou git-submodule, complexité d’onboarding élevée.
• Tout en pnpm avec patches Metro — fragile, casse à chaque upgrade Expo, déjà testé en début de projet.
• Nx — courbe d’apprentissage plus raide, écosystème moins natif côté Expo.

Suivi

• pnpm-workspace.yaml exclut explicitement apps/mobile-client, apps/mobile-business, apps/mobile-pro.
• Commandes documentées dans le CLAUDE.md racine.
• Voir /dev/getting-started.