【ITニュース解説】Monorepos: A Year in Review

モノレポとは、複数の独立したアプリケーションやライブラリのコードを、一つのリポジトリ（コードを保管する場所）で管理する開発手法のことである。今回、ある開発チームが、このモノレポへの移行を1年かけて行った経験について共有する。このチームは2人の少人数で構成されており、この規模だからこそ、意思決定を素早く行い、変更内容をチーム全体で常に把握し、様々な実装方法を試すことができた。

モノレポ化の目的は、主に三つあった。一つ目は、複数のアプリケーションが共通で使う部品（ライブラリやフレームワーク）の管理をシンプルにすることだ。二つ目は、同じような機能のコードをアプリケーションごとに何度も書く手間を省き、コードの重複を減らすこと。そして三つ目は、新しいアプリケーションや機能を追加する際に、既存の仕組みに簡単に組み込めるようにすることだった。

移行を進めるにあたり、重要な条件として、既存のアプリケーションに対する新機能の開発やバグの修正を中断できないという制約があった。そこでチームは、一度にすべてを移行するのではなく、一つずつ段階的にアプリケーションを移行するアプローチを選んだ。まず、比較的小規模なアプリケーションから移行を開始し、そこでモノレポの基本的な設定、つまり開発環境の構築、自動テストやデプロイの仕組み（パイプライン）、そして利用するツールの設定に習熟することを目指した。これにより、後から大規模なアプリケーションを移行する際にスムーズに進めることができた。ただし、移行中のアプリケーションに対しては、新機能開発を一時的に止めるというルールを設けた。これは、移行作業と並行して新機能開発を行うと、同じ変更を二重に行うリスクや、混乱が生じる可能性があったためだ。小さなバグ修正などは許可された。

モノレポ化を進める上で、数あるツールの中から「Nx」とその連携サービスである「Nx Cloud」を選定した。このツールを選んだ理由は、コマンドラインインターフェース（CLI）のドキュメントが豊富で、多くの例やチュートリアルが用意されており、学習のハードルが低かったからである。もしツールの使い方を理解できなければ、移行計画そのものが頓挫し、モノレポ導入の妥当性まで疑われかねないという危機感があった。Nxは既存の技術スタックに対応するプラグインも提供しており、Nx Cloudは移行を開始する前に、寛大な無料枠を利用して様々な実験を可能にした点も評価された。

移行の過程では、計画だけでは予測できない様々な課題に直面し、貴重な学びを得た。例えば、「Day.js」という日付ライブラリと「KendoReact」というUIコンポーネントライブラリの間で、日付のフォーマット（表示形式）が異なるために発生した不具合があった。Day.jsはISO形式（例: 年をYYYYと表記）を使うのに対し、KendoReactは独自の形式（例: 年をyyyyと表記）を期待していたため、表示が崩れてしまったのだ。この問題は、Day.jsには日付の計算や比較を担当させ、表示（フォーマット）はすべてKendoReactに任せるという役割分担をすることで解決し、一貫性を保つことができた。

また、認証機能として使っていた「React Keycloak」のライブラリが古く、ほとんどメンテナンスされていなかったため、独自のKeycloakラッパー（既存の機能を使いやすくする層）を自作することになった。この作業を通じて、トークンがどのように流れ、どのように更新されるのか、そしてReactアプリケーションがKeycloakとどのように連携するのかといった認証の仕組みを深く理解することができた。その結果、信頼性が高く、実際に利用されて問題がないことを確認できた認証ラッパーを手に入れ、チーム全体の認証メカニズムへの理解も深まった。

さらに、共有UIコンポーネントのリファクタリング（コードの改善）に着手した際、意図せず150以上のファイルに影響が及ぶ大規模な変更となってしまったことがあった。これはあまりにも巨大な変更であり、安全にレビューすることが不可能だと判断され、一度差し戻された。この経験から、大きな変更を一度に行うのではなく、小規模で集中的なプルリクエスト（コード変更の提案）に分割して進めることの重要性を学んだ。これにより、レビューが容易になり、リスクが減り、変更に対する信頼感が増した。一見効率的に見える「一括変更」よりも、管理された段階的なアプローチが最終的に成功につながるという教訓である。

