docs: touch up docs

arbrandes · arbrandes · commit eda72638422d · 2025-06-24T14:48:51.000-03:00
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Open edX frontend framework
 
-| :rotating_light: Pre-alpha                                                                |
+| :rotating_light: Alpha                                                                |
 |:------------------------------------------------------------------------------------------|
 | frontend-base is under **active development** and may change significantly without warning. |
 
@@ -34,39 +34,50 @@ Feel free to reach out in [#wg-frontend on Slack](https://openedx.slack.com/arch
 
 ## Development
 
-This library is under development and has not yet been published to npm.
+This library is under development and for now is released manually to npm.
 
-## Migrating an MFE to `frontend-base` (Work in progress)
+### Developing with Tutor
 
-See the [Frontend App Migration How To](./docs/how_tos/migrate-frontend-app.md).
+In order to use develop frontend-base with Tutor, you need to create a Tutor plugin which patches some of the LMS's development settings.
 
-## Merging repositories
+```
+from tutormfe.hooks import MFE_APPS, MFE_ATTRS_TYPE
 
-Followed this process: https://stackoverflow.com/questions/13040958/merge-two-git-repositories-without-breaking-file-history
+from tutor import hooks
 
-After adding a remote of the repo to merge in, run this command:
+hooks.Filters.ENV_PATCHES.add_item(
+  (
+    "openedx-lms-development-settings",
+    """
+CORS_ORIGIN_WHITELIST.append("http://{{ MFE_HOST }}:8080")
+LOGIN_REDIRECT_WHITELIST.append("http://{{ MFE_HOST }}:8080")
+CSRF_TRUSTED_ORIGINS.append("http://{{ MFE_HOST }}:8080")
+"""
+    )
+)
+```
+
+Once you enable this plugin, you can start the development site with:
 
 ```
-git merge other-repo-remote/master --allow-unrelated-histories
+nvm use
+npm ci
+npm run dev
 ```
 
-Then work through the conflicts and use a merge commit to add the history into the frontend-base.
+The development site will be available at `http://apps.local.openedx.io:8080`.
 
-Then move the files out of the way (move src to some other sub-dir, mostly) to make room for the next repo.
+## Migrating an MFE to `frontend-base`
 
-### Latest repository merges
+See the [Frontend App Migration How To](./docs/how_tos/migrate-frontend-app.md).
 
-- frontend-build            - Up to date as of 9/12/2024
-- frontend-platform         - Up to date as of 9/13/2024
-- frontend-plugin-framework - Up to date as of 9/13/2024
-- frontend-component-header - Up to date as of 9/12/2024
-- frontend-component-footer - Up to date as of 9/12/2024
+# Notable changes
 
-# Other notable changes
+This is a list of notable changes from the previous paradigm:
 
 - Cease using `AUTHN_MINIMAL_HEADER`, replace it with an actual minimal header.
 - No more using `process.env` in runtime code.
-- Removed dotenv.  Use site.config.tsx.
+- Removed dotenv.  Use `site.config.*.tsx`.
 - Removed Purge CSS.  We do not believe that Purge CSS works properly with Paragon in general.
 - Removed `ensureConfig` function.  This sort of type safety should happen with TypeScript types in the site config file.
 - Removed `ensureDefinedConfig` function.  Similar to ensureConfig, this sort of type safety should be handled by TypeScript.
@@ -99,39 +110,3 @@ The following config variables have been removed, in favor of defining roles for
 - DISCOVERY_API_BASE_URL
 - CREDENTIALS_BASE_URL
 - PUBLISHER_BASE_URL
-
-# Working with Tutor
-
-In order to use tutor with frontend-base, you need to create a tutor plugin which patches some of the LMS's development settings.
-
-```
-from tutormfe.hooks import MFE_APPS, MFE_ATTRS_TYPE
-
-from tutor import hooks
-
-hooks.Filters.ENV_PATCHES.add_item(
-  (
-    "openedx-lms-development-settings",
-    """
-CORS_ORIGIN_WHITELIST.append("http://{{ MFE_HOST }}:8080")
-LOGIN_REDIRECT_WHITELIST.append("http://{{ MFE_HOST }}:8080")
-CSRF_TRUSTED_ORIGINS.append("http://{{ MFE_HOST }}:8080")
-MFE_CONFIG = {
-  # override MFE CONFIG values appropriate to the shell, if necessary
-}
-"""
-    )
-)
-```
-
-Customizing the MFE config API:
-
-https://github.com/overhangio/tutor-mfe?tab=readme-ov-file#customising-mfes
-
-Creating a Tutor plugin:
-
-https://docs.tutor.edly.io/tutorials/plugin.html
-
-Adding new MFEs:
-
-https://github.com/overhangio/tutor-mfe?tab=readme-ov-file#adding-new-mfes
diff --git a/docs/how_tos/migrate-frontend-app.md b/docs/how_tos/migrate-frontend-app.md
@@ -2,7 +2,7 @@
 Migrating an MFE to frontend-base
 =================================
 
-To use `frontend-base`, you'll need to use `npm pack` and install it into your MFE from the resulting `.tgz` file.
+To use the latest version of `frontend-base` from a git repository, you'll need to use `npm pack` and install it into your MFE from the resulting `.tgz` file.
 
 Following these steps turns your MFE into a library that can be built using frontend-base and its shell application.  It involves deleting a lot of unneeded dependencies and code.
 
@@ -58,21 +58,19 @@ Dependencies shared with the shell should be moved to peerDependencies.  These i
 ```diff
 "dependencies" {
 -  "@openedx/paragon": "^22.8.1",
+-  "@tanstack/react-query": "^5.81.2",
 -  "react": "^17.0.2",
 -  "react-dom": "^17.0.2",
--  "react-redux": "^8.1.3",
 -  "react-router": "^6.26.1",
 -  "react-router-dom": "^6.26.1",
--  "redux": "^4.2.1"
 },
 "peerDependencies": {
 +  "@openedx/paragon": "^22.8.1",
++  "@tanstack/react-query": "^5.81.2",
 +  "react": "^17.0.2",
 +  "react-dom": "^17.0.2",
-+  "react-redux": "^8.1.3",
 +  "react-router": "^6.26.1",
 +  "react-router-dom": "^6.26.1",
-+  "redux": "^4.2.1"
 }
 ```
 
@@ -127,14 +125,10 @@ With the exception of any custom scripts, replace the `scripts` section of your
 
 ```
   "scripts": {
-    "build": "openedx build",
     "dev": "PORT=YOUR_PORT openedx dev",
     "i18n_extract": "openedx formatjs extract",
     "lint": "openedx lint .",
     "lint:fix": "openedx lint --fix .",
-    "pack": "openedx pack",
-    "release": "openedx release",
-    "serve": "PORT=YOUR_PORT openedx serve",
     "snapshot": "openedx test --updateSnapshot",
     "test": "openedx test --coverage --passWithNoTests"
   },
@@ -168,8 +162,6 @@ This means that the code from the library can be safely tree-shaken by webpack.
 ],
 ```
 
-// TODO: Maybe put scss and css files in side effects.  They have side effects and need to be excluded so they get bundled.
-
 
 Add a Type Declaration file (app.d.ts)
 ======================================
@@ -294,9 +286,11 @@ Add a babel.config.js file for Jest
 Jest needs a babel.config.js file to be present in the repository.  It should look like:
 
 ```
-const config = require('@openedx/frontend-base/config/babel/babel.base.config');
+const { createConfig } = require('@openedx/frontend-base/config');
 
-module.exports = config;
+module.exports = createConfig('test', {
+...
+});
 ```
 
 
@@ -542,7 +536,6 @@ App-specific configuration can be expressed by adding an `config` section to the
 const app: App = {
   ...
   config: {
-    appId: 'myapp',
     myCustomVariableName: 'my custom variable value',
   },
 };
@@ -554,7 +547,7 @@ These variables can be used in code with the `getAppConfig` function:
 getAppConfig('myapp').myCustomVariableName
 ```
 
-Or via `useAppConfig()` (with no need to specify the appId), if `AppProvider` is wrapping your app.
+Or via `useAppConfig()` (with no need to specify the appId), if `CurrentAppProvider` is wrapping your app.
 
 
 Replace the .env.test file with configuration in site.config.test.tsx file
@@ -625,8 +618,7 @@ Export the modules of your app in your index.ts file.
 
 This may require a little interpretation.  In spirit, the modules of your app are the 'pages' of an Open edX Frontend site that it provides.  This likely corresponds to the top-level react-router routes in your app.  In frontend-app-profile, for instance, this is the `ProfilePage` component, amongst a few others.  Some MFEs have put their router and pages directly into the `index.jsx` file inside the initialization callback - this code will need to be moved to a single component that can be exported.
 
-These modules should be unopinionated about the path prefix where they are mounted.  The exact way we handle routing is still being figured out.  In the short term, the react-router data APIs are not suppored until we can figure out how to implement lazy route discovery (a.k.a., "Fog of War")  Using `<Routes>` with `<Route>` components inside it works today.  **This functionality is still a work in progress, and is one of the big things we need to figure out.**
-
+These modules should be unopinionated about the path prefix where they are mounted.
 
 Remove core-js and regenerator-runtime
 ======================================
@@ -639,7 +631,7 @@ Create a site.scss file
 
 This is required if you intend to run builds from the app itself.
 
-Create a new `site.scss` file at the top of your application.  It's responsible for:
+Create a new `app.scss` file at the top of your application.  It's responsible for:
 
 1. Importing the shell's stylesheet, which includes Paragon's core stylesheet.
 2. Importing your brand stylesheet.
@@ -648,7 +640,7 @@ Create a new `site.scss` file at the top of your application.  It's responsible
 You must then import this new stylesheet into your `site.config` file:
 
 ```diff
-+ import './site.scss';
++ import './app.scss';
 
 const siteConfig: SiteConfig = {
   // config document
@@ -721,6 +713,8 @@ Upgrade react-query
 
 If the MFE uses react-query version 4 or below, upgrade it to 5 as per [this guide](https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5).
 
+If the MFE uses Redux, consider porting the app over to react-query, as it will make it much easier to handle header (and footer) customization.
+
 
 Removal of pubsub-js
 ====================
@@ -742,16 +736,4 @@ Refactor plugin-slots
 
 First, rename `src/plugin-slots`, if it exists, to `src/slots`.  Modify imports and documentation across the codebase accordingly.
 
-Next, the frontend-base equivalent to `<PluginSlot />` is `<Slot />`, and has a different API.   This includes a change in the slot ID, according to the [new slot naming ADR](../decisions/0009-slot-naming-and-lifecycle.rst) in this repository.  Rename them accordingly. You can refer to the `src/shell/dev-site` in this repository for examples.
-
-
-Find your module boundaries
-===========================
-
-From this step on, things get a bit more subjective.  At this point you need to ensure that the modules in your library are decoupled and well-bounded.  If you use Redux, this may mean creating individual redux stores for each module, including adding a context so that they're separate from any "upstream" redux stores that may exist.
-
-https://react-redux.js.org/using-react-redux/accessing-store#multiple-stores
-
-
-react-router: move to data router
-=================================
+Next, the frontend-base equivalent to `<PluginSlot />` is `<Slot />`, and has a different API.   This includes a change in the slot ID, according to the [new slot naming ADR](../decisions/0009-slot-naming-and-lifecycle.rst) in this repository.  Rename them accordingly. You can refer to the `src/shell/dev` in this repository for examples.
