Requirements for an MFE

Owned by Adolfo Brandes
Last updated: Oct 05, 2023
2 min read

This is a list of requirements for an MFE to be included in an Open edX release from the perspective of the Build-Test-Release working group. It is suggested that it become part of OEP-61 so it can be used as an official development checklist for micro-frontends, but for now it is simply a technical bar against which each MFE will be measured: if it passes, the MFE can be considered for inclusion. (Actual inclusion will also depend on other, non-technical factors.)

The list

Each MFE must:

  1. Be maintained according to OEP-55, and in particular:

  2. Be production-ready, which means:

    1. Its basic feature-set must be be reasonably bug free;

    2. It has to work reliably with the rest of the Open edX codebase;

    3. It must work if hosted with a URI path other than '/' (e.g., if sharing a domain with other MFEs).

  3. Be internationalized (“i18n”) using current standards set by the Translation Working Group;

  4. Be localized (“l10n”) in the minimum set of languages set by the Translation Working Group:

    1. French

    2. Spanish

  5. Pass Open edX’s accessibility (a11y) standards, and in particular:

    1. Use Paragon components wherever possible.

  6. Have a header that is customizable via npm aliases;

  7. Have a footer that is customizable via npm aliases;

  8. Be compatible with the @edx/brand theming system, as per OEP-48;

  9. Use CSS utility classes in a branding-friendly way. This includes:

    1. Not using using hard-coded in-line styles or brand overrides that specify specific colors ('bg-white'.)

  10. Be deployable as via tutor-mfe, or via a standalone Tutor plugin;

  11. Support runtime configuration;

  12. If the MFE is replacing pre-existing Open edX functionality, the latter must have formally gone through the process established by OEP-21, and in addition:

    1. Allowing one full release cycle before removal of the pre-existing functionality is required (where in OEP-21 this is merely a suggestion);

    2. During the full release cycle prior to removal, it should be possible for the new MFE to be optionally enabled by operators.

    3. If the MFE does not implement feature parity with what it’s intended to replace (i.e., one or more Open edX features would be lost if the original functionality were entirely removed), the community must be alerted to this fact via the DEPR ticket, the OEP or ADR that proposes the new MFE, the new MFE’s README, and/or accompanying forum and Slack posts, so that there is abundant time to adjust.

    4. Tracking log or other analytic events count as pre-existing functionality for this, so they should either be replicated in the new MFE identically or versioned and run through the DEPR process as above.

  13. Not depend on another Open edX component (edx-platform plugin, IDA, MFE, or otherwise) that is not part of the target Tutor release or part of a corresponding, maintained Tutor plugin.

    1. It should only have hard dependencies on libraries that are either in the Open edX organization or a commonly used third-party (such as a generic NPM package)