もう一つ、今まであまり意識してこなかった「ドキュメント」の重要性も痛感した。チームの知識は主に個人の頭の中にあり、特に明文化してこなかった。しかし、外部のチームにNxワークスペースのレビューを依頼した際、初めて自分たちのシステムについて説明するために文書を作成する必要に迫られた。最初は単なる手間だと感じたが、実際に書くことで自分たちの設計意図が明確になり、これまでの思考の抜け穴を発見するきっかけにもなった。その結果、新しい開発者がチームに加わった際のオンボーディング（受け入れ教育）も、不可能ではないと感じるようになった。外部レビューのためだけに始まったドキュメント作成が、最終的には自分たちの思考を整理し、知識を共有するための強力なツールとなったのである。

すべてのコードをモノレポに移行する必要はないという判断基準も得られた。コードが「価値があり、頻繁に使われ、自分たちで管理できるものか」という問いが有効だ。 例えば、短命なコードやレガシーコード、つまり寿命が尽きたシステム、実証実験用のコード、プロトタイプなどは、移行に労力をかける価値が低い。また、影響の小さいツール、例えば管理者用のダッシュボードや、社内スクリプト、ごく少数の人々が使うユーティリティなどは、優先度を低く設定し、主要な移行目標が達成された後に改めて検討することも可能だ。非常に安定しており、性能が最適化されたモジュールについては、均一化のためだけに無理に移行を優先する必要はなく、変更が真に必要となるまで待つ方が賢明である。歴史的な記録や法的要件のためだけに保管されているアーカイブ済みのプロジェクトも、移行の対象外として良い。

モノレポへの移行は、主要な目標達成以外にも、いくつかの予期せぬ良い副次的効果をもたらした。 一つ目は、バージョン管理の問題がなくなったことだ。移行中はワークスペース全体の更新について深く考えていなかったが、アプリケーション間の移行の合間に、Nxの自動更新機能である「nx migrate」を使って、依存関係のバージョンをまとめて更新することができた。これは、複数のプロジェクトで異なるバージョンのライブラリを使うことによる混乱を避ける上で非常に効果的だった。 二つ目は、開発者体験が向上したことである。共有ライブラリの利用、信頼できる情報源の一元化、ユーティリティの統合により、知識の共有が容易になった。特定のコンポーネントやユーティリティを探す手間が減り、ローカルでの開発や新しい開発者のオンボーディングがより予測可能になった。 三つ目は、コードレビューの質が向上した点だ。共有モジュールは厳密にテストされているため、ユーティリティの実装について毎回詳細にレビューする必要がなくなった。これにより、コードレビューは機能の論理的な部分に集中できるようになり、以前の個別のリポジトリ（ポリレポ）運用時と比較して大きな改善となった。 そして四つ目は、チーム内の信頼が深まったことだ。当初、GitHubのブランチ保護ポリシーを適切に設定できていなかったが、それでもチーム内ではコードレビューを実践していた。これは、小規模で信頼し合えるチームだからこそ可能だったことであり、成長の余地があることも示している。

この1年間のモノレポ移行プロジェクトを通じて、いくつかの重要な教訓が得られた。 まず、「賢く始める」ことだ。本番環境のコードに手を付ける前に、多くのテスト用ワークスペースやパイプラインを構築して実験を繰り返した。この初期段階での実験が自信につながり、後からの予期せぬ問題を減らすことになった。同時に、どのアプリケーションやモジュールを移行対象とし、どこまでが自分たちの責任範囲かを明確に定めることで、作業を管理しやすい状態に保てた。Nxのジェネレーター（コード自動生成機能）を活用することで、後から構造を調整することも容易だったため、最初から完璧を目指す必要はなかった。

