Integrating microfrontend tooling into OpenMRS SDK?

Agree with not creating a second SDK. Devs working primarily in frontend technologies already have tooling like npm, nvm, etc.

Enhancing our SDK to facilitate the packaging, deployment, and running of OpenMRS instances with new frontend artifacts makes sense.

Put simply, our SDK should make development, packaging, & deployment easier while focusing on simplifying & standardizing the OpenMRS-specific steps that devs otherwise need to do manually and the fewer OpenMRS-specific aspects of development we have, the better.

1 Like

Noted all ,thanks

I’d like to work on this in the next couple weeks. Not the generator part (sorry @ibacher ) but rather the integration with setup, deploy, and run.

What we have presently is IMO a second SDK, npx openmrs, which is a very good thing and was definitely the right decision. The task now is to integrate that with the maven SDK.

I agree with @mseaton 's proposals. As @ibacher suggests, I think we should implement this by having the maven SDK delegate to the openmrs frontend tool as much as possible.

So I suggest that openmrs-distro.properties should support the following sorts of properties:

# Microfrontends to include, a la microfrontends.json
spa.microfrontends.@openmrs/esm-home-app=next
spa.microfrontends.@openmrs/esm-login-app=1.3.0

# The base application path and SPA path
spa.apiBase=openmrs/
spa.spaBase=openmrs/spa/

# Paths to config files to build in
spa.config=config.json,config-site.json

# Additional import map lines
spa.importmap.config-file=assets/another-config.json
    # becomes the line "config-file"="assets/another-config.json"

# Additional assets to bundle with the application
spa.assets=assets

Where we have files config-json, config-site.json, and assets/another-config.json all in the distro folder.

This will build the specified frontend application to frontend/ in the application data directory, both in development and when building the distribution. This will work out of the box with openmrs-module-spa.

I don’t know how the SDK should support builds where the frontend is being served from outside the application data directory. We should figure this out. @mksrom , @mksd ?

I realize this seems like a lot of new stuff in openmrs-distro.properties. Other ideas are welcome. But these are all application build parameters and that seemed like the natural place for them to go.

CC @jdick , @corneliouzbett , @dkayiwa

EDIT: Changed spa.@xyz to spa.microfrontends.@xyz

3 Likes

This is great! I might start working on MFs.

IMO: with the assumption that the individual who wants to serve frontend assets outside the application directory already has a pipeline of building those assets. So maybe adding a prompt to decide whether to serve from a remote URL, If yes ask for the URL and skip building the frontend assets, then use the information to set the GPs; spa.remote.enabed=true and spa.remote.url=<provided-URL>. Dunno how SDK is architecture but a simple insert for the GPs will do the trick.

2 Likes

As far as I know that doesn’t matter too much.

And otherwise I am really excited to see this work being moved forward @bistenes! That will be really useful for the ICRC as we start embracing O3 in the next few months (hopefully).

Cc @frederic.deniger

2 Likes

Thanks for working on this @bistenes ! With a quick review, this makes sense to me!

Take care, Mark

@bistenes Thanks for this, this looks great!

Are these actually necessary to create a distro bundle? They look to me like more of runtime considerations than distribution-time, but I suppose these are embedded in the actual SPA page?

The SDK doesn’t really have a role in the actual instance running nor do we want to make that a requirement. So having the SDK directly create GPs is probably not the best idea (the SDK at best loads a skeleton of the OMRS DB schema that’s then modified by the Liquibase scripts).

3 Likes

Yeah, that is the case exactly. Not sure there’s a good way around it that wouldn’t introduce a bunch more server-client coupling.

Yeah, that definitely makes sense.

@mksd & @mksrom, will @bistenes’ approach work with the folder layout convention proposed in RefApp 3.x? I mean, I know it can work, but do we see a way to make this the default/assumed convention that “just works”?

@burke isn’t that a question for @bistenes?

Maybe I’m missing something but what the SDK does usually is build the distro and then do its thing. Building the distro means relying on the build of the distro Maven project. In other words the SDK acts downstream of the distro project.

But if anything needs to be changed in the distro project to make the SDK tooling easier, let’s do it. It’s not too late since we haven’t released anything yet.

Actually, I’m just realizing that the RefApp 3.x layout doesn’t have an openmrs-distro.properties file. It seems like the modules are just listed in the POM.

So it seems completely orthogonal to what I’m working on here. But maybe the RefApp 3.x layout should instead be built around an openmrs-distro file?

The old Ref App (so to say) requires to maintain the openmrs-distro.properties file LHS keys in sync with the POM dependencies. That was always “ok” but obviously requires some additional attention.

Having some tooling that generates that file from the POM file would be ideal. Whilst writing this I realise that this piece of O3-minded tooling could be somewhere in the SDK?

Would this mean that we’d also want to define the microfrontends in the POM?

I do think it’s worthwhile to discuss whether the openmrs-distro.properties file is secondary, and generated from information in a distribution POM, or whether it is a primary artifact that is maintained and complementary to the distribution POM (or could stand alone and not require a distribution POM).

Maybe the answer is that both are valid options, as long as we build common standards in our distribution packaging.

The assumption I’ve been making is the the openmrs-distro.properties file (and / or some new openmrs-distro.yml file) would continue to evolve as a means to define an OpenMRS distribution in full, and that SDK and other tooling would be able to install a fully defined and operational OpenMRS instance with war, modules, owas, config, and microfrontends with just the configuration present in this file.

Interested in discussion more and hearing others thoughts.

Mike

Thanks @mseaton for sharing your thoughts. I realised that I had a draft response for @bistenes that I had left hanging… and now rather that posting it I’d suggest that we take this to a good ol’ TAC.

Cc @grace

1 Like

Roger that @mksd, I’ve added this to the top priority list for next week’s TAC.

I’m not going to be around for next weeks TAC, so just some thoughts on this:

  • Currently the RefApp Docker images are built using the SDK build-distro command. Consequently, the “final” Docker image is a product of the openmrs-distro.properties file, the openmrs.sql file (these are the two things bundled in current Reference Application JAR file).

  • The openmrs-distro.properties is thus at the heart of the process that we use to setup both the community-run servers and local development servers. Moving away from it probably means we need to redesign large parts of the SDK.

  • I think it’s important to ensure that there’s alignment between how we are packaging RefApp 3.0 and how we encourage people to setup dev environments, at least for backend work. I.e., the more similar they are, the more we can trust that changes that work locally will continue to work when deployed. I’m pretty agnostic as to whether this means we keep things working as they are or just modify the SDK.

  • Although this is somewhat tangential, it’s probably good to think about the role that module-spa will play in the future, i.e., it seems pretty essential to the SDK being able to deploy MFs to a local server and to keeping OMRS deployable as a single bundled WAR.

  • Probably worth considering that we may need to maintain multiple kinds of Docker images, e.g., one fully bundled for the community demo environment and one not fully bundled for the community development environment.

2 Likes

IMO this is very critical for moving things forward

Rather than building this complexity into the SDK, pointing it to relevant distro.properties files would be the best way forward

2 Likes

Discussed in TAC call on 2021-06-28. General agreement on working toward a distro.properties (eventually a YML) as a single source of truth, generating POM contents as needed from it.

1 Like