docs: OEP-65 reframe around build-time shell architecture#808
Conversation
a8a69df to
24e17f3
Compare
| The library will provide base ESLint, Jest, TypeScript, and Webpack configurations. ESLint, Jest, and TypeScript will be similar to what ``frontend-build`` provides. | ||
|
|
||
| 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: | ||
| The webpack configurations will support a variety of build targets for the new :term:`Shell 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: |
There was a problem hiding this comment.
Is MFE a deprecated term? If so, I'd be careful how it gets used in this doc. I'm not sure if this should read "... application configurations (was MFE configurations) ...", or just "... application configurations ...", or something else. But I would not continue to sprinkle the term "MFE" around if you wish to replace it.
There was a problem hiding this comment.
Agreed, totally. This instance should definitely read "application configurations". Thanks!
brian-smith-tcril
left a comment
brian-smith-tcril
left a comment
There was a problem hiding this comment.
Overall this reframe looks great! Couple things that feel odd to me I left comments about.
|
|
||
| Proposed MFE Architecture | ||
| ========================= | ||
| The reference implementation of this architecture is `frontend-base <https://github.com/openedx/frontend-base>`_, which provides the :term:`shell` and replaces `frontend-build <frontend-build_>`_, `frontend-platform <frontend-platform_>`_, `frontend-plugin-framework <frontend-plugin-framework_>`_, `frontend-component-header <frontend-component-header_>`_, and `frontend-component-footer <frontend-component-footer_>`_. |
There was a problem hiding this comment.
Reference implementation doesn't feel like it makes sense as this section title anymore
There was a problem hiding this comment.
I think it's fine. Can't think of a better term for a concrete piece of code that implements a proposed architecture.
There was a problem hiding this comment.
I think I'm OK with it too. The thing that gave me pause about it is that reference implementation doesn't automatically imply "prod ready."
frontend-base is our official, published (to npm), production ready implementation. "Reference" doesn't quite hit those notes for me.
83e8bae to
1ee72e3
Compare
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>
1ee72e3 to
46bf1e8
Compare
brian-smith-tcril
left a comment
brian-smith-tcril
left a comment
There was a problem hiding this comment.
2 tiny comments but this looks great!
|
|
||
| * **The shell takes over the foundations.** Apps no longer initialize ``frontend-platform`` or render their own header and footer; the :term:`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 :term:`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 :term:`Site Config` (see :ref:`Frontend Sites`). A repository may keep a git-ignored config file for local development. |
There was a problem hiding this comment.
I like the reframing! The one part that still specifically feels odd to me is the mention of
A repository may keep a git-ignored config file for local development.
even more specifically, the gitignored part.
Since we do keep site.config.dev.tsx files checked in for local development in the frontend-base branches of frontend app repos, it feels odd to mention gitignoring it.
|
|
||
| Proposed MFE Architecture | ||
| ========================= | ||
| The reference implementation of this architecture is `frontend-base <https://github.com/openedx/frontend-base>`_, which provides the :term:`shell` and replaces `frontend-build <frontend-build_>`_, `frontend-platform <frontend-platform_>`_, `frontend-plugin-framework <frontend-plugin-framework_>`_, `frontend-component-header <frontend-component-header_>`_, and `frontend-component-footer <frontend-component-footer_>`_. |
There was a problem hiding this comment.
I think I'm OK with it too. The thing that gave me pause about it is that reference implementation doesn't automatically imply "prod ready."
frontend-base is our official, published (to npm), production ready implementation. "Reference" doesn't quite hit those notes for me.
3 participants
Description
This reframes OEP-65 to match what the
frontend-basereference implementation actually does. The original OEP proposed runtime module loading via webpack module federation, but the implementation dropped both in favor of composing frontends into a single build. The OEP, its glossary, and its ADRs described an architecture that no longer exists.The proposal now centers on build-time composability and shared dependencies, achieved by composing apps into one or more sites via a shared shell. The glossary and ADRs are updated to the new vocabulary, and ADR-0003 is renamed from "Frontend Projects" to "Frontend Sites". A longstanding misspelling of the OEP's "Composability" label is also fixed.
LLM usage notice
Built with assistance from Claude.