Skip to content
Last updated

Capacitor Update from v4 to v5

As updates to Capacitor versions on the native side are expected to be backward compatible, it is still advisable to maintain synchronized versions on both the native and web sides. However, the update from Capacitor version 4 to version 5 constitutes an exception due to the introduction of breaking changes. These changes may disrupt the connectivity of existing MWAs with the native app if the versions of Capacitor are not aligned. Consequently, for these versions, it is imperative to ensure synchronization of Capacitor versions; meaning if the native app is utilizing Capacitor v5, then the web application should similarly adopt Capacitor v5. We have developed some utilities to facilitate a smoother transition for the MWA side, aimed at minimizing the risk of web application crashes due to inconsistencies in Capacitor versions.

Please adhere to the following recommended steps for the upgrade:

1. Remove any usage of @capacitor-community/http

Since we are dropping support for this plugin, if you are still using it, you will have to migrate to the official Capacitor Http plugin provided with the capacitor/core package.

Configuration and usage example: https://capacitorjs.com/docs/apis/http

Make sure you uninstalled and removed @capacitor-community/http plugin from the package.json to avoid Capacitor versions conflicts later.

2. Install @egym/mwa-utils


npm install --save @egym/mwa-utils

Source code https://github.com/egym/lib-mwa-utils.

Now instead of using Portals API directly from @ionic/portals we need to switch to using @egym/mwa-utils library.

/*
  Remove any usages from @ionic/portals 
  and use API from @egym/mwa-utils instead
*/

- import { getInitialContext } from '@ionic/portals';
+ import { getPortalsInitialContext } from '@egym/mwa-utils';


- import { publish } from '@ionic/portals';
+ import { portalsPublish } from '@egym/mwa-utils';


- import { subscribe } from '@ionic/portals';
+ import { portalsSubscribe } from '@egym/mwa-utils';

3. Install updated versions of Capacitor core and plugins.

To avoid npm dependencies versions conflicts during updating each of the capacitor package separately, it's recommended to install new versions for all of them together in one command, e.g.:

npm install --save @ionic/portals@0.9 @capacitor/core@5 @capacitor/android@5 @capacitor/app@5 @capacitor/geolocation@5 @capacitor/ios@5

The list of packages to install above can be different from what you are using in your MWA.

Make sure to also install @ionic/portals@0.9 and @egym/mwa-logger@latest as they are specified in @egym/mwa-utils library as peer dependencies.

Also do not forget to update capacitor/cli from the dev dependencies

npm install --save-dev @capacitor/cli@5

Capacitor & Portals packages update example

Please see here the complete example of updating of the existing mwa reference app: https://github.com/egym/mwa-reference/commit/c1e97b81d0cb3399c692459845b870839cba8eb2

Previous page
Next page