SaaS Factoryモノレポ運用記 — pnpmとTurboで複数サービスを束ねる

SaaS Factory モノレポ運用記 — pnpmとTurboで複数サービスを束ねる

「たった一つのボタンの色を変更するために、なぜ5つの別々のリポジトリを開いて、3時間も無駄にしなければならないのか？」これは1年前、私が複数のマイクロSaaSを個別のマルチレポで管理していた時に発した、怒りの独り言です。現在、私たちのGRAXELプラットフォームは12以上のサービスを単一のモノレポ（Monorepo）で運用しています。pnpmとTurborepoを駆使して、1人開発者がいかにして巨大なコードベースを飼い慣らしているのかをお話しします。

pnpm workspacesによる「真実の源」の確立

複数のサービス間で、認証ロジックやUIコンポーネントをコピー＆ペーストするのは技術的負債の温床です。私はpnpm workspacesを採用し、packages/uiやpackages/authといった共通パッケージをローカルでリンクする方式（workspace:*）に切り替えました。これにより、共通パッケージのコードを修正した瞬間、それに依存するすべてのNext.jsアプリが即座にホットリロードされるという、極めてシームレスな開発体験を手に入れました。ローカルでのパッケージの公開（publish）作業は一切不要です。

Turborepoがもたらしたビルド時間の革命

サービスが増えるにつれ、CI/CDのビルド時間が深刻な問題になりました。最初はGithub Actionsでの全ビルドに20分近くかかっていました。そこでTurborepoの出番です。依存関係グラフに基づいた並列実行と、強力なローカル＆リモートキャッシュのおかげで、変更がないパッケージはビルドをスキップできるようになりました。結果として、現在では平均ビルド時間がわずか2分にまで短縮されています。この20分から2分への短縮は、1日あたり数十回のデプロイを行う私にとって、文字通り「命を救う」改善でした。

地獄を見た失敗談：React 18と19の衝突

しかし、モノレポには特有の「罠」が潜んでいます。最も恐ろしかった失敗は、特定のサービスだけを実験的にReact 19にアップグレードしようとした時のことです。共通のpackages/uiはReact 18をpeerDependenciesとして指定していました。

ローカル環境では動いていたものの、本番ビルドの過程でパッケージマネージャーが混乱し、本番環境で「Reactのフックが2回呼び出される」という原因不明の深刻なバグが発生しました。ユーザーのセッションが突然切断される事態となり、数時間のダウンタイムを引き起こしました。原因を突き止めるため深夜までログと格闘し、最終的にルートのpackage.jsonでresolutionsフィールドを用いてバージョンの強制固定を行うことで、ようやく事態を収拾しました。モノレポにおいては、依存関係のバージョン管理（特にReactのようなコアライブラリ）のわずかなズレが、エコシステム全体を崩壊させるリスクがあることを痛感しました。

1人開発者にとってモノレポは正解か？

「モノレポはGoogleのような大企業向けのもので、個人開発者にはオーバースペックだ」という意見をよく耳にします。しかし私の経験上、それは半分間違っています。共通基盤を一度構築してしまえば、新しいSaaSのプロトタイプを立ち上げるのに必要な時間は、わずか1〜2日に短縮されます。12のサービスを同時に運用できているのは、間違いなくこのアーキテクチャのおかげです。私たちのプラットフォームの全体像についてはGRAXELについてで詳しく解説しています。

もちろん、設定の複雑さや、1つのエラーが全体に波及するリスクは常に伴います。もし似たような構成で悩んでいる方がいらっしゃれば、ぜひコンタクトページからメッセージを送ってください。喜んで私の知見をシェアさせていただきます。