refactor: configuration types and file names

There is no need for a distinct ProjectSiteConfig; it is actually less
confusing to accept that some config properties are indeed optional, and
write code accordingly.

The concept of "Project" is also a bit confusing, since the
configuration is typed as "SiteConfig".  So we're abandoning "Project"
in favor of "Site".  This renames everything accordingly.

Continuing, rename SiteConfig's top-level `appId` to a more fitting
`siteId`, leaving `appId` exclusively for the `App` type.

In yet another rename, move the `custom` app config to what it's
actually for: `standalone` mode.  (Plus, "dev.legacy" is better
described as "dev.standalone".)

Also move test.site.config.tsx into the normal site.config.*.tsx
pattern.  There is no longer any reason for the distinction, as all
site.config files are ok to be committed.

Finally, adjust other webpack and site.config file names to a more
conformant pattern.

Author: arbrandes

.github/workflows/ci.yml

@@ -33,5 +33,5 @@ jobs:
       run: npm run lint
     - name: Test
       run: npm run test
-    - name: Test Project
-      run: npm run test-project
+    - name: Build Test Site
+      run: npm run test-site:build

.gitignore

@@ -9,4 +9,4 @@ scss
 node_modules
 npm-debug.log
 docs/api
-/openedx-frontend-base-1.0.0.tgz
+/*.tgz

docs/decisions/0008-stylesheet-import-in-site-config.md

@@ -18,7 +18,7 @@ As a best practice, a project should have a top-level SCSS file as a peer to the
 
 ## Implementation
 
-The `project.scss` file should import the stylesheet from the shell:
+The `site.scss` file should import the stylesheet from the shell:
 
 ```diff
 + @import '@openedx/frontend-base/shell/app.scss';
@@ -29,7 +29,7 @@ The `project.scss` file should import the stylesheet from the shell:
 The site.config file should then import the top-level SCSS file:
 
 ```diff
-+ import './project.scss';
++ import './site.scss';
 
 const config = {
   // config document

docs/decisions/0009-slot-naming-and-lifecycle.rst

@@ -106,7 +106,7 @@ Where:
 
 For example:
 
-* org.openedx.frontend.slot.devProject.foobar (unsupported slot, as version is empty)
+* org.openedx.frontend.slot.devSite.foobar (unsupported slot, as version is empty)
 * org.openedx.frontend.slot.footer.main.unstable (unstable slot)
 * org.openedx.frontend.slot.learning.navigationSidebar.v2 (this slot is on version 2)
 

docs/how_tos/migrate-frontend-app.md

@@ -128,9 +128,9 @@ With the exception of any custom scripts, replace the `scripts` section of your
 ```
   "scripts": {
     "build": "PORT=YOUR_PORT openedx build",
-    "build:legacy": "openedx build:legacy", // TODO: Does this target exist?
+    "build:standalone": "openedx build:standalone",
     "dev": "PORT=YOUR_PORT openedx dev",
-    "dev:legacy": "PORT=YOUR_PORT openedx dev:legacy",
+    "dev:standalone": "PORT=YOUR_PORT openedx dev:standalone",
     "i18n_extract": "openedx formatjs extract",
     "lint": "openedx lint .",
     "lint:fix": "openedx lint --fix .",
@@ -182,7 +182,7 @@ Create an `app.d.ts` file in the root of your MFE with the following contents:
 /// <reference types="@openedx/frontend-base" />
 
 declare module 'site.config' {
-  export default ProjectSiteConfig;
+  export default SiteConfig;
 }
 
 declare module '*.svg' {
@@ -210,7 +210,6 @@ Create a `tsconfig.json` file and add the following contents to it:
     "babel.config.js",
     "eslint.config.js",
     "jest.config.js",
-    "test.site.config.tsx",
     "site.config.*.tsx",
   ],
 }
@@ -388,7 +387,7 @@ Description fields are now required on all i18n messages in the repository.  Thi
 SVGR "ReactComponent" imports have been removed
 ===============================================
 
-We have removed the `@svgr/webpack` loader because it was incompatible with more modern tooling (it requires Babel).  As a result, the ability to import SVG files into JS as the `ReactComponent` export no longer works.  We know of a total of 5 places where this is happening today in Open edX MFEs - frontend-app-learning and frontend-app-profile use it.  Please replace that export with the default URL export and set the URL as the source of an `<img>` tag, rather than using `ReactComponent`.  You can see an example of normal SVG imports in `test-project/src/ExamplePage.tsx`.
+We have removed the `@svgr/webpack` loader because it was incompatible with more modern tooling (it requires Babel).  As a result, the ability to import SVG files into JS as the `ReactComponent` export no longer works.  We know of a total of 5 places where this is happening today in Open edX MFEs - frontend-app-learning and frontend-app-profile use it.  Please replace that export with the default URL export and set the URL as the source of an `<img>` tag, rather than using `ReactComponent`.  You can see an example of normal SVG imports in `test-site/src/ExamplePage.tsx`.
 
 
 Import createConfig and getBaseConfig from @openedx/frontend-base/config
@@ -490,7 +489,7 @@ Required config
 
 The required configuration at the time of this writing is:
 
-- appId: string
+- siteId: string
 - siteName: string
 - baseUrl: string
 - lmsBaseUrl: string
@@ -538,13 +537,13 @@ const examplePageUrl = getUrlForRouteRole('example');
 App-specific config values
 --------------------------
 
-App-specific configuration can be expressed by adding a `custom` section to SiteConfig which allows arbitrary config variables.
+App-specific configuration can be expressed by adding a `standalone` section to SiteConfig which allows arbitrary config variables.
 
 ```
-const config: ProjectSiteConfig = {
+const config: SiteConfig = {
   // ... Other config
 
-  custom: {
+  standalone: {
     appId: 'myapp',
     myCustomVariableName: 'my custom variable value',
   }
@@ -557,30 +556,28 @@ These variables can be used in code with the `getAppConfig` function:
 getAppConfig('myapp').myCustomVariableName
 ```
 
-If you have fully converted your app over to the new module architecture, you can add custom variables to the `config` object in your `App` definition and they will be available via `getAppConfig`.
+If you have fully converted your app over to the new architecture, you can add custom variables to the `config` object in your `App` definition and they will be available via `getAppConfig`.
 
 
-Replace the .env.test file with configuration in test.site.config.tsx file
+Replace the .env.test file with configuration in site.config.test.tsx file
 ==========================================================================
 
-We're moving away from .env files because they're not expressive enough (only string types!) to configure an Open edX frontend.  Instead, the test suite has been configured to expect a `test.site.config.tsx` file.  If you're initializing an application in your tests, `frontend-base` will pick up this configuration and make it available to `getConfig()`, etc.  If you need to manually access the variables, you can import `site.config` in your test files:
-
-Note that test.site.config.tsx has a different naming scheme than `site.config.*.tsx` because it's intended to be checked in, and `site.config.*.tsx` is git-ignored.
+We're moving away from .env files because they're not expressive enough (only string types!) to configure an Open edX frontend.  Instead, the test suite has been configured to expect a `site.config.test.tsx` file.  If you're initializing an application in your tests, `frontend-base` will pick up this configuration and make it available to `getConfig()`, etc.  If you need to manually access the variables, you can import `site.config` in your test files:
 
 ```diff
 + import config from 'site.config';
 ```
 
-The Jest configuration has been set up to find `site.config` in a `test.site.config.tsx` file.
+The Jest configuration has been set up to find `site.config` in a `site.config.test.tsx` file.
 
 Once you've verified your test suite still works, you should delete the `.env.test` file.
 
-A sample `test.site.config.tsx` file:
+A sample `site.config.test.tsx` file:
 
 ```
-import { ProjectSiteConfig } from '@openedx/frontend-base';
+import { SiteConfig } from '@openedx/frontend-base';
 
-const config: ProjectSiteConfig = {
+const config: SiteConfig = {
   apps: [],
   accessTokenCookieName: 'edx-jwt-cookie-header-payload',
   baseUrl: 'http://localhost:8080',
@@ -591,9 +588,9 @@ const config: ProjectSiteConfig = {
   logoutUrl: 'http://localhost:18000/logout',
   refreshAccessTokenApiPath: '/login_refresh',
   segmentKey: '',
+  siteId: 'test',
   siteName: 'localhost',
   userInfoCookieName: 'edx-user-info',
-  appId: 'authn',
   environment: 'dev',
   ignoredErrorRegex: null,
   publicPath: '/',
@@ -629,12 +626,12 @@ Remove core-js and regenerator-runtime
 We don't need these libraries anymore, remove them from the package.json dependencies and remove any imports of them in the code.
 
 
-Create a project.scss file 
-==========================
+Create a site.scss file 
+=======================
 
 This is required if you intend to run builds from the app itself.
 
-Create a new `project.scss` file at the top of your application.  It's responsible for:
+Create a new `site.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.
@@ -643,16 +640,16 @@ Create a new `project.scss` file at the top of your application.  It's responsib
 You must then import this new stylesheet into your `site.config` file:
 
 ```diff
-+ import './project.scss';
++ import './site.scss';
 
-const config: ProjectSiteConfig = {
+const config: SiteConfig = {
   // config document
 }
 
 export default config;
 ```
 
-This file will be ignored via `.gitignore`, as it is part of your 'project', not the module library.
+This file will be ignored via `.gitignore`, as it is part of your 'site', not the module library.
 
 
 Document module-specific configuration needs
@@ -731,7 +728,7 @@ 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-project` in this repository for examples.
+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

eslint.config.js

@@ -10,7 +10,7 @@ module.exports = tseslint.config(
   {
     ignores: [
       'tools/*',
-      'test-project/*',
+      'test-site/*',
       'config/*',
       'docs/*',
     ],

frontend-base.d.ts

@@ -1,5 +1,5 @@
 declare module 'site.config' {
-  export default ProjectSiteConfig;
+  export default SiteConfig;
 }
 
 declare module '*.svg' {

package.json

@@ -17,11 +17,11 @@
     "dev:shell": "npm run build && node ./tools/dist/cli/openedx.js dev:shell",
     "docs": "jsdoc -c jsdoc.json",
     "docs:watch": "nodemon -w runtime -w docs/template -w README.md -e js,jsx,ts,tsx --exec npm run docs",
-    "lint": "eslint .; npm run lint:tools; npm --prefix ./test-project run lint",
+    "lint": "eslint .; npm run lint:tools; npm --prefix ./test-site run lint",
     "lint:tools": "cd ./tools && eslint . && cd ..",
     "test": "jest",
-    "test-project": "npm --prefix ./test-project i; npm --prefix ./test-project run build",
-    "test-project:refresh": "npm run build && npm pack && cd test-project && npm i --audit=false --fund=false ../openedx-frontend-base-1.0.0.tgz && cd ../"
+    "test-site:build": "npm --prefix ./test-site i; npm --prefix ./test-site run build",
+    "test-site:refresh": "npm run build && npm pack && cd test-site && npm i --audit=false --fund=false ../openedx-frontend-base-1.0.0.tgz && cd ../"
   },
   "repository": {
     "type": "git",

runtime/config/index.ts

@@ -128,7 +128,7 @@ let config: SiteConfig = {
   externalRoutes: [],
   externalLinkUrlOverrides: [],
 
-  appId: '',
+  siteId: '',
   baseUrl: '',
   siteName: '',
 
@@ -139,7 +139,7 @@ let config: SiteConfig = {
   // Backends
   lmsBaseUrl: '',
 
-  custom: {
+  standalone: {
     appId: '',
   },
 };
@@ -200,7 +200,7 @@ export function setConfig(newConfig: SiteConfig) {
  *
  * @param {Object} newConfig
  */
