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
Copy file name to clipboardExpand all lines: oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst
+69-54Lines changed: 69 additions & 54 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
-
OEP-65 Frontend App Migrations
2
-
##############################
1
+
Frontend App Migrations
2
+
#######################
3
3
4
4
Status
5
5
******
@@ -9,7 +9,7 @@ Accepted
9
9
Summary
10
10
*******
11
11
12
-
This ADR describes a migration path and simplified repository organization for the frontend-app-* repositories that is compatible with the shell provided by frontend-base as well as module federation and frontend projects.
12
+
This ADR describes a migration path and simplified repository organization for the frontend-app-* repositories that is compatible with the shell provided by frontend-base, module federation, and frontend projects.
13
13
14
14
Context
15
15
*******
@@ -18,87 +18,102 @@ OEP-65 proposes adopting webpack module federation for Open edX micro-frontends
18
18
19
19
This reference implementation is effectively a new underlying architecture for our frontend. This ADR refers to this new architecture as the "module" architecture, as opposed to the historical "micro-frontend" architecture that has existed prior to OEP-65.
20
20
21
-
As part of this paradigm shift, our frontend-app-* repositories (MFEs) will need to be migrated to work with frontend-base. Of particular note, this will require the repositories to:
21
+
As part of this paradigm shift, our ``frontend-app-*`` repositories (MFEs) will need to be migrated to work with `frontend-base<https://github.com/openedx/frontend-base>`_. Of particular note, this will require the repositories to:
22
22
23
23
* Adopt a new set of build/development CLI helpers
24
24
* Use the shell to provide the header, footer, and runtime initialization code, amongst other things.
25
-
* Organize their code into loosely-coupled top-level components, which we'll call *modules*.
25
+
* Organize their code into loosely-coupled top-level components, which we'll call *application modules*.
26
26
27
-
As we adopt frontend-base, the libraries it replaces will undergo their own deprecation processes, which will need to coordinate with the migration of micro-frontends included in Open edX releases. After that deprecation, the micro-frontend architecture will cease to be supported.
27
+
As we adopt ``frontend-base``, the libraries it replaces will undergo their own deprecation processes, which will need to coordinate with the migration of micro-frontends included in Open edX releases. After that deprecation, the micro-frontend architecture will cease to be supported.
28
28
29
29
Decision
30
30
********
31
31
32
-
Each of our frontend-app-* repositories will migrate from being an independent "micro-frontend application" to being a library of modules that can be loaded into a common Shell, deployed as a Site. We will document the migration process in detail. At a high level:
32
+
Each of our ``frontend-app-*`` repositories will migrate from being an independent "micro-frontend application" to being a library of modules that can be loaded into a common Shell, deployed as a Site. These are called *application module libraries*. We will document the migration process in detail. At a high level, this will involve the following changes.
33
33
34
-
* They will be deployable via a variety of methods, all of which will use the Shell.
35
-
* They will be deployable together or independently.
36
-
* They will no longer contain .env or env.config files for any environment, including Devstack and Tutor.
37
-
* They will cease to use the following libraries in favor of frontend-base:
34
+
New Deployment Methods
35
+
======================
38
36
39
-
* @openedx/frontend-build
40
-
* @edx/frontend-plaform
41
-
* @openedx/frontend-plugin-framework
42
-
* @edx/frontend-component-header
43
-
* @edx/frontend-component-footer
44
-
* @openedx/frontend-slot-footer
45
-
* @edx/brand
46
-
* core-js
47
-
* regenerator-runtime
37
+
The application module libraries will be buildable in several different ways.
48
38
49
-
* The following dependencies will become peer dependencies:
39
+
* Built as an independent Site using the Shell for initialization, the header and footer, configuration, and other foundational services (logging, analytics, i18n, etc.)
40
+
* Built as federated modules to be loaded into the Shell at runtime via webpack module federation.
41
+
* Built and released as an NPM package for build-time inclusion in a frontend Project, perhaps alongside other application modules from other libraries.
50
42
51
-
* @openedx/frontend-base
52
-
* @openedx/paragon
53
-
* react
54
-
* react-dom
55
-
* react-redux
56
-
* react-router
57
-
* react-router-dom
58
-
* redux
43
+
Environment Agnostic
44
+
====================
59
45
60
-
* They will replace the frontend-build ``fedx-scripts`` CLI tools with the frontend-base ``openedx`` CLI tools. We'll discuss some of them in detail here, as they help illustrate what the library will be able to do:
46
+
The application module libraries will no longer contain ``.env`` or ``env.config`` files for any specific environment, including Devstack and Tutor. Config filename patterns will be added to the ``.gitignore`` file. They will continue to support adding a (git ignored) config file into the repository to build or develop it, but we also expect operators to use Projects and check their config files into those project repositories as their primary way of working with the application module libraries.
61
47
62
-
* ``dev`` will start a dev server, loading the repository's application modules into the shell in a site.
63
-
* ``dev:module`` will start a dev server that provides the application modules via module federation.
64
-
* ``build`` will create a standalone deployable artifact that uses the shell (similar to the micro-frontend architecture)
65
-
* ``build:module`` will create a standalone deployable artifact that provides the application modules via module federation.
66
-
* ``release`` will package the library for distribution on npm.
67
-
* ``serve`` will work with ``build`` or ``build:module`` to locally serve the production assets they generated.
68
-
* ``pack`` will work with ``release`` to create a ``.tgz`` file suitable for installing in local git checkouts that depend on the library. (this is a development tool)
48
+
Projects and these config files will be the subject of a subsequent ADR.
69
49
70
-
* The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a "Site Config" file (the replacement for .env/env.config files) which will not be checked into the repository.
71
-
* frontend-app-* repositories that are part of Open edX releases will be expected to be published on NPM as a library which exports its modules.
50
+
Removed Dependencies
51
+
====================
72
52
73
-
Redefining "application"
74
-
========================
53
+
Application module libraries will cease to use the following libraries in favor of ``frontend-base``:
75
54
76
-
This decision constitutes a re-definition of "application" in the Open edX frontend ecosystem. In the past, "application" was synonymous with the entire frontend-app-* repository. With this ADR, "application" will be synonymous with the top-level modules provided by a frontend-app-* repository. Those modules are applications.
55
+
* @openedx/frontend-build
56
+
* @edx/frontend-plaform
57
+
* @openedx/frontend-plugin-framework
58
+
* @edx/frontend-component-header
59
+
* @edx/frontend-component-footer
60
+
* @openedx/frontend-slot-footer
61
+
* @edx/brand
62
+
* core-js
63
+
* regenerator-runtime
77
64
78
-
We believe that the boundaries of our frontend-app-* repositories are fairly arbitrary and not as semantically meaningful as the boundaries of the *application modules* within them. We want these modules to be the primary unit of modularity - not the entire repository. The shell will be configured to load applications, not repositories.
65
+
Peer Dependencies
66
+
=================
79
67
80
-
As an example:
68
+
We expect application module libraries to be dependencies of Frontend Projects by default for most operators. Because of this, the following dependencies will become peer dependencies in the application module libraries themselves:
81
69
82
-
* The ``frontend-app-learning`` repository contains modules related to "learning" - course outline, courseware, the progress and dates pages, etc.
83
-
* The ``frontend-app-authn`` repository contains modules related to "authentication" - login, registration, logout, forgot password, etc.
70
+
* @openedx/frontend-base
71
+
* @openedx/paragon
72
+
* react
73
+
* react-dom
74
+
* react-redux
75
+
* react-router
76
+
* react-router-dom
77
+
* redux
84
78
85
-
The shell will be configured to load things like "courseware" or "login", not "learning" and "authn" - the repository the module is in is incidental.
79
+
New CLI Tools
80
+
=============
86
81
87
-
Regarding "plugins"
88
-
-------------------
82
+
The ``fedx-scripts`` CLI tools from ``frontend-build`` will be replaced with the ``openedx`` CLI tools from ``frontend-base``. We'll discuss some of them in detail here, as they help illustrate what the library will be able to do:
89
83
90
-
Plugins are another type of module. We believe that they are different than application modules because they have a different interface with the shell. Plugins are generally UI widgets loaded into a slot, though some can be larger. Applications are generally large and complex, comprising multiple pages of functionality with internal routing. They are also loaded at a path in the application, not in a plugin slot.
84
+
* ``dev`` will start a dev server, loading the repository's application modules into the shell in a site.
85
+
* ``dev:module`` will start a dev server that provides the application modules via module federation.
86
+
* ``build`` will create a standalone deployable artifact that uses the shell (similar to the micro-frontend architecture)
87
+
* ``build:module`` will create a standalone deployable artifact that provides the application modules via module federation.
88
+
* ``release`` will package the library for distribution on npm.
89
+
* ``serve`` will work with ``build`` or ``build:module`` to locally serve the production assets they generated.
90
+
* ``pack`` will work with ``release`` to create a ``.tgz`` file suitable for installing in local git checkouts that depend on the library. (this is a development tool)
91
91
92
-
Modeling applications as Plugins is a possibility, but we believe that it feels like too much indirection and abstraction, and minimizes the importance of applications. Without them there's no site, and many are likely *required* functionality for the Open edX frontend to function at all.
92
+
The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a "Site Config" file (the replacement for .env/env.config files) which will not be checked into the repository.
93
93
94
-
Some frontend-app-* repositories may also include Plugins, but they aren't the primary subject of this ADR.
94
+
Distributed as NPM Packages
95
+
===========================
96
+
97
+
``frontend-app-*`` repositories that are part of Open edX releases will be expected to be published on NPM as a library which exports its modules. These libraries will primarily be consumed by Frontend Projects.
95
98
96
99
Consequences
97
100
************
98
101
99
-
As the module architecture stabilizes, frontend-app-* maintainers and developers will be encouraged to migrate their micro-frontends into application module libraries, and to adopt the module architecture provided by frontend-base. (There will be a migration guide.)
102
+
As the module architecture stabilizes, ``frontend-app-*`` maintainers and developers will be encouraged to migrate their micro-frontends into application module libraries, and to adopt the module architecture provided by ``frontend-base``. (There will be a migration guide.)
103
+
104
+
As micro-frontends are migrated to application module libraries using the shell, there will be a deployment approach that mimics the micro-frontend architecture, but which will require operators to adopt a new underlying configuration and build process to achieve a similar result. Each ``frontend-app-*`` repository will need a deprecation process for the micro-frontend configuration and build infrastructure.
105
+
106
+
Thinking in Modules
107
+
===================
108
+
109
+
Our definition of "module" aligns with the `industry standard definition <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`_. It is also used in the context of `module federation <https://module-federation.io>`_. It's a self-contained part of the frontend that represents a specific part of the Site, and can be loaded in a variety of ways. We have several sub-types of module:
110
+
111
+
* An *application module* represents a well-bounded sub-area of the Open edX frontend at a particular path. This might be "courseware", "the login page", or "account settings". There are a number of application modules that are *required* for a functioning Open edX frontend Site.
112
+
* A "plugin module" represents an optional UI component that is generally added somewhere in an application module, or in the shell. The header and footer, for instance, would be overridden with alternate implementations via plugin modules. New tabs added to the course homepage are also plugin modules.
113
+
* *Service modules* which act as implementations of the logging or analytics services.
114
+
* *Script modules* which allow attaching arbitrary scripts to the page.
100
115
101
-
As micro-frontends are migrated application modules using the shell, there will be a deployment approach that mimics the micro-frontend architecture, but which will require operators to adopt a new underlying configuration and build process to achieve a similar result. Each frontend-app-* repository will need a deprecation process for the micro-frontend configuration and build infrastructure.
116
+
Our ``frontend-app-*`` repositories go from being "micro-frontend applications" to being a collection of application modules centered around a particular domain (learning, authoring, authn, etc.) The question of which application modules belong in which repositories, and where the right boundaries are, is beyond the scope of this ADR.
0 commit comments