Frontend Apps

Frontend Apps#

Status#

Accepted

Summary#

This ADR describes what frontend apps are in the Composable Architecture, and how the frontend-app-* repositories are organized around them. It also summarizes, at a high level, how existing micro-frontends become apps.

Context#

OEP-65 proposes composing the Open edX Frontend from independently developed apps at build time - into one or more Sites built by a shared Shell - as a means to enable build-time composability and shared dependencies. The OEP lays out a series of changes necessary to enable these capabilities, which it refers to as building a “reference implementation”.

This reference implementation is effectively a new underlying architecture for our frontend. This ADR refers to this new architecture as the Composable Architecture, as opposed to the historical Micro-frontend Architecture that has existed prior to OEP-65.

The frontend-app-* repositories are central to this architecture: rather than being independently deployed applications, they become the home of the apps that a Site composes. This ADR defines what an app is and how these repositories are organized, and summarizes how existing micro-frontends migrate to become apps.

Please see Create a unified platform library for more information on frontend-base.

Decision#

The fundamental unit of the frontend is the App.

What an App is#

An App is a self-contained part of the Open edX Frontend that is composed into a Site at build time. An app usually represents a well-bounded area of the UI - such as courseware, the login page, or account settings - and typically owns one or more routes. Beyond its routes, an app can contribute:

  • Widgets - components rendered into a Slot, whether its own, another app’s, or the Shell’s. The header and footer, for instance, can be overridden with alternate implementations via widgets, and new tabs on the course home are widgets.

  • Services - implementations of platform services such as logging or analytics.

  • Scripts - arbitrary scripts attached to the page.

Crucially, there is no separate “plugin” concept. What other frameworks would split into “applications” and “plugins” are, in the Composable Architecture, all just apps: an app that contributes a top-level area of the UI and an app that only contributes a Widget to another app’s Slot are the same kind of thing.

App Repositories#

Apps live in App Repositories. These repositories:

  • Are always named frontend-app-*, regardless of what their apps do. This is the single naming convention for frontend application code going forward.

  • Provide one or more apps. Most provide a single app, but some provide several related apps centered on a domain (learning, authoring, authn, etc.) that share code and dependencies. The question of which apps belong in which repositories, and where the right boundaries are, is beyond the scope of this ADR.

Because plugins are apps, components previously built as frontend-plugin-framework plugins become apps, and repositories previously named frontend-plugin-* should be renamed to frontend-app-*. There is no longer a meaningful distinction between a “plugin repository” and an “app repository”.

Consequences#

Migration#

Existing micro-frontends (and frontend-plugin-* repositories) will need to migrate to become App Repositories built on frontend-base. Here are a few essential examples of what needs to happen during the conversion:

  • The shell takes over the foundations. Apps no longer initialize frontend-platform or render their own header and footer; the Shell provides application initialization, layout, branding, and services. Apps drop the foundational libraries this replaces - frontend-build, frontend-platform, frontend-plugin-framework, frontend-component-header, frontend-component-footer, and @edx/brand - in favor of frontend-base.

  • Shared dependencies become peer dependencies. The dependencies the shell provides - React, Paragon, React Router, Redux, and so on - become peer dependencies of the App Repository rather than direct ones, so that a Site resolves them to a single shared version at build time.

  • Configuration moves to the Site. App Repositories no longer carry environment-specific .env or env.config files; configuration lives in a Site Config (see Frontend Sites).

  • New tooling. The openedx CLI from frontend-base replaces fedx-scripts from frontend-build, and App Repositories are published to npm so that Sites can consume their apps.

The complete, step-by-step migration process will be documented in a Frontend App Migration How To in the frontend-base repository.

As we adopt frontend-base, the libraries it replaces will undergo their own deprecation processes (via the DEPR process), coordinated with the migration of the micro-frontends included in Open edX releases. After that deprecation, the Micro-frontend Architecture will cease to be supported.

Unsupported Customizations#

The Micro-frontend Architecture took an extreme approach to “flexibility”, allowing MFEs to diverge from each other in a variety of ways as described in OEP-65. As a result, in the process of migrating them to the Composable Architecture, there could be unforeseen refactoring that may need to happen in some MFEs that don’t map into apps well, or which have customizations that aren’t supported by the Shell. While we hope to provide enough extensibility mechanisms to reduce the need for forking or hacky customizations, there will be customizations we haven’t anticipated, which the community will need to work around or find ways to support.

Consistent Dependency Versions#

Addressing our lack of dependency version consistency is one of the primary drivers of OEP-65.

The shell will support specific version ranges of shared dependencies (such as React, Paragon, or React Router). All apps composed into the shell’s Site will be expected to use (or at least be compatible with) that version. We intend to create lock-step version consistency of shared dependencies across all apps in the platform. We envision each Open edX release supporting a particular major version of each shared dependency.

References#

Change History#

2024-08-28#

2024-09-13#

  • Updating the language use to match and reference the frontend glossary.

2026-07-13#

  • Rewritten and generalized to match the frontend-base reference implementation, and retitled from “Frontend App Migrations” to “Frontend Apps”. The Decision now defines what an App is; the migration is summarized under Consequences, with the details deferred to the migration how-to in frontend-base.