2026 Monorepo front-end : pièges sur Mac distant —
pnpm, cache Turborepo distant et miroirs de registre (checklist en trois étapes)
Sur un Mac distant, un monorepo pnpm + Turborepo donne souvent des caches incohérents et des CI rouges après un changement de miroir npm. Ici : tableau cache local vs distant, risques de miroir, puis trois blocs (variables d’environnement, turbo.json, parité CI), des phrases pour vos runbooks, des liens vers le blog, et l’achat MacWww sans connexion obligatoire pour parcourir les offres.
01 Pourquoi le monorepo sur Mac distant casse le cache et les installs
SSH sur Mac loué ≠ poste local : profils, chemins et utilisateur CI diffèrent. pnpm (store adressé par contenu) et Turborepo (hachage des entrées) punissent toute dérive Node, registre ou variable non déclarée — d’où l’impression de cache « cassé ».
- Env cachées.
process.env.API_URLabsente depassThroughEnv/env→ hit cache distant invalide. - Store instable. Chemins de store différents → duplication et liens durs rompus.
- Miroir lent. Bascule sans lockfile figé → résolutions divergentes malgré des semver « identiques ».
02 Turborepo : cache local et cache distant côte à côte
Matrice pour décider du cache distant sur Mac loué. Il accélère les rebuilds mais impose env et entrées strictes pour éviter un artefact réhydraté hors contexte.
| Dimension | Cache Turbo local | Cache Turbo distant |
|---|---|---|
| Vitesse en série chaude | Rapide sur une machine ; perdu si l’instance est recyclée | Rapide entre collègues et CI si les clés concordent exactement |
| Coût opérationnel | Disque uniquement ; réinitialisation simple via prune ou vidage cache | Quotas vendeur, jetons d’auth, latence réseau au premier fetch |
| Sécurité / audit | Reste sur l’hôte ; plus simple pour les builds réglementés | Revue du périmètre de confiance ; éviter les tâches dont les sorties embarquent des secrets |
| Mode de défaillance | Un miss impose un rebuild local | Un mauvais hit produit une sortie erronée jusqu’à invalidation ou désactivation des lectures distantes |
03 Changer de miroir npm : ce qui casse vraiment
Le vrai danger du miroir est la résolution incohérente (lockfile, auth, scoped) entre Mac distant et CI.
| Risque | Symptôme typique | Atténuation |
|---|---|---|
| Délai de métadonnées | pnpm install résout un patch plus récent en CI que sur le Mac |
Versionner pnpm-lock.yaml ; pnpm install --frozen-lockfile en CI |
| Configuration mixte | Packages scoped vers npmjs, autres vers miroir ; empreintes tarball divergentes | Centraliser .npmrc dans le dépôt ; une politique de miroir par environnement |
| Jetons et portée | Packages privés en 401 sur le Mac distant mais pas en local | Mêmes secrets CI et profil shell sur le Mac, même hôte de registre |
| « Poisoning » de cache Turbo | Tâche mise en cache pendant que le miroir servait le paquet A ; machines ultérieures reçoivent B | Incrémenter globalDependencies ou les entrées du pipeline lors d’un changement de politique registre |
04 Étape 1 — Variables d’environnement (store pnpm, registre, Turbo distant)
Mêmes valeurs sur shell Mac loué, doc équipe et secrets CI — prérequis d’un turbo run build prévisible.
- Store pnpm :
PNPM_HOME+ répertoire stable pour liens durs. - Registre :
NPM_CONFIG_REGISTRYou.npmrcdépôt (évite miroir global silencieux). - Turbo distant :
TURBO_TOKEN/TURBO_TEAMseulement où lecture-écriture utile. - Node : même majeure qu’en CI (fnm/nvm +
.node-version). - Check SSH :
node -v,pnpm -v,pnpm config get registry.
05 Étape 2 — turbo.json : contrat de clés de cache
Le pipeline lie Mac loué, collègues et CI : outputs manquants ou env omises = cache distant « aléatoire ».
- outputs / inputs : dossiers écrits (
dist/**,.next/**) ;inputsétroits. - passThroughEnv / env : tout ce qui change le compilé ; runtime seul hors build.
- globalDependencies : lockfiles,
.npmrc, toolchain. - remoteCache : désactiver écritures sur branches expérimentales.
06 Étape 3 — Même recette en CI et sur le Mac développeur
CI = même install + mêmes commandes Turbo que le playbook SSH (éviter « CI verte, SSH rouge »).
- Install :
pnpm install --frozen-lockfilepartout. - Turbo : version épinglée,
pnpm exec turbo. - Secrets :
TURBO_TOKENsur branches protégées ; pas d’écriture cache depuis forks. - Logs : conserver traces
.turbopour hits et entrées. - Docker E2E : aligner Node/pnpm image ↔ hôte (Docker + Playwright Mac distant).
07 Trois formulations prêtes pour vos runbooks internes
À coller dans la doc interne.
- Règle lockfile : « Chaque fusion vers la branche principale inclut un
pnpm-lock.yamlà jour ; la CI n’exécute que des installations à lockfile gelé. » - Règle cache : « Toute variable qui modifie la sortie du compilateur doit être déclarée dans
turbo.json; une variable omise est un défaut de build. » - Règle miroir : « Tout changement de miroir impose un rafraîchissement du lockfile, une entrée de changelog et un
turbo run build --forcecomplet avant de réactiver les écritures de cache distant. »