18 hónap pnpm monorepo — a jó, a rossz, és a migrációs sztori

A Nortinia két repo-ja, a netorigo-app-finance és a netorigo-app-logistics, pnpm workspace-alapú monorepo-ként fut. Két package-et tartalmaznak: packages/api (NestJS) és packages/web (Next.js). 18 hónap éles futás után a mérleg nem az, amit a Reddit-es viták alapján várnál.

Ami működik

• API + web egy PR-ben cserélhető — egyetlen atomi commit
• Shared TypeScript típusok a packages/shared-ból, valós idejű refactor
• Egy pnpm-lock.yaml, konzisztens dependency tree
• CI egyszerre futtatja mindkét package tesztjeit
• Deploy egyszerre történik, nincs "API deployolva, web még nincs" ablak

Ami fáj

• ESLint 9 a rootban külön config-ot kér — a packages/api config-ja nem öröklődik
• A Jest + TypeORM kombó ritka módon keveredik a workspace hoisting-gal
• A Dockerfile bonyolultabb: kell pnpm fetch és pnpm deploy step
• A CI cache gyakran hiányzik, mert a lockfile változása minden package-et érint
• Új csapattag első napja lassabb: "miért van itt két package.json?"

Mikor ne válaszd

Ha az API és a web külön csapaté, külön deploy pipeline-on, külön release cadence-szel — ne válassz monorepo-t. A shared típusok ígérete nem éri meg a CI bonyolódást. Nálunk azért jó, mert ugyanaz a csapat írja mindkettőt, és minden feature egy PR-be kerül. Ez a Netorigo stack alapfeltételezése.

És ha mégis váltani akarsz egy meglévő kétrepo setupból monorepo-ra: tervezz 2 hetet és ne húzd a deploy pipeline átírását utolsónak. A mi migrációnk 9 napig tartott, és a 9. napon a deploy pipeline volt az, amire még egy full nap kellett.

A CI sarok esetek, amiket nem mondanak el

• A GitHub Actions cache kulcs a pnpm-lock.yaml hash-én alapul — egy apró patch verzió váltás teljes rebuilt kényszerít
• A pnpm fetch + pnpm install --offline sorrendet pontosan kell betartani, különben megduplázódik a letöltés
• A Jest ESM kompatibilitás workspace hoisting-gal kombinálva időnként transformIgnorePatterns-t kér
• A husky + lint-staged a root-ban fut, de a TypeScript csak a megfelelő packages/<x>-ban tud resolve-olni
• A Docker layer cache csak akkor működik, ha a pnpm store-ot külön COPY lépésben hozod be

Sok csapat a Turborepo vagy az Nx felé menne a pnpm workspace helyett. Ezek jobbak, amikor 5+ package van, vagy amikor az incremental build a kritikus tényező. Kettő package-nél a pnpm workspace + szimpla pnpm script-ek bőven elegendőek. A Nortinia-nál is csak akkor fontolnánk meg a váltást, ha a Netorigo stack egyszer átlépi a 4-5 package határt — addig a "boring technology" elv érvényes.