[DEPR]: Deprecation of Legacy Home, Course Catalog, and Course About Pages in Favor of MFE Implementations

[SergiiKalinchuk]

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.html
• lms/templates/courseware/courses.html
• lms/templates/courseware/course_about.html
• lms/templates/courseware/course_about_sidebar_header.html
• lms/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_date
  • org_image_url for 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)

1. 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"]
2. 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.
3. 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 the homepage_promo_video_youtube_id value and the plugin slot.
4. 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".
5. show_partners Fully deprecated.
6. homepage_course_max
   Exposed as a new HOMEPAGE_COURSE_MAX field in MFE_CONFIG can be configured from Site Configuration with a backoff value of settings.HOMEPAGE_COURSE_MAX
7. sidebar_html_enabledDeprecated as a backend configuration. Can be configured via an appropriate FPS (plugin slot).
8. course_about_show_social_links
   Deprecated as a backend configuration. Can be configured via an appropriate FPS (plugin slot).
9. 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"]
10. 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 new NON_BROWSABLE_COURSES field in MFE_CONFIG
    Defaulted to not settings.FEATURES.get("COURSES_ARE_BROWSABLE")
11. enable_course_discovery
    Deprecated and exposed as a new ENABLE_COURSE_DISCOVERY field in MFE_CONFIG
    with a backoff value of settings.FEATURES["ENABLE_COURSE_DISCOVERY"]

• course_discovery API enhancements include:

  • Sorting and result limiting
  • Organization branding support

• Redirect logic built into legacy views

• Link generation updated in:

  • common/djangoapps/util/course.py
  • CourseViewMetadataSerializer

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/v1 to 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.py for dynamic URL generation
• Update Tutor MFE registration and routing
• Add unit/integration tests for dual-mode logic
• Build and integrate frontend-app-catalog into release process

Links

• https://discuss.openedx.org/t/deprecation-of-legacy-home-course-catalog-and-course-about-pages-in-favor-of-mfe-implementations/16008

[MoisesGSalas]

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]

@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-catalog

We’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]

@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.