Deprecation of Legacy Home, Course Catalog, and Course About Pages in Favor of MFE Implementations

Summary

This issue proposes the deprecation of legacy Django-based pages in the LMS for the following views:

  • Home page (/)
  • Course Catalog (/courses)
  • Course About page (/courses/<course_id>/about)

These pages will be replaced with new Micro-Frontend (MFE) applications, built with modern technologies (React, TypeScript, React Query, Paragon). The transition enables a more modular, scalable, and customizable approach for LMS UI development.

The MFE pages will be enabled conditionally using waffle flags, with a fallback to legacy views if the corresponding flags are disabled.

Target Date for Removal

TBD – pending successful MFE rollout and communication per OEP-21.

Motivation & Context

Historically, these pages were rendered server-side using Django templates. The corresponding APIs returned pre-rendered HTML with full template context, making it difficult to modularize or reuse individual data blocks.

The new implementation decouples rendering from data delivery:

  • Non-course-specific configuration (such as site name, theming, links, and feature toggles) will now be exposed via the endpoint:

GET /api/mfe_config/v1/

  • Course data (used on catalog and homepage) will be fetched from:

GET /search/course_discovery/

The /search/course_discovery/ endpoint has been extended to support:

  • Course sorting by start date
  • Optional course count limitation via query parameters
  • Organization image links

This modular approach facilitates MFE-based rendering and improves frontend responsiveness and composability.

Acceptance Criteria

  • Waffle flags for all three pages are created in the branding app and exposed via a dedicated config API
  • Redirect logic is conditionally applied based on the new flags
  • Legacy views remain accessible if waffle flags are disabled
  • /api/branding/waffle-flag-config/ returns all three waffle flags for frontend use
  • Link generation logic in common/djangoapps/util/course.py and CourseViewMetadataSerializer respects the waffle flag status and redirects users to appropriate MFE paths
  • Tutor configuration is updated to support MFE registration, routing, and waffle flag initialization
  • Unit tests and integration tests are updated to reflect dual-mode behavior (MFE + legacy fallback)

Feature Flags

Django FEATURES Setting:

FEATURES = {
  'ENABLE_CATALOG_MICROFRONTEND': True,
}

Waffle Flags (created in lms.djangoapps.branding):

Flag Name Description Default
new_catalog_mfe.use_new_index_page Enables MFE version of LMS Home page False
new_catalog_mfe.use_new_catalog_page Enables MFE version of Course Catalog page False
new_catalog_mfe.use_new_course_about_page Enables MFE version of Course About page False

These are exposed to frontend clients via a new unauthenticated public endpoint:

GET /api/branding/waffle-flag-config/

Implementation Notes

Backend Changes

1. MFE Config API

Endpoint: /api/mfe_config/v1/
Purpose: Provides UI configuration that was previously rendered server-side, such as:

  • enable_course_sorting_by_start_date: boolean
  • homepage_overlay_html: string
  • show_partners: boolean
  • show_homepage_promo_video: boolean
  • homepage_course_max: integer
  • homepage_promo_video_youtube_id: string

2. Course Discovery API Enhancements

Endpoint: /search/course_discovery/
Extended to support:

  • org_image_url field for organization branding
  • homepage_course_max query param to limit result count
  • enable_course_sorting_by_start_date for sorting

3. Redirect Logic

Legacy views check the appropriate waffle flag and issue a redirect to the MFE if the flag is active.

4. Link Generation Updates

Modules that generate links to the Home page, Course Catalog page and Course About page should be gradually modified to dynamically generate MFE URLs based on the waffle flag status.

Frontend Changes

1. MFE Created

  • frontend-app-catalog

using the frontend-template-application.

2. Routing & Slots

Routing is aligned with legacy URLs. Slots are introduced to support plugin extensibility:

Index page

  • home_banner_slot for the banner section.
  • home_course_list_slot for the course list section.
  • home_course_card_slot for the course card.

Course About page

  • course_intro_content_slot for the content part of “Intro” section.

  • course_intro_action_row_slot for the action button in the “Intro” section.

  • course_intro_media_slot for the image/video block of “Intro” section.

  • course_overview_container_slot for the content part of content/overview and course sidebar.

  • course_overview_slot for rendering course content/overview.

  • course_sidebar_slot for rendering course sidebar content.

3. Paragon & React Query

  • All MFEs use Paragon for UI consistency
  • Data fetching via React Query
  • Components built with responsiveness and accessibility in mind

4. Course About Page Behavior

  • Handles auth states:
    • Anonymous users âžś Redirect to login
    • Enrolled users âžś Redirect to /learning/course/<course_id>/home
    • Non-enrolled âžś Enroll & redirect to /learner-dashboard/
  • Displays dynamic media block (image or video)
  • Responsive UI with loading spinners, alerts, and error handling

Code Locations Affected

Backend:

  • lms/templates/index.html
  • common/djangoapps/util/course.py
  • lms/djangoapps/mobile_api/course_info/serializers.py
  • lms/djangoapps/branding/views.py
  • lms/templates/courseware/course_about_sidebar_header.html

Frontend:

  • frontend-app-catalog (and 3 pages: Index, Course catalog, Course about)
  • tutor-mfe (for MFE registration and waffle flag support)

Related Docs & Links

Hello @SergiiKalinchuk. Welcome and thank you. From a process perspective (OEP-21), most of the details will be added to the DEPR issue and this page will be a light wrapper that does the announcing of that ticket. Since you are proposing a deprecation in edx-platform, you would use https://github.com/openedx/edx-platform/issues, choose “New Issue”, and choose the DEPR template. Let me know if you have any questions.

1 Like

@SergiiKalinchuk Could you please follow OEP-21 as Robert describes above, making an issue on the edx-platform repo with these details, and editing this post to be the brief announcement that is described within OEP-21’s “deprecation/removal template”? Thank you!

Thank you @robrap and @sarina , I will do as you suggest

@SergiiKalinchuk I made this PR to clarify the process: docs: Clarify that a 'ticket' in OEP-21 is a DEPR-type GitHub ticket by sarina · Pull Request #711 · openedx/open-edx-proposals · GitHub

Here is the ticket in edx-platform repository: [DEPR]: Deprecation of Legacy Home, Course Catalog, and Course About Pages in Favor of MFE Implementations · Issue #36785 · openedx/edx-platform · GitHub

If possible, please let me keep the extended version here, as not all information fit into the GitHub DEPR Ticket template

The DEPR Issue in Github is definitely where you want to capture all the details. If the template is imperfect, and you need a new subheader to capture additional details, you can do that. Or add them to a comment. But we want all the information to be on the ticket. Some people will never read this, because usually it just gets people to the ticket/issue.

@SergiiKalinchuk kindly edit or add comments to [DEPR]: Deprecation of Legacy Home, Course Catalog, and Course About Pages in Favor of MFE Implementations · Issue #36785 · openedx/edx-platform · GitHub to capture all information in this post, and then edit this post to simply be the template shown in OEP-21. Your post should be as follows:

Hello.

We plan to deprecate and remove the Legacy Home, Course Catalog, and Course About pages in favor of an MFE implementation.

Please read [DEPR]: Deprecation of Legacy Home, Course Catalog, and Course About Pages in Favor of MFE Implementations · Issue #36785 · openedx/edx-platform · GitHub for more information and to post any questions or comments. The proposed deadline for comments before acceptance is 2025-06-07.

Once the ticket is accepted, removal won’t happen until after Ulmo is cut in mid-October, 2025.

After acceptance, all future notifications around removal will only be posted to the GitHub issue, so be sure to watch that issue if you want further updates.

Thank you.