Upgrading To AG Grid 33

AG Grid 33 is one of our most significant releases ever: We've refactored the way Modules are implemented to deliver up to a 40% reduction in bundle size; the Theming API has become the default way to style the grid, making it even easier to customise the Grid, and we've also cleaned up our APIs to make the library more maintainable, enabling us to deliver more features, faster, in future.

All these changes mean this major release contains a larger-than-usual number of breaking changes. We recommend using our latest Codemod to automate most of the migration process, however, if you prefer to upgrade manually, this post outlines the quickest and easiest way to do so.

TL;DR

Run the latest Codemod to automate the migration process, or, to upgrade manually:

Migrate to the new way of registering modules. Doing so will reduce your grids' bundle size by up to 40%.
Opt out of the Theming API with the theme={'legacy'} gridOption, or migrate your CSS styles to the API.
Review the other minor breaking changes to specific features & the removal of deprecated APIs from version 31 or older (12+ months ago).

💡

We understand that not everyone can upgrade immediately. To help those who need more time, we're now offering Long-Term Support (LTS) versions of AG Grid (v32-lts) and AG Charts (v10-lts).

Learn More

How These Changes Benefit You

When making significant changes to any library, we know there needs to be a strong incentive to justify the time and effort required to upgrade:

Refactoring the internals of the grid means we can now tree shake from a single bundle, reducing the size of your grids by up to 40%.
Simplifying the library so that we only need to support 2 packages instead of 25 means better velocity for new features in future releases.
Moving towards the Theming API means no more need for importing those CSS files above your component/somewhere in the app.
1. Note: Whilst we're defaulting to the Theming API, we intend to support the legacy CSS themes for the foreseeable future, so you only need to migrate when you're ready.
Having the CSS in the code also means it is split per module adding even more savings to bundle size.

Migrating To New Modules

The main change in this release is to the way Modules work. We've refactored the underlying architecture of the grid so that we can optimize our bundle size and let you choose the features you want to use, whilst tree-shaking out everything else.

Migrating From Packages

If you were previously using Packages and aren't concerned with bundle size then the easiest way to migrate to the new Modules configuration is to use the AllCommunityModule or AllEnterpriseModule.

First, import the Module Registry:

// Import the Module Registry
import {
    ModuleRegistry,
} from 'ag-grid-community';

And then import and register the AllCommunityModules to access all of the Community Features:

// Import and Register All Community Features...
import {
  AllCommunityModule, 
} from 'ag-grid-community';

ModuleRegistry.registerModules([
  AllCommunityModule
]);

Or import and register the AllEnterpriseModule to access all of the Enterprise and Community features:

// Import and Register All Community & Enterprise Features...
import {
  AllEnterpriseModule,
} from 'ag-grid-enterprise';

ModuleRegistry.registerModules([
  AllEnterpriseModule 
]);

Doing this is essentially the same as using either the ag-grid-community or ag-grid-enterprise Packages in AG Grid 32.

Migrating from Modules

If you were previously using Modules and want to take advantage of the new bundle size reductions to make your grid up to 40% smaller, you can import the specific modules you want to use:

import {
    ModuleRegistry,
    PaginationModule,
    RowSelectionModule,
    TextEditorModule,
    ClientSideRowModelModule,
} from 'ag-grid-community';

ModuleRegistry.registerModules([
    PaginationModule,
    RowSelectionModule,
    TextEditorModule,
    ClientSideRowModelModule,
]);

This is similar to how modules worked in version 32 but significantly reduces bundle size thanks to the more fine-grained modules available in version 33.

Module Selector

To help make the process easier, we created a Module Selector which lets you select the features you want to use, and then generates the relevant import code for you:

0:00

/0:18

ValidationModule

If you include the ValidationModule when migrating the grid will log messages to the console to let you know which (if any) Modules are missing.

For example, using the rowSelection feature without registering the RowSelectionModule:

import {
    ModuleRegistry,
    ValidationModule,
    // Other modules...
} from 'ag-grid-community';

ModuleRegistry.registerModules([
    ValidationModule,
    // ...
]);

return (
  <AgGridReact ...
    rowSelection={'single'} // This feature Module is not registered...
  />
);

Will produce this console error:

AG Grid: error #200 
Unable to use rowSelection as RowSelectionModule is not registered. 
Check if you have registered the module:
import { ModuleRegistry } from 'ag-grid-community'; 
import { RowSelectionModule } from 'ag-grid-community'; 

ModuleRegistry.registerModules([ RowSelectionModule ]); 

For more info see: https://www.ag-grid.com/react-data-grid/modules/

For more information, refer to our Modules migration documentation.

Migrating to the Theming API (Optional)

The other major change in AG Grid 33 is that we now default to the Theming API, which allows you to use the Theme Builder to quickly create custom grid themes with our intuitive UI.

This change makes things much simpler for new users, but you don't have to use it if you already have a custom, CSS-based theme. We're supporting CSS styles for the foreseeable future, so there is no rush to migrate to the Theming API.

Opting Out

To continue using CSS to style the grid, you can opt out of the Theming API by setting the theme gridOption to "legacy":

<AgGridReact
    theme={"legacy"}
    ...
/>

Learn more about opting out in our Continuing with Legacy Themes docs.

Adopting the Theming API

If you're ready to start using the Theming API, you'll need to:

Remove CSS imports.
Import your chosen theme.
Convert CSS properties to their new names.
Optional: Remove ag-theme-* classes and update CSS rules that target them.

If your application is split between multiple pages, it can be migrated one page at a time.

Learn more about these steps on our Theming Migration docs.

Other Breaking Changes

The majority of the other breaking changes are covered by the Codemods. These changes include:

Improved Types to help make your applications more robust.
Specific changes to Sparklines, bringing functionality more in line with AG Charts.
Various small (1-2 each) API changes to Integrated Charts, Column State, Grid State, and SSR.

For a complete list of these changes, refer to the Breaking Changes section of our Migration Guide.

Removal of Deprecated APIs

Finally, we've removed a number of APIs which were deprecated in or before version 31. These APIs have been deprecated for at least 12 months and affect the Grid API, Grid Options, ColDef and Interfaces and are also covered by the Codemod.

For a complete list of these changes, refer to the Removal of Deprecated APIs section of our Migration Guide.

Summary

Whilst the initial impression of this release may be that there is a lot of work required to upgrade, with the help of the Code Mods and opting out of the Theming API changes it should be a relatively straightforward process, especially for users upgrading from version 32.

We're here to make the process easier for you and also welcome your feedback. If you’re an Enterprise user and encounter issues whilst upgrading, please contact us on Zendesk.