大規模プロダクト × MUI v5 の破壊的アップデートから得た進行の知見

2025.10.8

実践と知見

こんにちは、Gaji−Labo フロントエンドエンジニアの上條です。

先日弊社が参画しているプロジェクトで進行していた MUI v4 から v5 へのアップデートがリリースされました。2025年10月時点で MUI の latest は v7.3.4。今更 v5 へのアップデートかという声が聞こえてきそうですが、MUI は v5 で破壊的な変更があり単純にバージョンを上げるだけではうまくいかないのです（つらい）。
プロダクトの規模も大きいため複数の機能開発と並行している分時間もかかりましたが、結果的に機能開発を妨げることなく無事に完遂できました。

そんな一筋縄ではいかなかった「大規模プロダクト × ライブラリの破壊的アップデート」ですが、そこから得た進行の知見もたくさんありました。実際にやったこととその結果をざっと振り返ってみます。

アップデート作業の進行方法

v5 アップデートの作業は以下のように進行しました。

作業範囲は1ページ（pages 配下のディレクトリ）ごと
- そのページで使われているコンポーネントも含めて作業するため作業ファイルは約50個
作業を全て集約する feature ブランチを作成し、そこから作業ブランチを切る
- 作業ブランチでのレビューが完了したら feature ブランチにマージ
- ※ v4 と v5 は共存できないため全てのコードを v5 に対応してからリリースする必要があった
定期的に master を feature ブランチに取り込む
- コンフリクトが発生していれば解消
- 新規開発によって v5 に対応されていないものは追加で作業

前提としてプロダクトの機能開発が優先であることと、デザインが MUI をベースにかなりカスタマイズされているため破壊的変更の影響が大きく、結果的にリリースまで1年以上かかりました。破壊的な変更の具体を知りたい方は MUI v4 のプロジェクトを段階的に v5 に上げてみるをご覧ください。

うまくいったこと

進行が円滑になった取り組みは主に3点です。

作業完了の時期を決める

リファクタリング系の作業は機能開発と比べて後回しになりがちで、その結果いつまでも作業が進まない、マージできないといった悩みを抱えていました。
チーム内で話し合う中で期日を決めていないことが後回しになる原因ではないかと考え、優先度と作業完了時期の目安を取り決めました。時期的に GW が近かったため、そこに向けて区切りをつけようとチーム内で温度感をすり合わせていた記憶があります。
後回しになりがちなリファクタリング作業こそしっかり期日を決めて作業することで比較的スムーズになるのではないかと思います。

コンフリクトしそうなものはマージのタイミングをずらす

master 取り込みによって並行して動いていた機能開発と作業範囲が被ってしまい、コンフリクトを起こすことが多々ありました。場合によってはコンフリクトだけでなく作業に手戻りが発生するため、機能開発は優先しつつ優先度が低いタスクはアップデート後に対応するよう調整しました。
作業内容的に影響範囲が広くコンフリクト解消の作業自体が重いため、回避することでメンバーのモチベーション低下や心理的な負担を軽減する働きもあったように思います。

誰でも Issue を作成できるようにする

作業後に改めて見返すと対応できていない箇所を見つけることがあります。そのような作業漏れを取りこぼさないために細かいことでも GitHub Issue に起こし、手が空いた人が誰でも対応できるようにしました。また Issue はテンプレートを用意することで誰でも情報の過不足なく作成でき、その結果 Issue 起票に関する属人化も防げました。

反省点

作業を進めるにあたってボトルネックとなったのは大きく2点です。

作業ボリュームとレビューコストが大きかった

「うまくいったこと」で「期日を決めていないことが後回しになる原因ではないか」と書きましたが、原因はそれだけではないと思っています。期日以外の要因で考えられるのは作業ボリュームの大きさとレビューコストの高さです。
作業ボリュームが大きいと単純に作業完了までに時間がかかり、レビューコストが大きいと確認する箇所が多くどうしても腰が重たくなりますし、見るにも気力が要ります。そして一部にレビューが入ると問題ないコードもレビューが完了するまでマージできません。結果なかなかマージできず全体の作業完了まで時間がかかった印象です。
なるべく作業範囲を絞ってマージ可能なものはどんどんマージできるような運用ができたらよかったなと思っています。

目視でのレビューによってコストが増える

当プロジェクトではスタイルメインの作業は Chrome DevTool で出力されているスタイルと Figma を比べて目視でレビューしており、この運用が上記のレビューコストにも繋がっています。今のプロジェクトの規模感を考えるとコンポーネントテストなど何かしらの手を打つべき時が来たと感じます。

MUI v5 アップデートの次は？

v5 へのアップデートは終わりではなくむしろやっとスタートラインに立ったところと言えます。反省点を活かして v6, v7 へのアップデート作業が絶賛進行中なので、その話はまた別の機会にできればと思います。
そして現在は AI で作業の効率化が図れる時代です。Gaji-Labo では AI のより良い活かし方を会社全体で検証しており、それらの知見をもとに作業負荷を軽減できる方法を模索しています。興味のある方はぜひ AIタグの記事一覧をご覧ください。