TL;DR
- Our frontend grids (AG Grid) were a mix of v21 and v33, so we are migrating everything to v36
- Instead of upgrading all at once, we run v21 and v36 side by side in the same app and migrate and release screen by screen
- We turned the per-screen workflow into a fixed template (a "harness"), so an AI agent (Claude Code) or a human gets the same quality every time
Background
Where we started
| Item | Details |
|---|---|
| Target | Web frontend of a sales-support SaaS (React 17 + TypeScript) |
| AG Grid usage | About 40 grids across lists, detail pages, settings, and reports; about 220 files to migrate |
| Versions | Mostly v21 (released 2019), with v33 on a few screens |
| License | AG Grid Enterprise. Our current license covers the latest release, 36.2.0 (released September 2026) |
Problems
- Not using newer features: Although we use the Enterprise edition, we were on a version more than six years old and missed most of the features and improvements added since then
- Two versions living together: The v21 and v33 stylesheets conflict, so the v33 screens relied on a workaround that loads their CSS only while they are displayed. Maintaining that workaround was a burden
- Blocked on a feature we wanted: We want to expand a row in a parent list to show its related child list directly beneath it (Master/Detail). But the parent list was built on v21 and the child list on v33, and different versions can't be combined
- Reference: AG Grid - Master / Detail
Goals
- Standardize on AG Grid 36.2.0 and remove both the v21/v33 coexistence and the CSS workaround
-
ag-grid-react@36.2.0supports React 16.8–19, so no React upgrade is needed
What makes it hard
- About 220 files are affected, and the largest list is about 1,700 lines on its own
- v21 and v36 coexist during the migration, so their CSS must not conflict
- After migrating, infinite scrolling, sorting, row selection, range selection and copy, saving and restoring column settings, CSV export, grouping, and so on must all keep working as before
Main differences between v21 and v36
Simple renames (excerpt)
| v21 | v36 |
|---|---|
columnApi.xxx() | api.xxx() (columnApi was removed) |
cellRendererFramework | cellRenderer (pass the component directly) |
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 |
Cell editors as classes (getGui / getValue) | React components (onValueChange / useGridCellEditor) |
Renames that change behavior (handled with helpers)
| Target | If you just rename it | What our helper does |
|---|---|---|
Applying column state (applyColumnState) | Saved column order is not restored | Applies the column order as well |
Getting column state (getColumnState) | sort and other fields get saved, so sorting is applied twice | Keeps only the fields v21 had |
Resetting column state (resetColumnState) | Sorting is cleared too, and the list goes empty | Resets only column order, width, visibility, and pinning |
getSortModel / setSortModel | Removed | Builds the sort model from the column state |
Event and option differences
| Target | v21 | v36 | What happened |
|---|---|---|---|
Event source for column move / resize | Both uiColumnDragged | Split into uiColumnMoved / uiColumnResized | Column state stopped being saved |
suppressSetColumnStateEvents | Available | Removed | Applying column state through the API triggers our save logic |
infiniteInitialRowCount: 0 | Rows load | Rows never load | The list stays empty |
context | Later changes are reflected | Only the initial value is used | Updated values such as names don't reach the cells |
| Cell renderers returning HTML strings | Rendered as HTML | Shown as plain text | Raw tags appear on screen |
| Server-side row model | getRowId optional | Effectively required | Row selection is not kept |
| Line breaks in range copy | \n | \r\n | Accepted, since pasting into Excel and similar tools works the same |
| Zero results | Nothing shown | "No Rows To Show" overlay | Kept the v36 behavior |
Visuals (restored to v21 in our shared wrapper)
| Target | v21 | v36 default |
|---|---|---|
| Minimum column width | 10px | 28px |
| Header text | 12px, system font | 14px, page font |
| Selected row color | Solid blue | Translucent blue (looks different on striped rows) |
| Range selection color | Opacity 0.3, no inner borders | Opacity 0.2, with inner borders |
| Row selection checkbox | Centered in the cell | Pushed to the top left |
| Inline edit input | 28px tall, gray border | Full row height, blue border and shadow |
Differences of a few pixels that CSS can't fix (such as a header that is 1px taller, or a horizontal scrollbar that now extends under pinned columns) are documented in our README with the reason, and accepted.
How we proceeded
1. Build the foundation first (not used by any screen yet)
In this phase we only prepare the parts needed to build screens on v36. Every screen still runs on v21, so users see no change. We actually start using v36 in the next phase, "Migrate screen by screen".
| Step | What we did |
|---|---|
| 1 | Upgrade TypeScript from 4.8 to 5.9 (required by v36's type definitions) |
| 2 | Install v36 under aliased package names so it can coexist with v21 |
| 3 | Scope the CSS at build time so v21 and v36 styles don't conflict (explained below) |
| 4 | Build a shared wrapper, AgGridV36, with defaults and visuals aligned to v21 |
| 5 | Create v36 versions of the cell renderers, cell editors, filters, and column definitions by duplicating the originals |
What "scope the CSS at build time" means
v21 and v36 use the same class names (such as .ag-row), so putting both on the same page makes each version's CSS hit the other's grid. To prevent that, when webpack loads AG Grid's CSS, we automatically add a condition to every selector.
/* Original CSS */ .ag-row { ... } /* v36 CSS: applies only inside .ag-theme-v36 */ .ag-row:where(.ag-theme-v36, .ag-theme-v36 *) { ... } /* v21 CSS: applies only outside .ag-theme-v36 */ .ag-row:not(:where(.ag-theme-v36, .ag-theme-v36 *)) { ... } - Wrapping the condition in
:where()keeps specificity unchanged, so our existing override styles behave the same - The icon fonts also share a name, so the v36 font gets a
-v36suffix - The library itself is left untouched; the CSS is transformed on every build
This lets us ship releases where v21 and v36 screens are mixed.
2. Migrate screen by screen (this is where v36 goes live)
- One screen = one ticket = one PR. The first list we migrated produced the mapping tables above, and later screens just look things up in them
- Screens with many users or shown on the home screen keep the old version behind a feature flag so we can switch back
- Every newly found difference is added to the mapping tables in the README
3. Turn the per-screen workflow into a template (harness)
Each step has a gate, and we don't move on until it passes.
- Investigate: List where the screen uses v21 APIs, then sort each use into "covered by the table / uses a helper / behavior difference / new"
- Implement: Build the v36 version. Mark temporary code with a fixed TODO marker (done when typecheck and lint pass)
- Unit tests: Extract the rewritten logic into functions and test them
- Screen E2E: Use Playwright to test the 15 checks shared by every list plus every operation specific to that screen. First inventory the screen's features in a table, then assign a test to every row
- Compare with v21: When something looks like a bug, switch back to v21 and repeat the same steps. Every difference is either "fixed" or "documented in the README with a reason"
- Feed knowledge back: Update the README, the E2E tests, and our notes so the next person avoids the same traps just by reading the README
4. Remove v21 at the end (consolidation)
Once every screen is on v36, we will remove everything we kept around for the migration (planned).
- What gets removed
- The v21 / v33 packages
- The originals we duplicated for v36 (v21 cell components, column definitions, shared hooks, and so on)
- The v21 versions of high-risk screens and their feature flags
- The build-time CSS scoping, and v33's "load CSS only while displayed" workaround
- How we avoid missing anything
- All temporary code added during the migration carries the same marker comment (
TODO: when removing v21…), so a single grep finds all of it - For screens with a feature flag, the flag file states when, what, and in which order to remove things
- The top of the shared wrapper lists the duplicated originals to delete
- All temporary code added during the migration carries the same marker comment (
- Watch out for
- Some originals (constants and components that don't depend on v21) are also imported by the v36 versions. Move them to the v36 side instead of deleting them
Why we chose this approach
- Ship in small pieces, one screen at a time: Changing about 220 files at once makes review and debugging hard. If something breaks, only one screen is affected
- Duplicate instead of modifying existing parts: Screens not yet migrated stay safe. v21 is removed all at once at the end
- Feature flags for high-risk screens: If a problem shows up in production, we can switch back to v21 without reverting code
Ideas we drew on
- Strangler Fig: Grow the new system alongside the old one and replace it gradually Martin Fowler - StranglerFigApplication
- Branch by Abstraction: Put an abstraction in between (here, the shared wrapper and the switch components) and swap the implementation behind it step by step Martin Fowler - BranchByAbstraction
- Parallel Change (expand / migrate / contract): Run old and new side by side (expand), move over (migrate), then remove the old one (contract) Martin Fowler - ParallelChange
Our process follows Parallel Change directly: "build the foundation first" is expand, "migrate screen by screen" is migrate, and "remove v21 at the end" is contract.
Pitfalls
- Many differences don't cause type errors: Differences in column state or event
sourcepass both typecheck and unit tests, and only show up when you use the screen - "v36 bug" that turned out to be the same in v21: We now always repeat the steps on v21 first. Quite a few bugs had been carried over from v21
- Comparing visuals: Comparing
getComputedStylevalues was more reliable than comparing screenshots
For E2E we tried both Claude in Chrome and Playwright, and chose Playwright
At first we checked screens with Claude in Chrome, where an AI operates the browser, but partway through we switched to Playwright tests.
| Playwright | Claude in Chrome | |
|---|---|---|
| Setup | You have to write test code first | You can start right away |
| Speed | For a fixed set of steps, many times faster than driving the browser | Slow, since it looks at the screen and acts one step at a time |
| Repeatability | Runs exactly the same steps every time | Doesn't always test the same way each time |
| Best for | Running the same checks over and over across many screens, as in a migration | Quick checks after a small bug fix, or exploring how a screen is built |
A migration means running the same checks many times for every screen, so Playwright paid off even after the upfront cost of writing the code.
Note: This article covers only what we verified while migrating our own project. It may contain mistakes or details that differ between versions. When you migrate, please also check the official AG Grid documentation (the upgrade guide for each version and the API reference).


