18 hónap pnpm monorepo — a jó, a rossz, és a migrációs sztori
Két Nortinia repo fut pnpm monorepo-ként. Elmondjuk, mit tanultunk a 18 hónap alatt — és mikor ne válaszd ezt a setupot.
A monorepo nem "jobb vagy rosszabb". Attól függ, mennyire akarsz egyszerre változtatni két kódbázist.
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.