We really really need some docs on MFE env settings

Working Groups Build-Test-Release
1

Microfrontends (MFE) are about to become officially part of the Open edX Lilac release, scheduled for June 9th. As part of my job as a Tutor maintainer, I am trying to figure out what is the minimal set of common settings to be defined for each MFE, and this is made very difficult by the fact that the none of the MFEs document any of their settings.

For instance, here is the list of env vars for a few MFEs:

By looking at these settings lists, I am unable to determine whether I need to define, for instance: ORDER_HISTORY_URL, DISCOVERY_API_BASE_URL, SEARCH_CATALOG_URL. These are just examples of settings for which I have no clear idea whether their values should be shared with other MFEs or not. All I can do is grep the repo source code along with my node_modules/ folder for every one of these settings. This is unmanageable.

As open source maintainers, we need the following:

  1. A list of documented settings that are shared between all MFEs. If necessary, this list can be split between frontend-component-header, frontend-component-footer and frontend-platform.
  2. For every MFE, a list of documented settings that are specific to this MFE.

The responsibility of creating these docs belongs to the developers who created the settings and who maintain the MFE repositories, i.e: edX.

I am sorry to raise the alarm in a public forum, but I have asked about this multiple times already in online conversations, both in private and in meetups of the BTR working group. Every time, my request was acknowledged, but not action was taken (as far as I know). With the multiplication of MFE and the Lilac release just around the corner, this documentation effort must be added to the MFE team roadmap as soon as possible.

4 Likes
2

I just stumbled on a tidbit of code that highlights the need of better, standardized MFE settings, even for edX developers. Both the profile and the ecommerce MFEs depend on the OPEN_SOURCE_URL setting, according to their env files:

However, it turns out that this variable is only ever used by the Gradebook MFE, which is totally unrelated to these other two: https://github.com/search?q=org%3Aedx+OPEN_SOURCE_URL&type=code

2 Likes
3

I can add one more really to the title. It’s incredibly inconvenient trying to build and test mfes w/o such documentation.

4

I totally hear you on this.

@sarina, I think our team needs a task to document the core environment variables expected to be defined in all MFEs, and then coordinate with other teams to document additional custom variables in MFEs they own. I’m going to go write up a task in FEDX (for now) with some details, and will link it back here.

Update: [FEDX-566] MFE Environment Variable documentation - JIRA

3 Likes
5

Thanks @djoy I appreciate your response!

6

Hi all,

Following up on this, I’ve merged some documentation for the common variables needed by all MFEs, as well as those used by the header and footer components:

https://edx.readthedocs.io/projects/edx-developer-docs/en/latest/developers_guide/micro_frontends_in_open_edx.html#configuration-with-environment-variables

Next I’m planning on adding similar PRs for the MFE-specific environment variables in frontend-app-account, frontend-app-payment, frontend-app-profile, frontend-app-ecommerce, and frontend-app-gradebook.

4 Likes