You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: OEP-65 reframe around build-time shell architecture
Reframe OEP-65 to match the frontend-base reference implementation:
build-time composition of apps into sites via a shared shell, replacing
the dropped runtime module federation approach. Rework the glossary and
ADRs to the new vocabulary (App, App Repository, Site, Shell, Shell
Architecture, Slot, Widget), rename ADR-0003 to "Frontend Sites", remove
the obsolete federation diagrams, and fix the "Composability" label typo.
Co-Authored-By: Claude <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-library.rst
+32-27Lines changed: 32 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
-
.. _Create a unified platform repository:
1
+
.. _Create a unified platform library:
2
2
3
-
Create a unified platform repository
4
-
####################################
3
+
Create a unified platform library
4
+
#################################
5
5
6
6
Status
7
7
******
@@ -11,24 +11,24 @@ Accepted
11
11
Summary
12
12
*******
13
13
14
-
This ADR proposes combining a number of repositories into a single, unified frontend platform library as a migration strategy for implementing :ref:`OEP-65 <OEP-65 Frontend Composibility>`. This library is named `frontend-base <https://github.com/openedx/frontend-base>`_.
14
+
This ADR proposes combining a number of repositories into a single, unified frontend platform library as a migration strategy for implementing :ref:`OEP-65 <OEP-65 Frontend Composability>`. This library is named `frontend-base <https://github.com/openedx/frontend-base>`_.
15
15
16
16
Context
17
17
*******
18
18
19
-
OEP-65 proposes adopting webpack:term:`module federation` for Open edX:term:`micro-frontends <Micro-frontend>` (MFEs) as a means to enable :term:`runtime module loading` and :term:`shared dependencies` in the :term:`Open edX frontend`. The OEP lays out a series of changes necessary to enable these capabilities, which it refers to as building a "reference implementation" of runtime module loading and shared dependencies.
19
+
OEP-65 proposes building the:term:`Open edX Frontend` from independently developed:term:`apps <App>`, all composed into a shared :term:`Shell` in one or more :term:`Sites <Site>`, as a means to enable build-time composability and :term:`shared dependencies <Shared Dependencies>`. The OEP lays out a series of changes necessary to enable these capabilities, which it refers to as building a "reference implementation".
20
20
21
-
This reference implementation is effectively a new underlying architecture for our frontend. This ADR refers to this new architecture as the :term:`module architecture`, as opposed to the historical :term:`micro-frontend architecture` that has existed prior to OEP-65.
21
+
This reference implementation is effectively a new underlying architecture for our frontend. This ADR refers to this new architecture as the :term:`Composable Architecture`, as opposed to the historical :term:`Micro-frontend Architecture` that has existed prior to OEP-65.
22
22
23
-
The bulk of the work to build OEP-65's reference implementation is related to the *library repositories* that MFEs depend on:
23
+
The bulk of the work to build OEP-65's reference implementation is related to the libraries that MFEs (as opposed to :term:`Apps <App>`) currently depend on:
24
24
25
25
* frontend-build
26
26
* frontend-platform
27
27
* frontend-plugin-framework
28
28
* frontend-component-header
29
29
* frontend-component-footer
30
30
31
-
It will also involve the creation of a new :term:`Shell` to initialize the frontend at runtime and load existing MFEs as :term:`modules <Module>`. Prior to this decision, we might have considered putting the shell in its own repository as well:
31
+
It will also involve the creation of a new :term:`Shell` to initialize the frontend and compose :term:`apps <App>` into a :term:`Site`. Prior to this decision, we might have considered putting the shell in its own repository as well:
32
32
33
33
* frontend-app-shell
34
34
@@ -37,12 +37,12 @@ There are several related concerns which influence our strategy for migrating th
37
37
Significant API changes
38
38
=======================
39
39
40
-
The creation of the shell and the move toward using:term:`plugins <Plugin Module>` and module federation is expected to significantly change the API surface across our various libraries.
40
+
The creation of the shell and the move toward composing:term:`apps <App>` is expected to significantly change the API surface across our various libraries.
41
41
42
42
``frontend-platform``
43
43
---------------------
44
44
45
-
As the shell takes responsibility for much of what ``frontend-platform`` provides to MFEs in the micro-frontend architecture, many of the APIs it exposes will become internal to the shell. We will also likely need to add new APIs for interactions between the shell and modules.
45
+
As the shell takes responsibility for much of what ``frontend-platform`` provides to MFEs in the :term:`Micro-frontend Architecture`, many of the APIs it exposes will become internal to the shell. We will also likely need to add new APIs for interactions between the shell and apps.
46
46
47
47
``frontend-build``
48
48
------------------
@@ -57,7 +57,7 @@ The header and footer will be owned by the shell and need not be libraries any m
57
57
``frontend-plugin-framework``
58
58
-----------------------------
59
59
60
-
We expect ``frontend-plugin-framework`` to be folded into ``frontend-platform`` to unify the two, as they will be intimately tied to each other going forward. We'll also be creating new APIs around loading plugins that support module federation.
60
+
We expect ``frontend-plugin-framework`` to be folded into ``frontend-base`` to unify it with the rest of the runtime library, as they will be intimately tied to each other going forward. We'll also be creating new APIs around composing :term:`widgets <Widget>` into :term:`slots <Slot>`.
61
61
62
62
``frontend-app-*`` Repositories
63
63
-------------------------------
@@ -77,59 +77,58 @@ We also feel the need to continue to modernize our library repositories by adopt
77
77
Deprecation of the micro-frontend architecture
78
78
==============================================
79
79
80
-
As described in OEP-65, we're migrating from the :term:`micro-frontend architecture`, where each MFE is a standalone, independently deployed app, to a :term:`module architecture` where the MFEs are modules loaded into a common :term:`Shell` which owns the header, footer, initialization, and shared dependencies.
80
+
As described in OEP-65, we're migrating from the :term:`Micro-frontend Architecture`, where an MFE is a standalone, independently deployed site, to a :term:`Composable Architecture` where the MFEs become :term:`apps <App>` composed into a common :term:`Shell` which owns the header, footer, initialization, and shared dependencies.
81
81
82
-
One way or another, this is a paradigm shift that will involve breaking changes and migration work on behalf of community members. We would like to provide a clear a path forward for operators, developers, and maintainers to adopt the module architecture. We believe that a clean break and a cohesive and clear platform for modules is more approachable than a more granular deprecation of certain features and code in the existing library repositories.
82
+
One way or another, this is a paradigm shift that will involve breaking changes and migration work on behalf of community members. We would like to provide a clear a path forward for operators, developers, and maintainers to adopt the module architecture. We believe that a clean break and a cohesive and clear platform for modules is more approachable than a more granular deprecation of certain features and code in the existing libraries.
83
83
84
84
Decision
85
85
********
86
86
87
-
We will migrate our existing foundational library repositories to the new module architecture by creating a new, unified platform library - `frontend-base <https://github.com/openedx/frontend-base>`_ - to act as the primary dependency of frontend modules in the module architecture.
87
+
We will migrate our existing foundational libraries to the new :term:`Composable Architecture` by creating a unified platform library - `frontend-base <https://github.com/openedx/frontend-base>`_ - to act as the primary dependency of frontend :term:`apps <App>`.
88
88
89
-
This library will include the parts of ``frontend-build``, ``frontend-platform``, ``frontend-plugin-framework``, ``frontend-component-header``, and ``frontend-component-footer``, as well as the new shell application that make sense for the module architecture, along with new features and capabilities necessary to implement our vision. We will also opportunistically fold in ``eslint-config``, which sees very little development but is its own source of dependency management overhead.
89
+
This library will include the relevant features of ``frontend-build``, ``frontend-platform``, ``frontend-plugin-framework``, ``frontend-component-header``, and ``frontend-component-footer``, as well as a new :term:`shell <Shell>` application, along with new features and capabilities necessary to implement the vision in OEP-65. We will also opportunistically fold in ``eslint-config``, which sees very little development but is its own source of dependency management overhead.
90
90
91
91
This new library will be released as one npm package with the following responsibilities.
92
92
93
93
Runtime library
94
94
===============
95
95
96
-
The library will export a subset of the APIs in ``frontend-platform``, along with ``frontend-plugin-framework``'s API and new APIs specific to the module architecture and the shell. This library will be a dependency of MFEs, as ``frontend-platform`` has been historically.
96
+
The library will export a subset of the APIs in ``frontend-platform``, along with ``frontend-plugin-framework``'s API and new APIs specific to the composable architecture and the shell. This library will be a (peer) dependency of frontend apps.
97
97
98
98
Development tool configurations
99
99
===============================
100
100
101
101
The library will provide base ESLint, Jest, TypeScript, and Webpack configurations. ESLint, Jest, and TypeScript will be similar to what ``frontend-build`` provides.
102
102
103
-
The webpack configurations will support a variety of build targets for the new module architecture, as well as application MFE configurations to enable us to migrate to the new unified platform library in a backwards compatible way. The new build targets include:
103
+
The webpack configurations will support a variety of build targets for the new :term:`Composable Architecture`, as well as app configurations to enable us to migrate to the new unified platform library in a backwards compatible way. The new build targets include:
104
104
105
-
* A production configuration suitable for deploying the MFE's modules to be consumed via module federation.
106
-
* A release configuration which will package those same modules to be released as an npm package for use as direct plugins.
107
-
* A development server configuration to serve the MFE's modules to be consumed locally via module federation, complete with hot module reloading.
108
-
* A development server configuration to serve the MFE's modules inside a shell as direct plugins.
105
+
* A production configuration suitable for building an :term:`App` into a deployable :term:`Site`.
106
+
* A release configuration which packages an :term:`App Repository`'s :term:`apps <App>` as an npm package for build-time inclusion in a :term:`Site`.
107
+
* A development server configuration to serve an :term:`App` inside a :term:`Shell`, complete with hot module reloading.
109
108
110
109
These webpack configurations will be exposed via a function like ``frontend-build``'s '``createConfig`` so that they can be modified and extended as necessary by the MFEs.
111
110
112
111
CLI tool
113
112
========
114
113
115
-
Similar to ``fedx-scripts`` provided by ``frontend-build``, the ``frontend-base`` library will provide a CLI tool. This tool will expose commands to run the above webpack configurations, as well as other commands related to frontend projects. The rationale and details of frontend projects and these CLI commands are the subject of a future ADR.
114
+
Similar to ``fedx-scripts`` provided by ``frontend-build``, the ``frontend-base`` library will provide a CLI tool. This tool will expose commands to run the above webpack configurations, as well as other commands related to building and developing :term:`Sites <Site>`. The rationale and details of these CLI commands are the subject of a future ADR.
116
115
117
116
Consequences
118
117
************
119
118
120
-
This approach allows us to treat the :term:`module architecture` as an independent effort, as opposed to a set of features that need to fit in with the existing :term:`micro-frontend architecture`. We greatly reduce or eliminate the risk of regressions in libraries that the entire community relies on while we build a replacement which resembles and borrows code from them, but is otherwise significantly different. This division makes it explicitly clear which features are used by the old architecture and which are used by the new one.
119
+
This approach allows us to treat the :term:`Composable Architecture` as an independent effort, as opposed to a set of features that need to fit in with the existing :term:`Micro-frontend Architecture`. We greatly reduce or eliminate the risk of regressions in libraries that the entire community relies on while we build a replacement which resembles and borrows code from them, but is otherwise significantly different. This division makes it explicitly clear which features are used by the old architecture and which are used by the new one.
121
120
122
-
Further, it means we can migrate to the new architecture in a backwards compatible way by atomically migrating MFEs to use the new `frontend-base <https://github.com/openedx/frontend-base>`_ library, again, without running the risk of destabilizing existing libraries with multiple breaking changes over time.
121
+
Further, it means we can migrate to the new architecture in a backwards compatible way by atomically porting MFEs to:term:`Apps` that use the new `frontend-base <https://github.com/openedx/frontend-base>`_ library, again, without running the risk of destabilizing existing libraries with multiple breaking changes over time.
123
122
124
123
We believe this is a reasonable migration strategy given the generally low rate of feature development in these libraries. We incur incrementally more maintenance burden in the interim while both sets of libraries exist, and a level of effort in absorbing any features or bug fixes in the existing libraries. However, we believe that will be offset by an increase in development velocity for the new library, a clearer deprecation process, less risk of regressions in existing code, and an easier mental model of how the architecture is changing.
* Updated terminology to match the ``frontend-base`` reference implementation: build-time composition of :term:`apps <App>` into :term:`Sites <Site>` via the :term:`Shell`, in place of runtime module federation. Renamed "Module Architecture" to :term:`Composable Architecture`.
146
+
* Retitled from "Create a unified platform repository" to "Create a unified platform library" (and renamed the file accordingly), since ``frontend-base`` is a library.
0 commit comments