DEV Community

Kaziu
Kaziu

Posted on

AG Grid を v21 から v36 へ。15 メジャー飛ばしを「画面ごと」に進めた話

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 *)) { ... }
Enter fullscreen mode Exit fullscreen mode
  • :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 へ戻せる

参考にした考え方

今回の流れは 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)