次に、「段階的に進める」ことだ。一つのアプリケーションを完全に移行するごとに、設定の検証やツールの改善を行うことができた。これにより、一つ一つの移行が大きなリスクではなく、学びの機会となった。最初の解決策がすべての例外に対応できるわけではないことも理解し、一時的な重複や簡易的な実装も許容しつつ、段階的に改善していく計画を立てることで、品質を損なうことなく作業の勢いを維持できた。

三つ目は、「実用性を保つ」ことである。すべてを抽象化し、ビルドプロセスを徹底的にカスタマイズし、完璧を目指そうとすると、過剰な設計に陥りがちだ。実際には、デフォルト設定を最大限に活用し、抽象化のバランスを取り、意図的なトレードオフを行うといった実用的な選択をすることが、プロジェクトの進行を早めた。一時的にコンポーネントを重複させる方が早い場合もあり、その場合はすべての利用ケースを理解した後にリファクタリングする計画を立てた。このような実用的な判断が、最終的に再利用可能なコードを生み出しつつ、開発速度を低下させなかった。

四つ目は、「随時ドキュメントを作成する」ことだ。前提条件、共有コンポーネント、ユーティリティ、開発規約などを文書化することで、思考が明確になり、新しい開発者のオンボーディングも改善された。最初は外部レビューのためだけの作業だと感じたが、すぐにチーム内部で意思決定を記録し、不足点を発見するためのツールへと変わっていった。良いドキュメントは他人だけのためではなく、自分たちのチームの明確な理解を深めるためにも役立つ。

五つ目は、「随時クリーンアップする」ことだ。予期せぬ問題、古くなった依存関係、忘れ去られたスクリプトなどが繰り返し見つかった。一つ一つの発見を、コードを整理し、標準化する機会と捉えた。これらの問題を早期に対処することで、後からのより大きな問題を防ぎ、コード全体の品質を向上させることができた。

最後に、「信頼を構築する」ことである。共有モジュールに対する厳密なテストは、非常に大きな時間節約につながった。堅牢なテストカバレッジ（テストで網羅されている範囲）があれば、ユーティリティの実装を毎回細かくレビューする必要がなくなり、アプリケーションのリファクタリングや更新をより安全に進められるようになった。テストはバグを見つけるだけでなく、共有コードとモノレポ移行全体に対する信頼を強化する役割も果たしたのである。

これらの教訓を総合すると、実用性、ドキュメント化、テストを優先した、思慮深く段階的なアプローチが、モノレポ移行を管理しやすく、教育的で、最終的に報われるものにしたことがわかる。

この1年を経て、モノレポは技術的な改善だけでなく、開発チームの働き方そのものを変革した。ここに至る道のりは決して単純ではなかった。各アプリケーションの移行には、慎重な計画、抽象化の再考、新しい要件や例外ケースの出現に応じた複数回の修正作業が含まれた。試行錯誤の瞬間はあったものの、それぞれの課題から貴重な学びが得られた。

現在、アプリケーション間のコードは一貫性を持ち、アップグレードは以前よりも簡単になり、共有されたレイアウト、ユーティリティ、ワークフローのおかげで新しいアプリケーションの立ち上げも迅速になった。自動テストとデプロイの仕組み（CI/CD）にはまだ改善の余地があり、オンボーディングもさらにスムーズにできるだろう。共有ライブラリも進化を続けるが、現在の基盤は非常に強固であり、日々の開発は以前よりも予測しやすく、エラーが少ないものになっている。

小規模チームにとっての教訓は明確だ。段階的な移行を受け入れ、完璧さよりも実用的なコードの再利用を優先し、Nxのようなツールを活用して実験を重ねることが重要である。モノレポは単なる技術的な変化ではなく、開発文化そのものの変革であり、そのための努力は十分報われたと言える。一つのリポジトリが、多くの学びと無限の可能性をもたらしたのだ。