Repository navigation
[DEPR]: Deprecation of Legacy Home, Course Catalog, and Course About Pages in Favor of MFE Implementations #36785
Description
RFC Start Date
2025-05-22
Target Plan Accepted Date
2025-08-07
Target Transition Unblocked Date
Estimated Oct 2025
Earliest Breaking Changes Unblocked Date
Verawood cut
Earliest Open edX Named Release with Breaking Changes
Willow - 2026-10
Rationale
Historically, the LMS home page (/), course catalog (/courses), and course about (/courses/<course_id>/about) were rendered using Django templates. These views delivered pre-rendered HTML and a full template context, limiting frontend modularity and making reuse of individual data components difficult.
We are moving to a modern frontend architecture using Micro-Frontends (MFEs), React, TypeScript, React Query, and Paragon to improve scalability, maintainability, responsiveness, and developer experience. This new implementation decouples rendering from data delivery via dedicated APIs.
Announcement (with some more details): https://discuss.openedx.org/t/deprecation-of-legacy-home-course-catalog-and-course-about-pages-in-favor-of-mfe-implementations/16008
Removal
The following server-rendered Django templates and backend logic are scheduled for deprecation and eventual removal:
lms/templates/index.htmllms/templates/courseware/courses.htmllms/templates/courseware/course_about.htmllms/templates/courseware/course_about_sidebar_header.htmllms/templates/course.html
Target Date: TBD – will be finalized after a successful MFE rollout and stakeholder communication.
Replacement
The deprecated pages are being replaced with MFEs hosted under the frontend-app-catalog project, providing:
- Modern client-side rendering (React + TypeScript)
- Slot-based extensibility
- Fully responsive and accessible UI
- Data fetching via React Query
- Theming with Paragon
Key Replacement Endpoints
/api/mfe_config/v1— Returns MFE common or MFE specific config/search/course_discovery/— Extended to support:homepage_course_max(limit results)enable_course_sorting_by_start_dateorg_image_urlfor branding
Deprecation
Deprecation will be managed via a configuration parameter ENABLE_CATALOG_MICROFRONTEND, default value is False
Legacy views conditionally redirect to the MFE based on flag values.
Migration
There are no required actions for learners or course authors.
System integrators should:
- Update Tutor config to support MFE routing and registration.
- Migrate any custom links to use MFE paths when flags are enabled.
Backend configuration changes (according the Catalog About Page API Design)
ENABLE_COURSE_SORTING_BY_START_DATE
Exposed as a new MFE_CONFIG field, can be configured from Site Configuration with a backoff value of settings.FEATURES["ENABLE_COURSE_SORTING_BY_START_DATE"]homepage_overlay_html
Deprecated on the backend, FPS (plugin slot) should be created as a replacement.
Operators can use the FPS to customize the Catalog MFE.show_homepage_promo_video
Backend configuration is Deprecated. No settings is exposed via MFE Configuration API.
The functionality provided by the show_homepage_promo_video switch (displaying the homepage without a promotional video) will be covered by checking thehomepage_promo_video_youtube_idvalue and the plugin slot.homepage_promo_video_youtube_id
Exposed as a new MFE_CONFIG field, can be configured from Site Configuration with no backoff value from settings.
Hard-coded backoff value is "your-youtube-id".show_partnersFully deprecated.homepage_course_max
Exposed as a newHOMEPAGE_COURSE_MAXfield in MFE_CONFIG can be configured from Site Configuration with a backoff value of settings.HOMEPAGE_COURSE_MAXsidebar_html_enabledDeprecated as a backend configuration. Can be configured via an appropriate FPS (plugin slot).course_about_show_social_links
Deprecated as a backend configuration. Can be configured via an appropriate FPS (plugin slot).course_about_twitter_account
Exposed as a new MFE_CONFIG field, can be configured from Site Configuration with a backoff value of settings.FEATURES["PLATFORM_TWITTER_ACCOUNT"]is_cosmetic_price_enabled
Exposed as a new MFE_CONFIG field with a backoff value of settings.FEATURES["ENABLE_COSMETIC_DISPLAY_PRICE"]
12 .courses_are_browsable
Deprecated and exposed as a newNON_BROWSABLE_COURSESfield in MFE_CONFIG
Defaulted tonot settings.FEATURES.get("COURSES_ARE_BROWSABLE")enable_course_discovery
Deprecated and exposed as a newENABLE_COURSE_DISCOVERYfield in MFE_CONFIG
with a backoff value of settings.FEATURES["ENABLE_COURSE_DISCOVERY"]
-
course_discoveryAPI enhancements include:- Sorting and result limiting
- Organization branding support
-
Redirect logic built into legacy views
-
Link generation updated in:
common/djangoapps/util/course.pyCourseViewMetadataSerializer
Home page
- The homepage_promo_video_youtube_id value is now provided via Site Configuration as HOMEPAGE_PROMO_VIDEO_YOUTUBE_ID.
- The functionality previously controlled by the show_homepage_promo_video switch (determining whether to display the homepage with or without a promotional video) is now handled by checking the HOMEPAGE_PROMO_VIDEO_YOUTUBE_ID value and the frontend plugin-slots configuration.
- The ENABLE_COURSE_DISCOVERY ENABLE_COURSE_SORTING_BY_START_DATE expose as MFE_CONFIG fallback.
- The text overlay section is rendered conditionally:
- If HOMEPAGE_OVERLAY_HTML is available from plugin-slots, that content is displayed.
- Otherwise, the text from legacy index_overlay (including title and subtitle) is rendered as a fallback.
Frontend
- MFE built using
frontend-template-application - Slot-based architecture:
home_banner_slot,home_course_list_slot, etc.
- Handles anonymous, enrolled, and unenrolled states
- Uses Paragon for consistent theming
- Fully internationalized and responsive
Task List
- Create config flag
ENABLE_CATALOG_MICROFRONTEND - Extend
/api/mfe_config/v1to support all required configuration settings with back-off values - Add new edx-search endoint
unstable/v0/course_list_search/to support multivalue faceted - Implement redirect logic in legacy views
- Update
common/djangoapps/util/course.pyfor dynamic URL generation - Update Tutor MFE registration and routing
- Add unit/integration tests for dual-mode logic
- Build and integrate
frontend-app-cataloginto release process
Activity
MoisesGSalas commentedon Jun 23, 2025
This might be a little bit off-topic, and I'm not against the deprecation, but how many additional MFEs would be needed to phase out all the legacy frontend?
My main concern is from the POV of a deployer. Building MFEs using Tutor can become resource intensive, specially when the number of MFEs increases. If we are expecting 4 or more additional MFEs it can become a real problem.
SergiiKalinchuk commentedon Jul 2, 2025
@MoisesGSalas Thank you for raising this important point.
You're absolutely right that the number of MFEs has deployment implications, especially for resource-constrained environments using Tutor.
In the scope of this deprecation, we are introducing only one new MFE:
frontend-app-catalogWe’re also actively engaging with the community to explore build-time and runtime optimizations (e.g., pre-built containers, shared base images, selective MFE builds) to help ease this burden.
Your feedback is helpful in prioritizing this work—thank you again.
sarina commentedon Aug 12, 2025
@MoisesGSalas there shouldn't be more MFEs required for the remaining legacy conversions, at least in my mind, beyond this one. The Instructor Dash conversion will be within the frontend-app-learning MFE and the new administrator console should be in the authoring MFE. We're trying to balance keeping things logically separated vs the overhead of new MFEs. I could be wrong, but I think we're quite close on legacy frontend conversions.
robrap commentedon Sep 4, 2025
[inform] 2U uses course about in our Edge environment. I did not do further review, but simply noting that we do have work to do before breaking changes land. FYI: @deborahgu @dianakhuang
dianakhuang commentedon Oct 30, 2025
@sarina I know there's been lots of work being done on this. Could you see if the tasklist on the ticket is up to date and if we can still target this for
transition unblockedsoon?sarina commentedon Oct 30, 2025
I'm asking the project team to look into this.
cmltaWt0 commentedon Oct 31, 2025
@sarina @dianakhuang I've updated the Task link and marked the completed items.
7 remaining items
mboisson commentedon Jan 8, 2026
what about for tutor users ?
feanil commentedon Jan 8, 2026
@mboisson tutor users can just use the tutor plugin that's provided and the MFE or wait till Verawood when the MFE will be on by default in Tutor.
feanil commentedon Jul 31, 2026
@brian-smith-tcril just confirming, now that Verawood is out, the work to drop the legacy UI is unblocked is that right? Are there folks resourced to do this work or do we need to find folks to do this?
brian-smith-tcril commentedon Aug 4, 2026
@feanil yes, I believe the work to drop the legacy UI is unblocked.
Looking at #38936 nothing stands out in "Build a replacement" or "Needs discovery" that would go into
frontend-app-catalog.brian-smith-tcril commentedon Aug 27, 2026
When reviewing overhangio/tutor-mfe#328 I noticed the
ENABLE_CATALOG_MICROFRONTENDtoggle is still set to defaultFalse.openedx-platform/lms/envs/common.py
Lines 642 to 649 in bae59d9
I assume removing just the toggle without actually removing any of the legacy frontend code wouldn't be ideal, so I'm thinking in the immediate-term a quick PR flipping the default to
Truewould be good.sarina commentedon Aug 28, 2026
Wait, I'm confused @brian-smith-tcril - I thought we had enabled the catalog MFE as the default in Verawood? At least that's what you told me on Aug 6th 😅
brian-smith-tcril commentedon Aug 28, 2026
Tutor MFE sets
ENABLE_CATALOG_MICROFRONTENDtoTruewhen the catalog MFE exists/is enabled, and Tutor MFE pulls/builds/hosts/enables the catalog MFE by default.This is a "the default lives in Tutor, not in platform" issue.
sarina commentedon Aug 28, 2026
NO 😭
robrap commentedon Aug 28, 2026
[idea] As part of BTR process, doing an out-of-the-box Tutor deployment and out-of-the-box non-Tutor deployment and diffing all settings (or all boolean toggle settings), to ensure that any diff is wanted/explained.
feanil commentedon Sep 10, 2026
One thing to make sure is captured in the removal scope: the
ENABLE_CATALOG_MICROFRONTENDwaffle flag itself should be removed as part of the cleanup, not just left defaulting to a value. Verified on master 2026-09-10 that the platform default is stillFalse, so vanilla installs serve the legacy pages by default and only get the MFE because Tutor sets the flag. When the legacy templates (index.html,courses.html,course.html,course_about.html,course_about_sidebar_header.html) come out, the flag and its redirect logic should go with them so the MFE becomes the unconditional experience.Tracking in #38936.
feanil commentedon Oct 15, 2026
Just flipping the default turns out to be more complex because there is a lot of testing relying on the old catalog and about pages still. I think we just need to complete the full cleanup here which will hopefully be faster than we previously expected. Having the default and test settings differ was also considered but is probably not a good idea.