/
2025-08-27 Frontend-base Release Strategy Summit

2025-08-27 Frontend-base Release Strategy Summit

 Date, time, location

🥅Objective

Decide when and how to release the frontend-base MFE conversions.

 Context

State of frontend-base

At time of writing frontend-base is usable as an alpha NPM package, along with two MFEs that have been similarly converted to libraries/NPM packages: frontend-app-authn and frontend-app-learner-dashboard. All are easily deployable in concert with a recent Tutor dev environment using the frontend-template-site template repository.

Work can be followed through the project roadmap. Conversion of the remaining Tutor-supported MFEs is under way, targetting Ulmo for completion. Four developers are working near full-time on this.

A recording of the Open edx 2025 Conference workshop that demonstrates how the whole thing works can be found on Youtube.

Breaking Changes

This is a list of proposed breaking changes introduced by the frontend-base conversions, so far. More will be added as MFEs are converted.

[Invitation] Frontend-base Release Strategy Summit: August 27, 2025

Missing Features

The following is a list of tasks that must be tackled before release, whatever form it takes:

  • Design tokens: frontend-base as it stands is still on Paragon 22.

  • Complete the conversion of MFEs: work has not yet started on the two major ones, Learning and Authoring. Work is advancing fast on the others, though.

  • Code splitting: currently, the collection of MFEs makes the single bundle smaller than the sum of the parts by anything from 25 to 50%. But it’s still larger than any single MFE bundle was in the past. We need to split it up.

  • Tutor support: including the ability, if possible, to toggle MFEs from frontend-base to legacy and vice-versa

Release Strategies

What follows is a list of release strategies that have been explored preliminarily. Anything here is presented merely as a framework for discussion.

I. A new client

In this scenario, frontend-base conversions are never merged to their corresponding repositories' master branches. The conversions exist simultaneously but independently of current MFEs, either in separate branches or separate repositories, effectively making them a new Open edX frontend client. Features would be ported between the legacy and new clients as required.

Pros

  • A clear message: the new client is not meant to be 1:1 compatible with the legacy ones - breaking changes and missing features are expected

  • Green-field(ish) development: a big plus for maintainability and developer experience. We can get rid of a lot of cruft! Also, we get to try fresher tech with lesser risk.

  • More time to establish reliability

  • Users get to pick which one they want to use (for a while)

Cons

  • New features that land on legacy master would have to be ported to the frontend-base version as they land, until such time we decide the frontend-base version is where all development should happen

  • It took the better part of a decade to deprecate most legacy Django pages; we could face a similar (though probably much less steep) uphill battle for adoption

  • Some users could get "stuck" in old versions

II. Merge to master ASAP

We merge to master as soon as it is possible to do so after minimizing the scope of breaking changes. It is unlikely there will be no breaking changes, though.

