18 ay pnpm monorepo — iyi, kötü ve geçiş hikâyesi

İki Nortinia reposu — netorigo-app-finance ve netorigo-app-logistics — pnpm workspace monorepo olarak çalışıyor. Her biri iki paket içeriyor: packages/api (NestJS) ve packages/web (Next.js). Canlı ortamda 18 ayın ardından bilanço, Reddit tartışmalarının düşündüreceğinden biraz farklı.

İşe yarayanlar

• API + web değişikliği tek PR'da — tek bir atomik commit
• packages/shared'den ortak TypeScript tipleri, canlı olarak yeniden düzenlenebilir
• Tek pnpm-lock.yaml, tutarlı bir bağımlılık ağacı
• CI her iki paketin test takımlarını paralel çalıştırır
• Yayınlar birlikte yapılır, “API çıktı, web geride kaldı” boşluğu olmaz

Can sıkanlar

• ESLint 9 kökte bir yapılandırma ister — packages/api yapılandırması yukarı doğru aktarılmaz
• Jest + TypeORM ikilisi zaman zaman workspace hoisting ile çakışır
• Dockerfile daha karmaşıktır: pnpm fetch ve pnpm deploy adımlarına ihtiyaç vardır
• Lockfile değişikliği tüm paketlere dokunduğu için CI önbelleği sık sık ıskalar
• Yeni ekip arkadaşlarının uyumu daha yavaştır: “Neden iki package.json dosyası var?”

Ne zaman SEÇMEMELİ

API ve web, farklı yayın süreçleri ve sürüm ritimleri olan farklı ekiplere aitse monorepo seçmeyin. Ortak tip vaadi CI karmaşıklığına değmez. Bizde işe yarıyor çünkü ikisini de aynı ekip yazıyor ve her özellik tek bir PR'da geliyor. Netorigo altyapısının temel çizgisi budur.

Yine de iki ayrı repodan monorepoya geçmek istiyorsanız: 2 hafta planlayın ve yayın sürecini sona bırakmayın. Bizim geçişimiz 9 gün sürdü ve 9. günde yayın süreci hâlâ tam bir gün daha gerektiriyordu.

Kimsenin size söylemediği CI uç durumları

• GitHub Actions önbellek anahtarı pnpm-lock.yaml hash'ine bağlıdır — küçük bir yama sürümü artışı tam yeniden derlemeye zorlar
• pnpm fetch + pnpm install --offline sırası tam olarak doğru olmalı, aksi halde indirmeler iki katına çıkar
• Jest ESM uyumluluğu workspace hoisting ile birleşince zaman zaman transformIgnorePatterns gerektirir
• husky + lint-staged kökte çalışır, ancak TypeScript yalnızca her packages/<x> içinde çözümlenir
• Docker katman önbelleği yalnızca pnpm store'u ayrı bir adımda COPY ederseniz çalışır

Birçok ekip pnpm workspace yerine Turborepo veya Nx'e yönelir. Bunlar 5'ten fazla paketiniz olduğunda ya da artımlı derlemeler kritik olduğunda daha iyidir. İki paketle pnpm workspace + düz pnpm betikleri fazlasıyla yeterlidir. Nortinia'da bu kararı ancak Netorigo altyapısı 4-5 paket sınırını aşarsa yeniden değerlendiririz — o zamana kadar “sıkıcı teknoloji” ilkesi geçerlidir.