-export function mergeConfig(newConfig: Partial<Partial<OptionalSiteConfig> & RequiredSiteConfig>) {
+export function mergeConfig(newConfig: Partial<SiteConfig>) {
   config = merge(config, newConfig);
   publish(CONFIG_CHANGED);
 }
@@ -214,6 +214,8 @@ const appConfigs: Record<string, AppConfig> = {};
  */
 export function addAppConfigs() {
   const { apps } = getConfig();
+  if (!apps) return;
+
   for (const app of apps) {
     if (app.config !== undefined) {
       patchAppConfig(app.config);

runtime/i18n/lib.ts

@@ -143,10 +143,14 @@ export function getLocale(locale?: string) {
   }
   // 2. User setting in cookie
 
-  const cookieLangPref = cookies.get(getConfig().languagePreferenceCookieName);
-  if (cookieLangPref) {
-    return findSupportedLocale(cookieLangPref.toLowerCase());
+  const { languagePreferenceCookieName } = getConfig();
+  if (languagePreferenceCookieName) {
+    const languagePreference = cookies.get(languagePreferenceCookieName);
+    if (languagePreference) {
+      return findSupportedLocale(languagePreference.toLowerCase());
+    }
   }
+
   // 3. Browser language (default)
   // Note that some browers prefer upper case for the region part of the locale, while others don't.
   // Thus the toLowerCase, for consistency.
@@ -240,9 +244,11 @@ export function mergeMessages(newMessages = {}) {
  */
 export function addAppMessages() {
   const { apps } = getConfig();
-  apps.forEach((app) => {
-    mergeMessages(app.messages);
-  });
+  if (apps) {
+    apps.forEach((app) => {
+      mergeMessages(app.messages);
+    });
+  }
 }
 
 interface ConfigureI18nOptions {