Breaking OpenMRS 3.x frontend core update

Development
,
1

The O3 squad will be rolling out a substantial breaking change to openmrs-esm-core. These changes will arrive with the package versions 4.0 of @openmrs/esm-framework and openmrs.* We are presently aiming to complete this update by May 20, but we are open to community feedback about the process for this.

We intend to include the following changes:

  • Upgrade to React 18. This will probably not require any action from O3 implementers.
  • Upgrade to React Router 6. This may require some substantial changes. Please see the React Router 6 migration guide.
  • Upgrade to Carbon 11. This too will require some substantial changes. Please see the Carbon 11 migration guide.
  • A breaking change to the way frontend modules (aka microfrontends) are loaded which will improve reliability and fix some bugs related to frontend loading. No changes should be required to upgrade.
  • A minor breaking change to breakpoints and responsiveness functions. The only change required is that code that checks if useLayoutType() == "desktop" should be changed to use isDesktop(useLayoutType()).

Frontend modules compiled against the previous version of openmrs-esm-core will not work with the new version of openmrs-esm-core and vice-versa. The app shell and frontend modules must be upgraded in sync.

The dev3.openmrs.org server will be upgraded to the new system as soon as it is released. Developers using that server as a backend for custom frontend modules will need to upgrade their modules to the new version for them to work. Developers who develop against custom backends will not be affected in this way (as long as their server keeps running the old version of the app shell), but should still upgrade ASAP, as the old version will not be maintained. For future upgrades we may adopt a more conservative upgrade process, but given the early stage of O3 adoption, I think it is best to have everyone upgrade at once.

Happy to hear questions/comments/concerns/cheers.

*No, it is not OpenMRS 4.0, it is still OpenMRS 3. These are just the frontend core package versions; the fact that they are presently 3 is incidental.

@grace @mksd @jdick @samuel34 @angshuonline @burke @mseaton @zacbutko @dkibet @dkigen

6 Likes
2

Thank you Brandon for this clear post. Definitely we need to maintain the supported versions of our key technologies like react and carbon - thank you for doing this maintenance work.

Re the major breaking change: maybe this is obvious to others, but… What would happen if someone’s esm modules were not up to date? Is the worst case scenario that the esm would render a 404…?

3

If a server is running the app shell version 4 and someone tries to load a module compiled with core version 3 onto it, that module will not be loaded, but the app will continue running. An error will be shown in the console.

1 Like
4

Thank you @bistenes!

CC @eudson @samuel34. I’ve discussed with @dagimm and he’s aware and the ET team will be able to address this. But not sure about next steps for OHRI-mainstem.

1 Like
5

@grace thanks for tagging us, @pirupius already brought this to our attention and we will be doing the same next week to make sure we are aligned. We will also support the @ICAPEthiopia on this.

2 Likes
6

Hey @bistenes based on initial date estimate of May 20, is it possible to publish a pre-release with the upgrades we can work with to make the necessary changes to our end?

7

Hi @pirupius , I think that would be reasonable for us to do. I’ll release 4.0-pre.0 once (BREAKING) Upgrade to Carbon v11 by denniskigen · Pull Request #437 · openmrs/openmrs-esm-core · GitHub is merged.

1 Like
8

Version 4.0.0-pre.0 has been published! Please try installing it and upgrading accordingly.

9

@slubwama this is the talk post for the frontend core major update.

10

@dkayiwa Thanks. We may need to change the SDK to understand how to deal with the changes.