docs: update outdated info, reword, reformat

README.md

@@ -26,23 +26,16 @@ In addition, frontend-platform provides an extensible application initialization
 ## Getting started
 
 ### One-time setup if you have not upgraded node/npm
-IMPORTANT: There is now a new node/npm version being used by frontend-platform as of
-https://github.com/openedx/frontend-platform/pull/259
 
 #### Install nvm
-This is highly recommended to be able to leverage different node/npm versions.
-For a some time, different repositories may be using different versions of node/npm.
-
-Alternatively, please install node16 and npm8 for use with this repository.
+This is highly recommended to be able to leverage different node/npm versions. For some time, different repositories may be using different versions of node/npm.
 
 #### Switch to node/npm version for this repo
-```nvm use```
-if you don't have the right node/npm versions, nvm will instruct you to install those
+In the project’s root directory, run `nvm use` to set your environment to the correct node version. If the required node or npm versions are not installed, nvm will prompt you to install them.
 
 #### Clean out old node modules and reinstall
 This step is needed because node now uses a different package lock format, and it's important to reinstall
-dependencies based on this new package file. Delete node_modules, and issue an `npm ci`
-
+dependencies based on this new package file. Delete `node_modules`, and run `npm ci`.
 
 ### Standard getting started steps
 
@@ -98,7 +91,7 @@ initialize({
 });
 ```
 
-When using runtime configuration via `mergeConfig` noted above, `getConfig` must be called within a component's render lifecycle for the added keys and values to be returned in the configuration object. If `getConfig` is called outside of a component's render lifecycle, the custom configuration key/value pairs will not initially be part of the object returned by `getConfig`. For example:
+When using runtime configuration via `mergeConfig` as noted above, `getConfig` must be called within a component's render lifecycle for the added keys and values to be returned in the configuration object. If `getConfig` is called outside of a component's render lifecycle, the custom configuration key/value pairs will not initially be part of the object returned by `getConfig`. For example:
 
 ```jsx
 import { getConfig } from '@edx/frontend-platform/config';
@@ -130,7 +123,7 @@ The included service implementations are:
 - Axios/JWT (auth)
 - React Intl (i18n)
 
-NOTE: As of this writing, i18n is _not_ configurable.  The `initialize()` function does not allow applications to supply an alternate i18n implementation; this is because the interface and implementation for i18n has not yet been separated and modularized.
+NOTE: As of this writing, i18n is _not_ configurable.  The `initialize()` function does not allow applications to supply an alternative i18n implementation; this is because the interface and implementation for i18n has not yet been separated and modularized.
 
 # Local Development & Testing Locally
 

docs/decisions/0007-javascript-file-configuration.rst

@@ -135,7 +135,7 @@ Anecdotally, in the past frontend-build used JSON versions of many of
 its configuration files (Babel, eslint, jest) but over time they were all
 converted to JavaScript files so we could express more complicated
 configuration needs.  Since one of the primary use cases and reasons we need a
-new configuration method is to allow developers to supply alternate
+new configuration method is to allow developers to supply alternative
 implementations of frontend-platform's core services (analytics, logging), JSON
 was effectively a non-starter.
 

src/config.js

@@ -40,10 +40,10 @@
  *
  * ###### JavaScript File Configuration
  *
- * Configuration variables can be supplied in an optional file named env.config.js.  This file must
- * export either an Object containing configuration variables or a function.  The function must
- * return an Object containing configuration variables or, alternately, a promise which resolves to
- * an Object.
+ * Configuration variables can be supplied in an optional file named env.config.js (it can also be
+ * a `.jsx`, `.ts`, or `.tsx` file).  This file must export either an Object containing configuration
+ * variables or a function.  The function must return an Object containing configuration variables or,
+ * alternatively, a promise which resolves to an Object.
  *
  * Using a function or async function allows the configuration to be resolved at runtime (because
  * the function will be executed at runtime).  This is not common, and the capability is included
@@ -89,11 +89,9 @@
  *
  * Configuration variables can also be supplied using the "runtime configuration" method, taking
  * advantage of the Micro-frontend Config API in edx-platform. More information on this API can be
- * found in the ADR which introduced it:
+ * found in [the ADR which introduced it][1].
  *
- * https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/mfe_config_api/docs/decisions/0001-mfe-config-api.rst
- *
- * The runtime configuration method can be enabled by supplying a MFE_CONFIG_API_URL via one of the other
+ * The runtime configuration method can be enabled by supplying a `MFE_CONFIG_API_URL` via one of the other
  * two configuration methods above.
  *
  * Runtime configuration is particularly useful if you need to supply different configurations to
@@ -103,9 +101,9 @@
  *
  * ##### Initialization Config Handler
  *
- * The configuration document can be extended by
- * applications at run-time using a `config` initialization handler.  Please see the Initialization
- * documentation for more information on handlers and initialization phases.
+ * The configuration document can be extended by applications at run-time using a `config`
+ * initialization handler.  Please see the Initialization documentation for more information on
+ * handlers and initialization phases.
  *
  * ```
  * initialize({
@@ -114,13 +112,15 @@
  *       mergeConfig({
  *         CUSTOM_VARIABLE: 'custom value',
  *         LMS_BASE_URL: 'http://localhost:18001' // You can override variables, but this is uncommon.
-  *       }, 'App config override handler');
+ *       }, 'App config override handler');
  *     },
  *   },
  * });
  * ```
  *
  * @module Config
+ *
+ * [1]: https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/mfe_config_api/docs/decisions/0001-mfe-config-api.rst
  */
 
 import { APP_CONFIG_INITIALIZED, CONFIG_CHANGED } from './constants';
@@ -223,7 +223,7 @@ let config = {
  * ```
  *
  * @returns {ConfigDocument}
-  */
+ */
 export function getConfig() {
   return config;
 }
@@ -313,7 +313,7 @@ export function ensureConfig(keys, requester = 'unspecified application code') {
  * In its most basic form, the initialization process loads this document via `process.env`
  * variables.  There are other ways to add configuration variables to the ConfigDocument as
  * documented above (JavaScript File Configuration, Runtime Configuration, and the Initialization
- * Config Handler)
+ * Config Handler).
  *
  * ```
  * {

src/initialize.js

@@ -314,7 +314,7 @@ export async function initialize({
 
     // This allows us to replace the implementations of the logging, analytics, and auth services
     // based on keys in the ConfigDocument.  The JavaScript File Configuration method is the only
-    // one capable of supplying an alternate implementation since it can import other modules.
+    // one capable of supplying an alternative implementation since it can import other modules.
     // If a service wasn't supplied we fall back to the default parameters on the initialize
     // function signature.
     const loggingServiceImpl = getConfig().loggingService || loggingService;

src/react/hooks/paragon/useParagonTheme.js

@@ -84,7 +84,7 @@ export const getDefaultThemeVariant = ({ themeVariants, themeVariantDefaults = {
  * A custom React hook that manages the application's theme state and injects the appropriate CSS for the theme core
  * and theme variants (e.g., light and dark modes) into the HTML document. It handles dynamically loading the theme
  * CSS based on the current theme variant, and ensures that the theme variant's CSS is preloaded for runtime theme
- * switching.This is done using "alternate" stylesheets. That is, the browser will download the CSS for the
+ * switching. This is done using "alternate" stylesheets. That is, the browser will download the CSS for the
  * non-current theme variants with a lower priority than the current one.
  *
  * The hook also responds to system theme preference changes (e.g., via the `prefers-color-scheme` media query),