Frontend-base: the plan for Willow

Working Groups Frontend
1

Hi there! This is our plan for the frontend-base conversion as it touches the next Open edX release, Willow. Comments are welcome!

TLDR

Starting now, all learner-facing MFEs will be converted to frontend-base apps in master, and will be enabled by default on Willow. Legacy MFEs will continue to be maintained in legacy-mfe branches, and shipped disabled.

The story so far

After a long stretch of development, the frontend-base library reached 1.0 in July, and Verawood is the first release to ship it. Four frontend-base apps were included. Authn and Learner Dashboard are there but disabled by default, each replacing the MFE of the same name. Instructor Dashboard is enabled by default, replacing the legacy instructor dashboard, and so is Notifications, which ports the old frontend-plugin-notifications over.

Landing frontend-base

The frontend-base conversions have been built on long-lived frontend-base branches in each repository. This has worked well for development, but there’s some maintenance pain because the two branches have to be kept in sync: the handful of us doing frontend-base work port every feature and fix that lands on master across by hand. With two or three apps in flight this was tedious but doable. But things have changed.

For Willow, we’re not only planning to convert every learner-facing MFE, but to have them enabled by default. So it’s time to distribute the load. Starting now, we’ll land the conversions in each repository’s master (or main) branch. In practice, this means that any ready-to-go conversions (such as Authn, Learner Dashboard, and Catalog) will land over the next few days, and ones that are in-progress will land as their PRs are approved prior to the Willow cutoff.

You can follow along on the frontend-base board.

What happens to MFEs?

MFEs aren’t going anywhere, for now. Immediately before each frontend-base merge we cut a long-lived legacy-mfe branch, and that is where they carry on receiving updates as they’re deemed necessary. They’ll be shipped in Willow, and though disabled by default, it’ll be easy to enable them (tutor-mfe’s README has the details). Nothing changes for previous releases, or for an operator running them, and no history is lost or rewritten in the move.

I’m an operator: what do I have to do?

If you run a stock deployment with no frontend customizations, very little: upgrade to Willow and you’ll get the frontend-base apps by default. They should, for the most part, look and behave the same from the point of view of the end user.

The interesting cases are branding, theming, plugins, and forks, because a frontend-base app is an npm package rather than an independently deployed MFE. This is the composable architecture OEP-65 describes, and it’s what buys the better learner experience, faster builds, and more complete plugin API. But it also means that any such customization needs to be modified accordingly.

The Verawood release notes cover the specifics and link out to porting documentation. The short version: there’s a frontend-base-compat shim, so a part of what you have today can survive without a port, but there’s no way around refactoring branding and theming. And if you fork an app and build from its master branch, that branch is now the frontend-base app, so repoint at legacy-mfe to stay where you are.

If you’re not ready in time for Willow, it’s fine: the legacy MFEs still ship, and turning the frontend-base apps off and the MFEs back on is a matter of flipping a couple of tutor-mfe filters. That buys you a release cycle or two rather than forever, though, so it’s worth starting the port as soon as possible. The best time to try it is now, on Verawood, where the same apps are already there waiting to be enabled.

I maintain a frontend-app-* repository: what changes?

Once the conversion lands, master is the frontend-base app, and that’s where new features and fixes go. If you haven’t been following along, OEP-65 and the official glossary are good places to start understanding the motivation and terms, frontend-base’s README is the place to catch up on how it’s all implemented, and tutor-mfe’s Frontend-base site development section covers bind-mounting your app into a running site so you can actually work on it. If you’d rather work outside Tutor, frontend-template-site’s Local Development with Workspaces does the same thing with npm workspaces (more details on the latter in a standalone how-to I posted here in the forum and to the wiki).

Bear in mind that master also becomes an unstable branch that publishes prereleases to npm, with released versions coming off stable, so landing a breaking change no longer means shipping it to everyone the same day. OEP-10 ADR 0002 has the full branch layout, including how older majors and minors keep getting patched.

Last but not least, there’s now a second branch to keep an eye on, since bugfixes that matter to the MFE still need to reach legacy-mfe for as long as a supported release ships it.

Questions?

Feel free to reply to this thread, or to ask in the #wg-frontend channel on Slack.

Thanks!

2

An update on progress:

We’ve landed the frontend-base conversions of the following repos:

  • frontend-app-authn
  • frontend-app-learner-dashboard
  • frontend-app-catalog

This means that their master branches now contain the frontend-base version of the app, and the (unaltered) MFE version is in legacy-mfe.

tutor-mfe@main has been updated accordingly so builds continue to work.

What’s likely to happen by the end of next week:

  • Including the new frontend-app-catalog in tutor-mfe@main
  • Enabling the frontend-base versions of frontend-app-authn, frontend-app-learner-dashboard, and frontend-app-catalog by default in tutor-mfe@main
3

Thanks!

What exactly is the role of frontend-template-site? Its README just says “This repository is a template for Open edX frontend sites”, but they don’t say what a “frontend site” is, or how many one should expect to have, or who wants one or why.

As I infer from the frontend-base README, frontend-base and the various new MFEs need to be packaged into a shell/site, and that can either be the super basic one built into frontend-base or one based on frontend-template-site?

4

In a nutshell, it - or rather, the site frontend-template-site becomes - is meant to be what glues frontend apps into a single webpage.

Why a template? Because it’s just a suggestion: the Open edX operator owns everything in there. They’re meant to fork that repository and modify everything (everything!) in it as they see fit. Up to and including making arbitrary changes to index.html.

Another way to see it: it’s npx create-react-app for Open edX, but with Github templates. SPOILER ALERT: or a prototype for a future npx create-openedx-site.

Ideally, one. Or, more precisely, one per Open edX deployment. This is what gets you the nice soft navigation between pages. It’s, by no coincidence, how tutor-mfe does it:

When frontend apps are enabled, the plugin builds a frontend-base site that bundles them together into a shell application.

That said, you can deploy one site for each app (just like we’ve always done with MFEs), if you want. You’ll just have to build your site.config files (one per site) accordingly. But then you’re back to full page loads whenever you click an otherwise internal link.

There are actually two sites built into frontend-base: npm run dev in a frontend-base checkout gets you the built-in “dev mode” site, mean for developing frontend-base itself. And then there’s test-site, which is only there for CI. Neither is meant to be used anywhere near production.

“One based on frontend-template-site” is exactly correct, though, as explained above.

Great questions! Looks like we might want to improve the READMEs, a bit. At the very least, we should lead with a link to the official glossary. :slight_smile:

5

I think there is an important point about frontend-template-site that’s missed here. According to Verawood release notes:

If you deploy your Open edX instance using something other than Tutor, start by looking at frontend-template-site.

So, wouldn’t it be better to say, the role of the frontend-template-site really is to provide a way to run the Open edX’s frontend, without Tutor, “natively” using NPM. I get a sense that, one could never know the existence of frontend-template-site and live with just tutor-mfe + Tutor plugins to develop and deploy Open edX instances. Is that right?