Pros

  • Less effort expended on porting newly-landed features from current edited MFEs (because they'll be landing on frontend-base)

  • More users, faster; developers will have to use frontend-base immediately after merge

  • It's possible (but not certain: see first con below) we'll see fewer users "stuck"

  • Will require enough documentation before merge

  • Will require Tutor support before merge

Cons

  • Can take significantly longer, specially if it is decided to do more to ease the transition (a shim for `env.config.js`, aliases for plugin slots that map 1:1 to new ones, generic tracking hooks for Segment, etc)

  • The longer it takes to merge to master, the more effort is spent on porting newly-landed features

  • Will require enough documentation before merge

  • Will require Tutor support before merge

  • Potentially less time to establish reliability

❓Open Questions

1. How much more development would be necessary to get frontend-base and converted apps to a state that can be merged to the current master branches?

Mostly, it comes down to how many breaking changes, and which ones, are acceptable to merge to master. The following tasks are doable, but would collectively push the release to after Ulmo:

  • Slot aliases, including specific ones for v1 compatibility: currently, frontend-base does not support slot aliases.

  • Wrapping of default content: currently, frontend-base does not offer a “wrap” operation for default content.

  • Providing provisional support for existing third-party services: work can be done on re-implementing support for services such as Segment

  • Partial migrations: A Tutor plugin (a new version of tutor-mfe?) that allows users to enable frontend-base MFEs individually?

The following tasks, while theoretically possible, have not been considered doable in any timeframe, as they would impact the benefits of the current frontend-base design directly:

  • Support for the legacy code API: because frontend-base is now a separate, unified library, maintaining library import names, function names, etc, would not be possible

  • Support for an interim API that works on both frontend-platform and frontend-base: would require reimplementing frontend-base in frontend-platform

2. If we’re breaking so much compatibility (particularly if going the “new client” route), shouldn’t we be doing more?

Yes, that’s one of the advantages of a greener field. The following are under serious consideration, but currently lack resources for a dedicated push in time for Ulmo:

  • Dropping Redux across the board

  • Replacement of Webpack with Vite or Rsbuild

  • Replacement of Jest with Node.js Test Runner

🎥Recording

 Participants

Adolfo Brandes, Braden MacDonald, Brian Smith, Chris Patti, Dave Ormsbee, Deborah Kaplan, Diana Villalvazo Salas, Drew Botka, Ed Zarecor, Feanil Patel, Jacobo Dominguez, Javier Ontiveros, Jesse Stewart-WGU, Kyle McCormick, Max Frank, Muhammad Anas, Nihad Rahim, Rabeeh T A, Rodrigo Méndez, Sarina Canelake, Tony Busa, Zameel Hassan

🤖 Summary

A summary of the meeting generated from the transcript by an LLM.

TL;DR

  • Frontend-base is usable today (alpha on npm) and can be test-driven via the new frontend-template-site. Running two MFEs (Learner Dashboard + Authn) already shows a ~25% bundle size reduction; with more MFEs, 50%+ savings are expected.

  • Big idea: move Open edX frontends to a single SPA built on Frontend-base (everything is a slot), with clearer roles/slots/widgets and simpler, repo-local customization (own your index.html).

  • Breaking changes incoming (slot IDs, runtime config, third-party vendors in core). Segment is the hardest open question.

  • Release strategy still open, but group leans toward letting operators opt-in MFEs gradually, with guardrails and timelines. A few concrete decisions landed (see below).

  • Before converting more MFEs, finish missing platform features (code-splitting, Tutor integration, slot aliases, etc.) and document the migration.

  • New work for Verawood: new MFEs should start on Frontend-base.

Current state

  • Alpha available on npm; easiest trial path is cloning frontend-template-site, running Tutor dev, and composing apps via a single site config.

  • Architecture: one Webpack build today; MFEs consumed as libraries → one SPA. Clear roles/slots/widgets taxonomy; operators fully own index.html for title, favicon, and default markup.

  • Observed wins: unified bundle smaller than sum of MFEs (~25% with two; expected 50%+ at ~10 MFEs). TypeScript types and ADR alignment improved.

Key missing pieces (pre-release)

  1. Design Tokens (Paragon 23): needs a port, not a merge (Adolfo + Brian to design).

  2. Code splitting / lazy-loading by route to counter the “one big bundle.”

  3. Tutor support:

    • How to toggle MFEs (partial migrations) without doubling build times or losing SPA nav.

    • Packaging (separate plugin vs. flags) and devstack/sandbox behavior.

  4. Transition helpers:

    • Slot aliases (old → new IDs).

    • “Wrap default content” behavior for legacy plugin operations.

    • Third-party vendor story (Google Analytics/Tag Manager, Optimizely). Segment needs a strategy (hooks are entangled with header/footer).

  5. Docs & testing:

    • Migration guide, per-MFE conversion playbooks, testing guidance (mocks change due to library consolidation).

Proposed deprecations / changes

  • Plugin slot IDs change (to disambiguate roles/slots/widgets). Legacy names to be aliased during transition.

  • MFE runtime config API replaced by a simpler JSON-load mechanism (flexible source, not platform-tied).

  • Third-party vendor code removed from core; re-introduce as plugins where needed (Segment needs dedicated design).

  • React Helmet removal under discussion; page titles may need a unified pattern to support contextual tab titles.

Release strategy options discussed

  1. “New client” track (preferred by several participants):

    • Frontend-base branches evolve separately for a while.

    • Operators can choose per-MFE whether to use legacy or Frontend-base.

    • Pros: safer runway, clearer message that it’s new (not 1:1 compatible), faster learning; can market wins and reduce review overhead on legacy.

    • Cons: porting effort from legacy → Frontend-base during overlap; risk of some operators lingering on legacy.

  2. “Merge to master ASAP” track:

    • Fewer parallel branches; faster user uptake.

    • Requires slot aliases, vendor shims, Tutor support, docs before merging.

    • Higher immediate stability burden; unlikely to make the OMO cutoff for all MFEs.

Directional guidance that emerged

  • Support partial migrations (per-MFE) for at least one release and at most two once an MFE is converted, so operators can phase in changes.

  • Avoid maintaining two worlds longer than needed; minimize overlap windows per MFE.

  • Prefer converting a limited set of MFEs first to harden the path, then scale (debated; balance maintainer burden vs. earlier aggregate gains).

Concrete decisions & agreements

  • ✅ Do not start converting additional MFEs until the missing features (esp. Tutor toggles, code-splitting, slot aliases) are in place and we agree on the migration mechanics.

  • ✅ Any new MFEs targeting Verawood should be built on Frontend-base from day one.

  • ✅ Operator choice per MFE during the transition (opt-in Frontend-base vs. legacy) is a goal; exact mechanics depend on Tutor design.

  • ✅ Upgrades that help later should land on legacy now:

    • Paragon 23, React Router v6, React Query v5, removing React Test Utils, reducing Redux usage.

    • Rationale: these make ports easier and improve security posture.

  • ✅ Aim to publish clear timelines: which release(s) support both, and when legacy is maintenance-only/archived.

Risks & operator value framing

  • If you don’t migrate: npm drift, security updates lag, incompatible backend API evolutions, shrinking review capacity on legacy.

  • Operator wins to highlight: simpler theming/customization (own index.html), fewer moving parts to track, lighter bundles, cleaner plugin model, clearer types and ADR compliance, and community-maintained security/dep updates.

Action items (owners tbd)

  • Draft DEPR/ADR tickets that set explicit release timelines per MFE (e.g., “supported in both for Release N; Frontend-base-only by Release N+1”).

  • Finish slot aliases and wrap-default-content support.

  • Define the Segment plan (generic event hooks vs. bridge layer).

  • Ship code-splitting in Frontend-base (lazy-load by route).

  • Design & implement Tutor integration:

    • Build strategy (separate plugin vs. flags).

    • Per-MFE toggle UX and build implications.

    • Devstack/sandbox defaults.

  • Publish a Migration Guide (operators + maintainers): config, theming, slot/role mapping, testing changes, known gotchas.

  • Coordinate maintainer engagement: pick the first MFEs, align dependency upgrades on legacy before porting.

Open questions to resolve

  • Final choice and timing between “new client track” vs. “merge ASAP” or a hybrid.

  • Exact per-MFE overlap window (1 vs. 2 releases) and which MFEs go first.

  • How far to break more now (Vite/rsbuild, Jest → Node test runner, drop Redux) vs. defer to post-OMO.

  • Depth of vendor support during transition (how much temporary shimming to include).

 Action items

We need to document the wins for operators from this change so that the value prop for the community is better documented.

 Decisions

  1. Operators can deploy converted MFEs optionally, on a per MFE basis, for at least one release, and at most two releases
  2. For a period of time there will be two branches, and at some point there will be only one: the choice should be up to the maintainer of the repo
  3. Development should default to frontend-base ASAP
  4. Support operators who use master to be able to choose and test frontend-base
  5. Coordinate with individual maintainers on how the frontend-base branch evolves
  6. Communicate to current maintainers things they should/shoudn’t do that will make porting to frontend-base easier
  7. Library upgrades such as react-router from v5 to v6, or react-query from v4 to v5, should happen in master before the frontend-base branch
  8. Do not start converting any new MFEs until the missing features have been tackled, and based on that, a new decision is arrived at on whether any new MFEs will be converted at all for the following release
  9. Any newly developed MFEs that are targetting Verawood or beyond should be developed on frontend-base only