Upcoming changes to AG Grid Angular in v28

In this post, we want to give you notice of the changes that are coming to our Angular wrappers in v28 and actions that you can take now to make the upgrade as smooth as possible.

In v28 of AG Grid, we are enabling the Ivy distribution format which brings numerous benefits. However, this means the minimum Angular dependency will increase to Angular v12.

To maintain support for older versions of Angular, v8-11, we are going to release new legacy versions of our Angular packages. So please read on to understand what to expect when upgrading to AG Grid v28.

Why are we doing this?

Since Angular v12 the recommend distribution format for Angular libraries was changed to Ivy. There are many advantages to this approach, namely no longer requiring ngcc to run and mutate your node_modules.

As Angular v12 is over a year old and there are other features that moving our library to Ivy unblocks we have decided to make this change now. This brings us in line with the rest of the Angular ecosystem in moving towards Ivy everywhere.

We have decided to update our existing Angular libraries, ag-grid-angular and @ag-grid-community/angular, (see Package vs Modules for why we have two Angular libraries) to use Ivy as opposed to creating new packages for the Ivy format. We have decided to minimise the change for users who are up to date with Angular and avoid future breaks when View Engine is no longer supported.

What to expect when migrating to AG Grid v28

Apps using Angular v12+

First off, if your application is built with Angular v12 or above, then you will update as normal. Simply move ag-grid-angular to v28 and notice that ngcc will no longer run against our package. You may see a slight improvement in CI build time as a result of this.

The following warning will disappear from your build log!

Generating browser application bundles (phase: setup)...
Processing legacy "View Engine" libraries:
- ag-grid-angular [es2015/esm2015]
Encourage the library authors to publish an Ivy distribution.

Deprecation of AgGridModule.withComponents().

With our Angular lib now requiring its consuming applications to run with Ivy, we have deprecated and removed the .withComponent() method from the AgGridModule. This has not been required for any applications that were running with Ivy but as we supported Angular v8 we could not remove it.

Simply delete the .withComponents([MyComponent]) if it is present in your code.

That is all you need to do concerning this Angular upgrade as part of AG Grid v28. Do still check the changelog for grid-related breaking changes.

Apps using Angular v8-11

If your application is on an old version of Angular there is going to be more work for you to upgrade to AG Grid v28 to get our latest features. If possible take this opportunity to upgrade your Angular version to at least v12. However, we understand this is not always going to be viable. As a result, we will produce legacy versions of our Angular libraries that will still work in your app.

These will be ag-grid-angular-legacy and @ag-grid-community/angular-legacy respectively for Package / Module setups.

So in your package.json file, you will need to change the AG Grid package to be the legacy version.

"dependencies": {
    ...
-    "ag-grid-angular": "^27.3.0",
+    "ag-grid-angular-legacy": "^28.0.0",
    ...

You will then need to update all the import paths throughout your application to use the legacy package name too.

- import { AgGridModule } from 'ag-grid-angular';
+ import { AgGridModule } from 'ag-grid-angular-legacy';

The only difference between the standard and legacy packages is the Angular distribution format, so aside from standard major version breaking changes, the legacy package should act as a drop-in replacement.

AG Charts v6

The same change will also be applied to our standalone Angular charting library. So from v6 of ag-charts-angular you will need to have a minimum Angular dependency of v12.

If you are on Angular v8-11 then you will need to switch to the ag-charts-angular-legacy package.

"dependencies": {
    ...
-    "ag-charts-angular": "^5.3.0",
+    "ag-charts-angular-legacy": "^6.0.0",
    ...

Then also update your chart import paths too.

- import { AgChartsAngularModule } from 'ag-grid-angular';
+ import { AgChartsAngularModule } from 'ag-grid-angular-legacy';

Conclusion

As Angular continues to move forward we want our users to be able to take advantage of the new features and so we will continue to move forward with Angular upgrades. This means that in future releases please expect that we will continue to drop support for older versions of Angular until we reach v12 and will drop the legacy packages entirely.