[question] Migration guidance for monolithic app: MUI X v6 → v7 → v8

[AmandaCarvalho1989]

The problem in depth

Hello!

We maintain a large monolithic application that currently uses MUI X Data Grid Premium v6, and we are planning to migrate to v7, and later to v8.

Because of the size of the application, migrating everything at the same time is not very practical for us. We are therefore looking for ways to migrate gradually, while keeping the application running.

I was wondering whether keeping two major versions side by side during the migration would be possible, but we are not sure if this is supported or recommended.

Is there any way to do this in phases, or does the migration need to be done all at once?

Any guidance, best practices, or recommendations would be greatly appreciated.

Your environment

`npx @mui/envinfo`

  System:
    OS: Linux 6.5 Ubuntu 22.04.5 LTS 22.04.5 LTS (Jammy Jellyfish)
  Binaries:
    Node: 20.17.0 
    npm: 10.8.2 
    pnpm: Not Found
  Browsers:
    Chrome: 142.0.7444.59
    Firefox: 146.0
  npmPackages:
    @emotion/react: ^11.9.3 => 11.14.0 
    @emotion/styled: ^11.9.3 => 11.14.1 
    @mui/base:  5.0.0-alpha.91 
    @mui/core-downloads-tracker:  5.18.0 
    @mui/lab: 5.0.0-alpha.92 => 5.0.0-alpha.92 
    @mui/material: ^5.15.14 => 5.18.0 
    @mui/private-theming:  5.17.1 
    @mui/styled-engine:  5.18.0 
    @mui/styles: ^5.15.14 => 5.18.0 
    @mui/system:  5.18.0 
    @mui/types: ^7.1.5 => 7.4.9 
    @mui/utils:  5.17.1 
    @mui/x-charts:  7.29.1 
    @mui/x-charts-pro: ^7.27.0 => 7.29.1 
    @mui/x-charts-vendor:  7.20.0 
    @mui/x-data-grid:  6.20.4 
    @mui/x-data-grid-premium: ^6.18.0 => 6.20.5 (7.29.12)
    @mui/x-data-grid-pro:  6.20.4 
    @mui/x-date-pickers:  8.22.0 
    @mui/x-date-pickers-pro: ^8.14.1 => 8.22.0 
    @mui/x-internals:  7.29.0 
    @mui/x-license: ^7.0.0 => 7.29.1 
    @mui/x-license-pro:  6.10.2 
    @mui/x-telemetry:  8.19.0 
    @mui/x-tree-view: 6.17.0 => 6.17.0 
    @types/react: ^17.0.38 => 17.0.90 
    react: 17.0.2 => 17.0.2 
    react-dom: 17.0.2 => 17.0.2 
    styled-components: ^5.3.0 => 5.3.11 
    typescript: ^4.5.4 => 4.9.5 

Search keywords: datagrid, migration

Order ID: 121279

[MBilalShafi]

Hey @AmandaCarvalho1989,

Thanks for the detailed context, this is a very common situation for large monolithic applications, and your concern makes sense.

Running two major versions of MUI X side by side in the same application is not something we officially support or recommend, as each major version has internal context, styling mechanisms, and global setup, which makes mixing them in one React tree risky and prone to issues.

In general, the most predictable and supportable path is to upgrade one major version at a time, keep only a single version loaded, and migrate behavior gradually within that version. The codemods and migration guides are designed to help you get to a compiling state quickly and reduce the amount of manual, straightforward changes.

For large codebases, it often helps if Data Grid usage is wrapped in shared containers or abstractions. In that case, most of the migration work can usually be limited to those shared layers rather than touching every individual grid instance.

Here are the migration guides for v7 and v8 for reference:

v7:

Data Grid: https://mui.com/x/migration/migration-data-grid-v6/
Pickers: https://mui.com/x/migration/migration-pickers-v6/
Charts: https://mui.com/x/migration/migration-charts-v6/
Tree View: https://mui.com/x/migration/migration-tree-view-v6/

v8:

Data Grid: https://mui.com/x/migration/migration-data-grid-v7/
Pickers: https://mui.com/x/migration/migration-pickers-v7/
Charts: https://mui.com/x/migration/migration-charts-v7/
Tree View: https://mui.com/x/migration/migration-tree-view-v7/

Let me know if you have further questions.

[AmandaCarvalho1989]

Hello!

Running two major versions of MUI X side by side in the same application is not something we officially support or recommend, as each major version has internal context, styling mechanisms, and global setup, which makes mixing them in one React tree risky and prone to issues.

Okay! That's what I thought! Thanks for clarifying!

In general, the most predictable and supportable path is to upgrade one major version at a time, keep only a single version loaded, and migrate behavior gradually within that version. The codemods and migration guides are designed to help you get to a compiling state quickly and reduce the amount of manual, straightforward changes.

The codemods have limited utility for our use case. Although they handle renaming effectively, they don't address the numerous breaking changes in column function signatures (valueGetter, valueFormatter, etc.). The v8 rowSelectionModel changes present similar challenges.

For example, we have more than 200 usages of the component, more than 700 usages of valueFormatter...

For large codebases, it often helps if Data Grid usage is wrapped in shared containers or abstractions. In that case, most of the migration work can usually be limited to those shared layers rather than touching every individual grid instance.

We don't have a Data Grid wrapper, which complicates migration. I'm considering implementing a wrapper now, something like this, and then migrate module by module or screen by screen (This is a rough draft, not the final version):

const adaptValueGetter = oldGetter => (value, row, column, apiRef) => oldGetter({ value, row, column, apiRef });

const adaptValueFormatter = oldFormatter => (value, row, column, apiRef) =>
  oldFormatter({ value, row, column, apiRef });

const adaptValueSetter = oldSetter => (value, row) => oldSetter({ value, row });

const adaptGroupingValueGetter = oldGetter => (value, row, column, apiRef) => oldGetter({ value, row, column, apiRef });

const adaptColumns = columns =>
  columns.map(col => ({
    ...col,
    valueGetter: col.valueGetter ? adaptValueGetter(col.valueGetter) : undefined,
    valueFormatter: col.valueFormatter ? adaptValueFormatter(col.valueFormatter) : undefined,
    valueSetter: col.valueSetter ? adaptValueSetter(col.valueSetter) : undefined,
    groupingValueGetter: col.groupingValueGetter ? adaptGroupingValueGetter(col.groupingValueGetter) : undefined,
  }));

const DataGridAdapted = ({ columns, ...props }) => <DataGridPremium {...props} columns={adaptColumns(columns)} />;

export default DataGridAdapted;

But it looks like we won't be able to avoid doing it all at once if this adapter isn't a good approach.