Skip to content

Commit 3776526

Browse files
robraprobrap
authored
feat: add doc for MFE testing (#702)
1 parent ad0c004 commit 3776526

2 files changed

Lines changed: 169 additions & 1 deletion

File tree

‎README.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ This is the standard edX header for use in React applications. It has four expor
1212

1313
- **default**: The Header Component
1414
- **messages**: for i18n in the form of ``{ locale: { key: translatedString } }``
15-
- **LearnerHeader** Header component for the Learner MFE
15+
- **LearningHeader** Header component for the Learning MFE
1616
- **StudioHeader** Header component for Studio
1717

1818
Cloning and Startup
@@ -59,6 +59,9 @@ Development
5959
- Start the example server `npm start`
6060
- Visit http://localhost:1234
6161

62+
Alternatively, you can develop and test the header from within a consuming MFE (e.g. to test ``LearningHeader`` in ``frontend-app-learning`` or ``StudioHeader`` in
63+
``frontend-app-course-authoring``). See `docs/testing_in_mfe.rst <docs/testing_in_mfe.rst>`_ for instructions.
64+
6265
Contributing
6366
============
6467

‎docs/testing_in_mfe.rst‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
.. title:: Testing the Header Component from Within an MFE
2+
3+
Testing the Header Component from Within an MFE
4+
================================================
5+
6+
.. note::
7+
**Warning:** This doc *may* work as-is, but may not. The process described worked for the author, but has not been verified by another. If you verify or fix this doc, please update or close `BOMS-619`_, the ticket for follow-up review.
8+
9+
.. _BOMS-619: https://2u-internal.atlassian.net/browse/BOMS-619
10+
11+
Overview
12+
--------
13+
14+
This guide describes how to test local changes to ``frontend-component-header-edx`` by wiring the component source directly into a consuming MFE using a webpack alias.
15+
16+
This approach *should* work with any MFE that imports ``@edx/frontend-component-header``.
17+
18+
.. note::
19+
These instructions assume you are running the MFE inside the edX devstack (Docker). If you are running the MFE from your host machine, the changes are the same except the header source path in ``webpack.dev.config.js`` should be the absolute local path to the header repo's ``src/`` directory (e.g. ``/Users/yourname/edx/src/frontend-component-header-edx/src``) instead of the Docker path shown below.
20+
21+
Prerequisites
22+
-------------
23+
24+
- The edX devstack is running.
25+
- ``frontend-component-header-edx`` is checked out locally on the branch you want to test. On the host machine, clone it to ``<DEVSTACK_WORKSPACE>/src/frontend-component-header-edx``, where ``<DEVSTACK_WORKSPACE>`` is the directory where devstack and all the devstack cloned repos live. The devstack mounts this location inside the MFE container at ``/edx/app/src/frontend-component-header-edx/``.
26+
27+
Step 1: Install dependencies in the header repo
28+
------------------------------------------------
29+
30+
The header component's direct dependencies (those listed under ``dependencies`` in its ``package.json``, such as ``react-responsive``) must be installed in the header repo itself. Webpack resolves these from the header's own ``node_modules``, not from the consuming MFE.
31+
32+
Run the following from your host machine or in the MFE container:
33+
34+
.. code-block::
35+
36+
cd /path/to/frontend-component-header-edx
37+
npm install
38+
39+
Step 2: Add a webpack alias to the consuming MFE
40+
-------------------------------------------------
41+
42+
Open ``webpack.dev.config.js`` in ``frontend-app-learning`` and add the header source alias along with peer-dependency aliases. The peer-dependency aliases ensure that both the header source and the MFE use the same instances of shared libraries (React, Paragon, etc.), preventing duplicate-module errors.
43+
44+
The changes below assume the existing config uses the pattern of calling ``createConfig`` and then adding to ``config.resolve.alias``.
45+
46+
Add the following block before the ``createConfig`` call:
47+
48+
.. code-block::
49+
50+
// Add before the createConfig call:
51+
const headerPeerDeps = [
52+
'@edx/frontend-platform',
53+
'@openedx/paragon',
54+
'prop-types',
55+
'react',
56+
'react-dom',
57+
'react-redux',
58+
'react-router-dom',
59+
];
60+
61+
const headerPeerAliases = Object.fromEntries(
62+
headerPeerDeps.map(pkg => [pkg, path.resolve(__dirname, 'node_modules', pkg)]),
63+
);
64+
65+
Option 1: If ``config.resolve.alias`` already exists in the file, add the ``frontend-component-header`` and ``headerPeerAliases`` lines to the end, like this ``frontend-app-learning`` example:
66+
67+
.. code-block::
68+
69+
// Add after the createConfig(...) call:
70+
config.resolve.alias = {
71+
...config.resolve.alias,
72+
'@src': path.resolve(__dirname, 'src'),
73+
'@edx/frontend-component-header': '/edx/app/src/frontend-component-header-edx/src',
74+
...headerPeerAliases,
75+
};
76+
77+
Option 2: If ``config.resolve.alias`` doesn't yet exist in the file, use the following directly:
78+
79+
.. code-block::
80+
81+
config.resolve.alias = {
82+
...config.resolve.alias,
83+
'@edx/frontend-component-header': '/edx/app/src/frontend-component-header-edx/src',
84+
...headerPeerAliases,
85+
};
86+
87+
The path ``/edx/app/src/frontend-component-header-edx/src`` is the location of the header source inside the devstack Docker container. Adjust this path if your devstack layout differs or if you are running the MFE on your host machine.
88+
89+
Step 3: Update the SCSS import
90+
-------------------------------
91+
92+
The consuming MFE's main SCSS file typically imports the header's compiled stylesheet from its ``dist/`` folder. Because we are now pointing to the unbuilt source, that path does not exist. Change the import to reference the source ``index.scss`` directly.
93+
94+
In ``src/index.scss``, find the header import and change it:
95+
96+
.. code-block::
97+
98+
/* Before */
99+
@import "~@edx/frontend-component-header/dist/index";
100+
101+
/* After */
102+
@import "~@edx/frontend-component-header/index";
103+
104+
Step 4: Restart the MFE and verify
105+
------------------------------------
106+
107+
To restart from devstack:
108+
109+
.. code-block::
110+
111+
make frontend-app-learning-stop
112+
113+
# Starting the container will run npm start
114+
make frontend-app-learning-up
115+
116+
Verifying your changes are active
117+
----------------------------------
118+
119+
If the changes you are testing produce obvious UI differences, confirm they appear. If the changes are subtle or internal, use browser DevTools to confirm the local source is being used:
120+
121+
1. Open DevTools → **Sources** tab.
122+
2. Search for the component you are testing (e.g. ``LearningHeader``, ``StudioHeader``, or ``Header``).
123+
3. The source file should be human-readable and match your local checkout.
124+
125+
Troubleshooting
126+
---------------
127+
128+
Module not found errors for header dependencies
129+
***********************************************
130+
131+
After adding the webpack alias, the MFE may fail to compile with one or more errors like:
132+
133+
.. code-block::
134+
135+
Module not found: Can't resolve 'react-responsive'
136+
in '/edx/app/src/frontend-component-header-edx/src'
137+
Module not found: Can't resolve '@2uinc/frontend-enterprise-utils'
138+
in '/edx/app/src/frontend-component-header-edx/src/learning-header'
139+
140+
Multiple errors of this form are expected if ``npm install`` has not been run in the header repo. The header's direct dependencies are resolved from the header repo's own ``node_modules``.
141+
142+
**Fix:** Run ``npm install`` in the header repo (Step 1 above), then restart the MFE.
143+
144+
Alternatively, this error might appear if there is a new peer dependency not yet listed in this doc.
145+
146+
Stale module errors after npm install completes
147+
***********************************************
148+
149+
If you leave the MFE running while ``npm install`` is executing in the header repo, you may see some errors resolve, but still see additional module-not-found errors.
150+
151+
**Fix:** Restart the MFE. A clean compile against the fully-installed ``node_modules`` clears these.
152+
153+
Can't find stylesheet to import (SCSS error)
154+
********************************************
155+
156+
.. code-block::
157+
158+
ERROR in ./src/index.scss
159+
Module build failed (from sass-loader):
160+
Can't find stylesheet to import.
161+
3 │ @import "~@edx/frontend-component-header/dist/index";
162+
163+
Once the webpack alias is active, ``@edx/frontend-component-header`` resolves to the local source directory, which has no ``dist/`` folder.
164+
165+
**Fix:** Apply the SCSS import change described in Step 3 above, then restart the MFE.

0 commit comments

Comments
 (0)