feat: a sane basename

This separates webpack's publicPath from react-router's basename.  They
have similar effects - and still need to be set in conjunction in dev
mode (but not in a production build, where publicPath is set to 'auto')
- but it is very confusing to give them the same name in configuration.

Relatedly, this also removes support for `history` and its similarly
confusing reliance on basename, which is not even supported on newer
versions of the package, anyway.  Consuming apps should be using
`useNavigate()` instead.

Author: arbrandes

README.md

@@ -75,9 +75,9 @@ Then move the files out of the way (move src to some other sub-dir, mostly) to m
   - csrfTokenApiPath: '/csrf/api/v1/token',
   - languagePreferenceCookieName: 'openedx-language-preference',
   - userInfoCookieName: 'edx-user-info',
-  - publicPath: '/',
   - environment: 'production',
-- the `basename` and `history` exports have been replaced by function getters: `getBasename` and `getHistory`.  This is because it may not be possible to determine the values of the original constants at code initialization time, since our config may arrive asynchronously.  This ensures that anyone trying to get these values gets a current value.
+- the `basename` and export has been replaced by: `getBasename`.  This is because it may not be possible to determine the values of the original constants at code initialization time, since our config may arrive asynchronously.  This ensures that anyone trying to get these values gets a current value.
+- the `history` export no longer exists.  Consumers should be using react-router 6's `useNavigate()` API instead.
 - When using MockAuthService, set the authenticated user by calling setAuthenticatedUser after instantiating the service.  It's not okay for us to add arbitrary config values to the site config.
 - `REFRESH_ACCESS_TOKEN_ENDPOINT` has been replaced with `refreshAccessTokenApiPath`.  It is now a path that defaults to '/login_refresh'.  The Auth service assumes it is an endpoint on the LMS, and joins the path with `lmsBaseUrl`.  This change creates more parity with other paths such as `csrfTokenApiPath`.
 

docs/how_tos/migrate-frontend-app.md

@@ -499,16 +499,16 @@ Optional config
 
 Other configuration is now optional, and many values have been given sensible defaults.  But these configuration variables are also available (as of this writing):
 
+- environment: EnvironmentTypes
+- basename: string
+- mfeConfigApiUrl: string | null
 - accessTokenCookieName: string
 - languagePreferenceCookieName: string
 - userInfoCookieName: string
 - csrfTokenApiPath: string
 - refreshAccessTokenApiPath: string
 - ignoredErrorRegex: RegExp | null
 - segmentKey: string | null
-- environment: EnvironmentTypes
-- mfeConfigApiUrl: string | null
-- publicPath: string
 
 URL Config changes
 ------------------
