These are my (@Kyle McCormick (Deactivated)'s) running notes as I do an investigation into the challenges that Open edX developers face when using Microfrontends and how we can address those. They represent my opinion and have not been approved or reviewed by any other edX employee.

Abstract

We are not currently providing Open edX developers and operators a clear path towards writing, building, and/or deploying edX Microfrontends. As edX.org continues to drive forward its frontend replatforming, this will increasingly become an issue for both the Open edX community and for edX.org itself.

We should address this by:

Writing and sharing documentation for the open-source portion of our MFE build+deploy pipeline.
As soon as feasible, including at least one MFE in an Open edX release and integrating it into the existing Open edX installation process.
Settling on a development environment strategy for microfrontends.
Sharing our plan with the Open edX Build-Test-Release WG and soliciting opinions on it.

Context

What are Microfrontends?

edX is in the midst of a front-end replatforming. The Architecture Team has lead an effort to give us the tools to rapidly build, test, and deploy React.js-based, REST-API-powered frontend apps, a.k.a. “Microfrontends” (MFEs). The eventual goal is to replace all of our existing “Django” front-ends (which are generated by Django/Mako templates and generally use Backbone.js as a front-end framework) with MFEs.

https://github.com/edx/frontend-platform and https://github.com/edx/frontend-build are the two NPM packages upon which most of our MFEs are built (there exist other libraries we use, such as the https://github.com/edx/paragon accessible component library, but all of those are transitively required by @edx/frontend-platform or @edx/frontend-build). Examples of production MFEs are https://publisher.edx.org/, https://profile.edx.org, and https://account.edx.org, all of which we now serve in place of related Django front-ends. An example of a major Django front-end which we are currently rewriting as an MFE is https://github.com/edx/frontend-app-learning , i.e. the LMS courseware experience.

Why are we doing them?

MFEs give us many advantages. I won’t enumerate them all here, but the ones that are most apparent to me personally are:

Testing an MFE is easy: just mock the REST API. No need to run costly acceptance tests a la Bok Choy.
It’s harder to create a tangled mess of frontend/backend logic when you are forced to pipe everything through a REST API.
With MFEs, one can often open a PR, get a green build, and deploy to prod in well under an hour. That same process can take over a day with edx-platform.
Refactoring the backend is much easier when frontend logic is separate. When Django frontends are deprecated, there may be hope to decomposing the edX monolith.
React.js is very powerful, popular, and actively developed, much more so than Backbone.js.

How does this relate to Open edX?

With the onset of the LMS courseware MFE effort, it’s become more apparent than ever that we are serious about rewriting its frontends, and not just the ones that are edX.org-specific. As time goes on, we will need to do one of the following:

Continue to support all non-edX.org-specific Django frontends for Open edX instances.
Deprecate significant portions of Open edX frontend without any official alternative implementation, leaving it up to the Open edX community to figure out how to either run our MFEs or develop their own.
Officially make Microfrontends part of Open edX

Option #1 seems like a lose-lose situation for both Open edX and edX.org. The Open edX community would be excluded from all the frontend innovations and UX imporvements that we make the in the future, and we (edX.org developers) would not be able to remove the large swaths of Django frontend code that we had hoped to deprecate as part of the frontend replatforming.

Option #2 strikes me as a betrayal of trust to the Open edX community that would be against our mission of improving access to high-quality education.

Given that, it is clear that we should pursue Option #3.

Can Open edX developers use MFEs now?

Yes, sort of, and no.

Yes, in that (as far as I know) the code for all of our MFEs are publicly available on GitHub.

Yes, in that the code to build and deploy frontends is publicly available in the edx/tubular repository (although our GoCD pipelines, which call that code, are closed-source).

Sort of, in that that documentation for that code is sparse and scattered between a few locations (READMEs, Confluence, etc.).

Sort of, in that while it is fairly straightforward to develop on a single MFE by running npm start while Devstack is running, this becomes more cumbersome as we need to run multiple MFEs at a time while developing. Furthermore, it probably isn’t obvious to a new Open edX dev which Devstack containers need to be running to get any given MFE to work correctly. We started “addressing” this by adding some individual MFEs to Devstack as nginx containers, but that is a very heavy-handed solution.

No, in that no MFEs were included in the last Open edX release.

No, in that MFEs are not included in the Native Open edX installation, which many small Open edX rely upon.

No, in that MFEs do not seem to collect any sort of change log other than git commits, which do not suffice.

So what do we need to do?

TODO: Flesh this out

Based on the above, I see three categories of work to be done:

Documentation
- Most of the code to use MFEs is already available, but how to use it isn’t clearly documented. We should provide a canonical guide for developing, debugging, testing, and building MFEs that, ideally, would allow someone to do all those things without asking for the help of someone experienced with MFEs. It would be great if this is also the guide that we use for MFE development internally so that it stays up-to-date.
- MFEs that are part of Open edX releases should have change logs.
Development environment
Deployment

Will this affect edX.org developers?

Ideally, yes, and positively!

As mentioned earlier, if we make it easy for Open edX community developers to use our MFEs, there will be much less friction towards deleting thousands and thousands of lines of Django frontend code from edx-platform, empowering ourselves to simplify and decompose the monolith.

Furthermore, the developing-multiple-MFEs-at-once problem is just as much of an issue for edX.org devs as it is for Open edX community devs, so solving that is a win for everyone.

Prior Art