TL;DR
- フロントエンドの表(AG Grid)が v21 と v33 の混在だったので、v36 に統一する移行を進めています
- 一気に上げず、v21 と v36 を同じアプリに並べて、画面ごとに移行・リリースする方式にしました
- 1画面ぶんの作業手順を型(ハーネス)にして、AI エージェント(Claude Code)でも人でも同じ品質で終わるようにしています
背景
状況
| 項目 | 内容 |
|---|---|
| 対象 | 営業支援 SaaS の Web フロントエンド(React 17 + TypeScript) |
| AG Grid の使用箇所 | 一覧・詳細・設定・レポートなど約40のグリッド、移行対象は約220ファイル |
| バージョン | 大半が v21(2019年リリース)、一部の画面だけ v33 |
| ライセンス | AG Grid Enterprise。今のライセンスで使える範囲に、最新版の 36.2.0(2026年9月リリース)が入っている |
課題
- 新しい機能を使えていない: Enterprise 版を使っているのに、6年以上前の版のままで、その間に増えた機能や改善をほとんど使えていなかった
- 2つの版の同居: v21 と v33 の CSS がぶつかるので、v33 の画面は「表示している間だけ CSS を読み込む」回避策で動かしていた。この回避策の保守も負担だった
- やりたいことができない: 親の一覧の行を開くと、その行に紐づく子の一覧が行の下に出る形(Master/Detail)にしたい。ところが親の一覧は v21、子の一覧は v33 で作られていて、版が違うので組み合わせられない
ゴール
- AG Grid を 36.2.0 に統一し、v21 / v33 の同居と CSS の回避策をなくす
-
ag-grid-react@36.2.0は React 16.8〜19 に対応しているので、React は上げなくてよい
難しさ
- 対象が約220ファイルと多く、一番大きい一覧は1画面で約1,700行ある
- 移行している間は v21 と v36 が同居するので、CSS がぶつからないようにする必要がある
- 移行後も、無限スクロール・並び替え・行選択・範囲選択とコピー・列設定の保存と復元・CSV 出力・グルーピングなどが、今までどおり動く必要がある
v21 と v36 の主な違い
名前を置き換えるだけで済むもの(抜粋)
| v21 | v36 |
|---|---|
columnApi.xxx() |
api.xxx()(columnApi が廃止) |
cellRendererFramework |
cellRenderer(コンポーネントを直接渡す) |
getRowNodeId: (data) => id |
getRowId: (params) => id |
api.setRowData(rows) |
api.setGridOption('rowData', rows) |
api.updateRowData(...) |
api.applyTransaction(...) |
purgeServerSideCache() |
refreshServerSide({ purge: true }) |
stopEditingWhenGridLosesFocus |
stopEditingWhenCellsLoseFocus |
suppressMenu |
suppressHeaderMenuButton |
セル編集部品はクラス(getGui / getValue) |
React コンポーネント(onValueChange / useGridCellEditor) |
置き換えるだけだと動きが変わるもの(ヘルパーで吸収)
| 対象 | そのまま置き換えると | 対応 |
|---|---|---|
列状態の適用(applyColumnState) |
保存した列順が戻らない | 並び順も当てるヘルパーを用意 |
列状態の取得(getColumnState) |
sort なども保存され、並び替えが二重に当たる |
v21 と同じ項目だけ取り出す |
列状態のリセット(resetColumnState) |
並び替えまで消え、一覧が空になる | 列の順・幅・表示・固定だけ戻す |
getSortModel / setSortModel
|
廃止 | 列状態から作るヘルパー |
イベント・設定の違い
| 対象 | v21 | v36 | 起きたこと |
|---|---|---|---|
列移動・幅変更のイベント source
|
どちらも uiColumnDragged
|
uiColumnMoved / uiColumnResized に分離 |
列の状態が保存されなくなる |
suppressSetColumnStateEvents |
あり | なし | API で列状態を当てただけで保存処理が走る |
infiniteInitialRowCount: 0 |
読み込まれる | 一度も読み込まれない | 一覧が空になる |
context |
後から変えた値も反映 | 初期化時の値だけ | 名称の変更などがセルに反映されない |
| HTML 文字列を返すセル部品 | HTML として描画 | 文字列がそのまま出る | タグが画面に出る |
| serverSide 行モデル |
getRowId は任意 |
実質必須 | 行選択が保てない |
| 範囲コピーの改行 | \n |
\r\n |
Excel 等への貼り付けは変わらないので許容 |
| 0件のとき | 何も出ない | 「表示する行がありません」 | v36 の挙動を採用 |
見た目(共通ラッパーで v21 に戻したもの)
| 対象 | v21 | v36 の既定 |
|---|---|---|
| 列の最小幅 | 10px | 28px |
| 見出しの文字 | 12px・システムフォント | 14px・ページのフォント |
| 行選択の色 | 単色の青 | 半透明の青(縞の行で色が変わる) |
| 範囲選択の色 | 透明度 0.3・区切り線なし | 透明度 0.2・区切り線あり |
| 行選択チェックボックス | セルの中央 | 左上に寄る |
| その場編集の入力欄 | 高さ 28px・灰色の枠 | 行の高さいっぱい・青い枠と影 |
数 px のずれで CSS では合わせられないもの(見出しの高さ +1px、固定列の下まで伸びる横スクロールバー など)は、理由と一緒に README に残して許容しています。
進め方
1. 基盤を先に作る(まだどの画面でも使わない)
v36 で画面を作るのに必要な部品を、先にまとめて用意するだけの段階です。この時点ではどの画面も v21 のままで、利用者から見える変化はありません。実際に v36 を使い始めるのは、次の「画面ごとに移行する」からです。
| 順番 | やったこと |
|---|---|
| 1 | TypeScript を 4.8 → 5.9 に上げる(v36 の型定義のため) |
| 2 | v36 を別名パッケージで導入し、v21 と同居させる |
| 3 | v21 と v36 の CSS がぶつからないよう、ビルド時に CSS の効く範囲を分ける(下で説明) |
| 4 | 共通ラッパー AgGridV36 を作り、既定値・見た目を v21 に寄せる |
| 5 | セル表示・セル編集・フィルタ・列定義の v36 版を複製して用意 |
「ビルド時に CSS の効く範囲を分ける」とは
AG Grid は v21 と v36 でクラス名(.ag-row など)が同じなので、そのまま同じページに置くと、お互いの CSS が当たって崩れます。そこで webpack で CSS を読み込むときに、AG Grid の CSS のセレクタすべてに条件を自動で足しています。
/* 元の CSS */
.ag-row { ... }
/* v36 の CSS: .ag-theme-v36 の中だけで効く */
.ag-row:where(.ag-theme-v36, .ag-theme-v36 *) { ... }
/* v21 の CSS: .ag-theme-v36 の外だけで効く */
.ag-row:not(:where(.ag-theme-v36, .ag-theme-v36 *)) { ... }
-
:where()で包んでいるので詳細度は変わらず、今ある上書き用の CSS の効き方も変わらない - アイコンフォントも名前が同じなので、v36 側はフォント名に
-v36を付けて分ける - ライブラリ本体には手を入れず、ビルドのたびに変換する
これで「v21 の画面と v36 の画面が混ざったまま」リリースできるようになりました。
2. 画面ごとに移行する(ここから v36 を使う)
- 1画面=1カード=1PR。最初に移した一覧で上の対応表を作り、以降は表を引いて進める
- 利用者が多い・TOP に出る画面は 旧版を残して切り替えフラグで戻せるようにする
- 新しく見つけた差分は、毎回 README の対応表に追記する
3. 1画面の作業を型にする(ハーネス)
各ステップに「通過条件」を置き、通らなければ次へ進まないようにしています。
- 調べる: v21 API の使用箇所を洗い出し、対応表で「表で済む/ヘルパーを使う/挙動差/新しいもの」に仕分ける
- 実装: v36 版を作る。一時的なコードには決まった目印の TODO を付ける(typecheck・lint が通るまで)
- ユニットテスト: 書き換えたロジックを関数に切り出してテストする
- 画面E2E: Playwright で、全一覧に共通の15項目と、その画面だけの操作を全部テストする。先に画面の機能を棚卸しして表にし、全部の行にテストを割り当てる
- v21 と比べる: 不具合っぽいものは、v21 に戻して同じ手順で確かめる。差分は「直した」か「理由付きで README に書いた」のどちらかにする
- 知見を戻す: README・E2E・学びのノートに追記し、次の人が README だけで同じ罠を踏まないようにする
4. 最後に v21 を消す(一本化)
全部の画面が v36 に移ったら、移行のために残していたものをまとめて消します(予定)。
-
消すもの
- v21 / v33 のパッケージ
- v36 版を作るときの複製元(v21 用のセル部品・列定義・共通フックなど)
- 高リスク画面の v21 版と切り替えフラグ
- CSS の効く範囲を分けるビルドの仕組みと、v33 の「表示している間だけ CSS を読み込む」回避策
-
消し忘れを防ぐ工夫
- 移行中に入れた一時的なコードには、すべて同じ文言の目印
TODO: v21を削除するときに…を付けておき、grep 1回で全部見つけられるようにしている - 切り替えフラグを置いた画面は、フラグのファイルに「いつ・何を・どの順で消すか」を書いておく
- 共通ラッパーの先頭に、消す対象の複製元の一覧を置いておく
- 移行中に入れた一時的なコードには、すべて同じ文言の目印
-
注意すること
- 複製元のうち、v21 に依存していない定数や部品は v36 版からも読まれているので、消さずに v36 側へ移す
この進め方にした理由
- 画面ごとに小さく出す: 約220ファイルを一度に変えると、レビューも不具合の切り分けも難しい。問題が出ても影響は1画面で済む
- 既存部品は触らず複製: まだ移していない画面を壊さない。v21 は最後にまとめて消す
- 高リスク画面は切り替えフラグ: 本番で問題が出ても、コードを戻さずに v21 へ戻せる
参考にした考え方
- Strangler Fig: 新しいものを古いものの横で育て、少しずつ置き換える Martin Fowler - StranglerFigApplication
- Branch by Abstraction: 抽象(今回は共通ラッパーと切り替え部品)を挟み、裏の実装を段階的に差し替える Martin Fowler - BranchByAbstraction
- Parallel Change(expand / migrate / contract): 新旧を並べて(expand)、移し(migrate)、最後に古い方を消す(contract) Martin Fowler - ParallelChange
今回の流れは Parallel Change そのもので、「基盤を先に作る=expand」「画面ごとに移行=migrate」「最後に v21 を消す=contract」に対応しています。
ハマったこと
-
型エラーにならない違いが多い: 列状態やイベントの
sourceの違いは、typecheck もユニットテストも通ってしまい、画面で触って初めて気づく - v36 の不具合だと思ったら、v21 でも同じだった: まず v21 で同じ手順を試すようにした。v21 から引き継いだバグも少なくなかった
-
見た目の比較: スクリーンショットを見比べるより、
getComputedStyleの数値を比べるほうが確実だった
E2E は Claude in Chrome と Playwright を試して、Playwright にした
最初は AI がブラウザを操作する Claude in Chrome で画面を確認していましたが、途中から Playwright のテストに切り替えました。
| Playwright | Claude in Chrome | |
|---|---|---|
| 準備 | 最初にテストのコードを書く必要がある | すぐに始められる |
| 速さ | 決まった手順なら、ブラウザ操作の何倍も速い | 1つずつ画面を見ながら操作するので遅い |
| 再現性 | 毎回同じ手順で確かめる | 毎回同じようにテストしてくれるとは限らない |
| 向いている場面 | 移行のように、同じ確認を画面ごとに何度も流すとき | 小さなバグ修正を手早く確かめたいとき、画面の作りを調べるとき |
移行では「同じ確認を画面の数だけ、何度も流す」ので、最初にコードを書く手間を払っても Playwright のほうが得でした。
注意: この記事は、私たちのプロジェクトで移行したときに確かめた範囲の内容です。誤りや、バージョンによる違いがあるかもしれません。実際に移行するときは、AG Grid 公式のドキュメント(各バージョンの移行ガイドや API リファレンス)もあわせて確認してください。
Top comments (0)