@@ -573,7 +573,7 @@ Once you've verified your test suite still works, you should delete the `.env.te
 A sample `site.config.test.tsx` file:
 
 ```
-import { SiteConfig } from '@openedx/frontend-base';
+import { EnvironmentTypes, SiteConfig } from '@openedx/frontend-base';
 
 const siteConfig: SiteConfig = {
   siteId: 'test',
@@ -582,7 +582,7 @@ const siteConfig: SiteConfig = {
   lmsBaseUrl: 'http://localhost:18000',
   loginUrl: 'http://localhost:18000/login',
   logoutUrl: 'http://localhost:18000/logout',
-  environment: 'dev',
+  environment: EnvironmentTypes.TEST,
   apps: [{
     appId: 'test-app',
     routes: [{
@@ -599,10 +599,9 @@ const siteConfig: SiteConfig = {
   csrfTokenApiPath: '/csrf/api/v1/token',
   languagePreferenceCookieName: 'openedx-language-preference',
   refreshAccessTokenApiPath: '/login_refresh',
-  segmentKey: '',
   userInfoCookieName: 'edx-user-info',
   ignoredErrorRegex: null,
-  publicPath: '/',
+  segmentKey: '',
 };
 
 export default siteConfig;

package-lock.json

@@ -76,7 +76,6 @@
     "glob": "^7.2.3",
     "globals": "^15.11.0",
     "gradient-string": "^2.0.2",
-    "history": "^4.10.1",
     "html-webpack-plugin": "5.6.0",
     "identity-obj-proxy": "3.0.0",
     "image-minimizer-webpack-plugin": "3.8.3",
@@ -112,7 +111,7 @@
     "ts-loader": "^9.5.1",
     "typescript": "^5.6.3",
     "typescript-eslint": "^8.11.0",
-    "universal-cookie": "^4.0.4",
+    "universal-cookie": "^8.0.1",
     "url-loader": "^4.1.1",
     "uuid": "^11.0.2",
     "webpack": "^5.97.1",
@@ -142,7 +141,7 @@
     "nodemon": "^3.1.4"
   },
   "peerDependencies": {
-    "@openedx/paragon": "^22.20.1",
+    "@openedx/paragon": "^22.20.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-redux": "^8.1.3",

package.json

@@ -123,14 +123,13 @@ let siteConfig: SiteConfig = {
   apps: [],
   externalRoutes: [],
   externalLinkUrlOverrides: [],
+  mfeConfigApiUrl: null,
   accessTokenCookieName: 'edx-jwt-cookie-header-payload',
   csrfTokenApiPath: '/csrf/api/v1/token',
   ignoredErrorRegex: null,
   languagePreferenceCookieName: 'openedx-language-preference',
-  publicPath: '/',
   refreshAccessTokenApiPath: '/login_refresh',
   userInfoCookieName: 'edx-user-info',
-  mfeConfigApiUrl: null,
   segmentKey: null,
 };
 

runtime/config/index.ts

@@ -78,7 +78,6 @@ export {
 export {
   auth,
   getBasename,
-  getHistory,
   initError,
   initialize
 } from './initialize';
@@ -125,11 +124,9 @@ export {
 export {
   camelCaseObject,
   convertKeyNames,
-  getPath,
   getQueryParameters,
   isValidVariableName,
   modifyObjectKeys,
-  parseURL,
   snakeCaseObject
 } from './utils';
 

runtime/index.ts

@@ -47,10 +47,6 @@
  * @module Initialization
  */
 
-import {
-  createBrowserHistory,
-  createMemoryHistory
-} from 'history';
 /*
 This 'site.config' package is a special 'magic' alias in our webpack configuration in the `config`
 folder. It points at an `site.config.tsx` file in the root of a site's repository.
@@ -94,30 +90,15 @@ import {
 } from './logging';
 import { GoogleAnalyticsLoader } from './scripts';
 import { publish } from './subscriptions';
-import { getPath } from './utils';
 
 /**
- * A browser history or memory history object created by the [history](https://github.com/ReactTraining/history)
- * package.  Applications are encouraged to use this history object, rather than creating their own,
- * as behavior may be undefined when managing history via multiple mechanisms/instances. Note that
- * in environments where browser history may be inaccessible due to `window` being undefined, this
- * falls back to memory history.
- */
-export const getHistory = () => ((typeof window !== 'undefined')
-  ? createBrowserHistory({ basename: getPath(getSiteConfig().publicPath) })
-  : createMemoryHistory());
-
-/**
- * The string basename that is the root directory of this MFE.
- *
- * In devstack, this should always just return "/", because each MFE is in its own server/domain.
+ * If set in configuration, a basename will be prepended to all relative routes under BrowserRouter.
  *
- * In Tutor, all MFEs are deployed to a common server, each under a different top-level directory.
- * The basename is the root path for a given MFE, e.g. "/library-authoring". It is set by tutor-mfe
- * as an ENV variable in the Docker file, and we read it here from that configuration so that it
- * can be passed into a Router later.
+ * Unlike webpack's publicPath, the basename cannot be auto-discovered, so when publicPath is set
+ * (or when it's set to 'auto' and the site is being served from a path other than '/') this
+ * needs to be configured.
  */
-export const getBasename = () => getPath(getSiteConfig().publicPath);
+export const getBasename = () => getSiteConfig().basename;
 
 /**
  * The default handler for the initialization lifecycle's `initError` phase.  Logs the error to the

runtime/initialize.js

@@ -1,5 +1,3 @@
-import { createBrowserHistory } from 'history';
-
 import {
   SITE_ANALYTICS_INITIALIZED,
   SITE_AUTH_INITIALIZED,
@@ -10,7 +8,7 @@ import {
   SITE_PUBSUB_INITIALIZED,
   SITE_READY,
 } from './constants';
-import { getHistory, initialize } from './initialize';
+import { initialize } from './initialize';
 
 import { configureAnalytics, SegmentAnalyticsService } from './analytics';
 import {
@@ -38,7 +36,6 @@ jest.mock('./auth');
 jest.mock('./analytics');
 jest.mock('./i18n');
 jest.mock('./auth/LocalForageCache');
-jest.mock('history');
 
 let config = null;
 const newConfig = {
@@ -357,13 +354,3 @@ describe('initialize', () => {
     });
   });
 });
-
-describe('history', () => {
-  it('browser history called by default path', async () => {
-    getHistory();
-    // import history from initialize;
-    expect(createBrowserHistory).toHaveBeenCalledWith({
-      basename: '/',
-    });
-  });
-});

runtime/initialize.test.js

@@ -7,6 +7,7 @@ const siteConfig: SiteConfig = {
   lmsBaseUrl: 'http://localhost:18000',
   loginUrl: 'http://localhost:18000/login',
   logoutUrl: 'http://localhost:18000/logout',
+
   environment: EnvironmentTypes.TEST,
   apps: [{
     appId: 'test-app',
@@ -24,10 +25,9 @@ const siteConfig: SiteConfig = {
   csrfTokenApiPath: '/csrf/api/v1/token',
   languagePreferenceCookieName: 'openedx-language-preference',
   refreshAccessTokenApiPath: '/login_refresh',
-  segmentKey: 'segment_whoa',
   userInfoCookieName: 'edx-user-info',
   ignoredErrorRegex: null,
-  publicPath: '/'
+  segmentKey: 'segment_whoa',
 };
 
 export default siteConfig;