@openedx/frontend-build 15.0.0-alpha.14 → 15.0.0-alpha.16

package/README.md

@@ -155,7 +155,7 @@ frontend-platform:
       dist: The sub-directory of the source code where it puts its build artifact.  Often "dist".
       */
       localModules: [
-        { moduleName: '@openedx/brand', dir: '../src/brand-openedx' }, // replace with your brand checkout
+        { moduleName: '@edx/brand', dir: '../src/brand-openedx' }, // replace with your brand checkout
         { moduleName: '@openedx/paragon/scss/core', dir: '../src/paragon', dist: 'scss/core' },
         { moduleName: '@openedx/paragon/icons', dir: '../src/paragon', dist: 'icons' },
         { moduleName: '@openedx/paragon', dir: '../src/paragon', dist: 'dist' },

package/config/.eslintrc.js

@@ -39,6 +39,7 @@ module.exports = {
   },
   globals: {
     newrelic: false,
+    PARAGON_THEME: false,
   },
   ignorePatterns: [
     'module.config.js',

package/config/data/paragonUtils.js

@@ -0,0 +1,171 @@
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Retrieves the name of the brand package from the given directory.
+ *
+ * @param {string} dir - The directory path containing the package.json file.
+ * @return {string} The name of the brand package, or an empty string if not found.
+ */
+function getBrandPackageName(dir) {
+  const appDependencies = JSON.parse(fs.readFileSync(path.resolve(dir, 'package.json'), 'utf-8')).dependencies;
+  return Object.keys(appDependencies).find((key) => key.match(/@(open)?edx\/brand/)) || '';
+}
+
+/**
+ * Attempts to extract the Paragon version from the `node_modules` of
+ * the consuming application.
+ *
+ * @param {string} dir Path to directory containing `node_modules`.
+ * @returns {string} Paragon dependency version of the consuming application
+ */
+function getParagonVersion(dir, { isBrandOverride = false } = {}) {
+  const npmPackageName = isBrandOverride ? getBrandPackageName(dir) : '@openedx/paragon';
+  const pathToPackageJson = `${dir}/node_modules/${npmPackageName}/package.json`;
+  if (!fs.existsSync(pathToPackageJson)) {
+    return undefined;
+  }
+  return JSON.parse(fs.readFileSync(pathToPackageJson, 'utf-8')).version;
+}
+
+/**
+ * @typedef {Object} ParagonThemeCssAsset
+ * @property {string} filePath
+ * @property {string} entryName
+ * @property {string} outputChunkName
+ */
+
+/**
+ * @typedef {Object} ParagonThemeVariantCssAsset
+ * @property {string} filePath
+ * @property {string} entryName
+ * @property {string} outputChunkName
+ */
+
+/**
+ * @typedef {Object} ParagonThemeCss
+ * @property {ParagonThemeCssAsset} core The metadata about the core Paragon theme CSS
+ * @property {Object.<string, ParagonThemeVariantCssAsset>} variants A collection of theme variants.
+ */
+
+/**
+ * Attempts to extract the Paragon theme CSS from the locally installed `@openedx/paragon` package.
+ * @param {string} dir Path to directory containing `node_modules`.
+ * @param {boolean} isBrandOverride
+ * @returns {ParagonThemeCss}
+ */
+function getParagonThemeCss(dir, { isBrandOverride = false } = {}) {
+  const npmPackageName = isBrandOverride ? getBrandPackageName(dir) : '@openedx/paragon';
+  const pathToParagonThemeOutput = path.resolve(dir, 'node_modules', npmPackageName, 'dist', 'theme-urls.json');
+
+  if (!fs.existsSync(pathToParagonThemeOutput)) {
+    return undefined;
+  }
+  const paragonConfig = JSON.parse(fs.readFileSync(pathToParagonThemeOutput, 'utf-8'));
+  const {
+    core: themeCore,
+    variants: themeVariants,
+    defaults,
+  } = paragonConfig?.themeUrls || {};
+
+  const pathToCoreCss = path.resolve(dir, 'node_modules', npmPackageName, 'dist', themeCore.paths.minified);
+  const coreCssExists = fs.existsSync(pathToCoreCss);
+
+  const themeVariantResults = Object.entries(themeVariants || {}).reduce((themeVariantAcc, [themeVariant, value]) => {
+    const themeVariantCssDefault = path.resolve(dir, 'node_modules', npmPackageName, 'dist', value.paths.default);
+    const themeVariantCssMinified = path.resolve(dir, 'node_modules', npmPackageName, 'dist', value.paths.minified);
+
+    if (!fs.existsSync(themeVariantCssDefault) && !fs.existsSync(themeVariantCssMinified)) {
+      return themeVariantAcc;
+    }
+
+    return ({
+      ...themeVariantAcc,
+      [themeVariant]: {
+        filePath: themeVariantCssMinified,
+        entryName: isBrandOverride ? `brand.theme.variants.${themeVariant}` : `paragon.theme.variants.${themeVariant}`,
+        outputChunkName: isBrandOverride ? `brand-theme-variants-${themeVariant}` : `paragon-theme-variants-${themeVariant}`,
+      },
+    });
+  }, {});
+
+  if (!coreCssExists || themeVariantResults.length === 0) {
+    return undefined;
+  }
+
+  const coreResult = {
+    filePath: path.resolve(dir, pathToCoreCss),
+    entryName: isBrandOverride ? 'brand.theme.core' : 'paragon.theme.core',
+    outputChunkName: isBrandOverride ? 'brand-theme-core' : 'paragon-theme-core',
+  };
+
+  return {
+    core: fs.existsSync(pathToCoreCss) ? coreResult : undefined,
+    variants: themeVariantResults,
+    defaults,
+  };
+}
+
+/**
+ * @typedef CacheGroup
+ * @property {string} type The type of cache group.
+ * @property {string|function} name The name of the cache group.
+ * @property {function} chunks A function that returns true if the chunk should be included in the cache group.
+ * @property {boolean} enforce If true, this cache group will be created even if it conflicts with default cache groups.
+ */
+
+/**
+ * @param {ParagonThemeCss} paragonThemeCss The Paragon theme CSS metadata.
+ * @returns {Object.<string, CacheGroup>} The cache groups for the Paragon theme CSS.
+ */
+function getParagonCacheGroups(paragonThemeCss) {
+  if (!paragonThemeCss) {
+    return {};
+  }
+  const cacheGroups = {
+    [paragonThemeCss.core.outputChunkName]: {
+      type: 'css/mini-extract',
+      name: paragonThemeCss.core.outputChunkName,
+      chunks: chunk => chunk.name === paragonThemeCss.core.entryName,
+      enforce: true,
+    },
+  };
+
+  Object.values(paragonThemeCss.variants).forEach(({ entryName, outputChunkName }) => {
+    cacheGroups[outputChunkName] = {
+      type: 'css/mini-extract',
+      name: outputChunkName,
+      chunks: chunk => chunk.name === entryName,
+      enforce: true,
+    };
+  });
+  return cacheGroups;
+}
+
+/**
+ * @param {ParagonThemeCss} paragonThemeCss The Paragon theme CSS metadata.
+ * @returns {Object.<string, string>} The entry points for the Paragon theme CSS. Example: ```
+ * {
+ *   "paragon.theme.core": "/path/to/node_modules/@openedx/paragon/dist/core.min.css",
+ *   "paragon.theme.variants.light": "/path/to/node_modules/@openedx/paragon/dist/light.min.css"
+ * }
+ * ```
+ */
+function getParagonEntryPoints(paragonThemeCss) {
+  if (!paragonThemeCss) {
+    return {};
+  }
+
+  const entryPoints = { [paragonThemeCss.core.entryName]: path.resolve(process.cwd(), paragonThemeCss.core.filePath) };
+  Object.values(paragonThemeCss.variants).forEach(({ filePath, entryName }) => {
+    entryPoints[entryName] = path.resolve(process.cwd(), filePath);
+  });
+  return entryPoints;
+}
+
+module.exports = {
+  getParagonVersion,
+  getParagonThemeCss,
+  getParagonCacheGroups,
+  getParagonEntryPoints,
+};

package/config/jest/setupTest.js

@@ -8,3 +8,38 @@ const testEnvFile = path.resolve(process.cwd(), '.env.test');
 if (fs.existsSync(testEnvFile)) {
   dotenv.config({ path: testEnvFile });
 }
+
+global.PARAGON_THEME = {
+  paragon: {
+    version: '1.0.0',
+    themeUrls: {
+      core: {
+        fileName: 'core.min.css',
+      },
+      defaults: {
+        light: 'light',
+      },
+      variants: {
+        light: {
+          fileName: 'light.min.css',
+        },
+      },
+    },
+  },
+  brand: {
+    version: '1.0.0',
+    themeUrls: {
+      core: {
+        fileName: 'core.min.css',
+      },
+      defaults: {
+        light: 'light',
+      },
+      variants: {
+        light: {
+          fileName: 'light.min.css',
+        },
+      },
+    },
+  },
+};

package/config/webpack.common.config.js

@@ -1,8 +1,35 @@
 const path = require('path');
+const RemoveEmptyScriptsPlugin = require('webpack-remove-empty-scripts');
+
+const ParagonWebpackPlugin = require('../lib/plugins/paragon-webpack-plugin/ParagonWebpackPlugin');
+const {
+  getParagonThemeCss,
+  getParagonCacheGroups,
+  getParagonEntryPoints,
+} = require('./data/paragonUtils');
+
+const paragonThemeCss = getParagonThemeCss(process.cwd());
+const brandThemeCss = getParagonThemeCss(process.cwd(), { isBrandOverride: true });
 
 module.exports = {
   entry: {
     app: path.resolve(process.cwd(), './src/index'),
+    /**
+     * The entry points for the Paragon theme CSS. Example: ```
+     * {
+     *   "paragon.theme.core": "/path/to/node_modules/@openedx/paragon/dist/core.min.css",
+     *   "paragon.theme.variants.light": "/path/to/node_modules/@openedx/paragon/dist/light.min.css"
+     * }
+     */
+    ...getParagonEntryPoints(paragonThemeCss),
+    /**
+     * The entry points for the brand theme CSS. Example: ```
+     * {
+     *   "paragon.theme.core": "/path/to/node_modules/@(open)edx/brand/dist/core.min.css",
+     *   "paragon.theme.variants.light": "/path/to/node_modules/@(open)edx/brand/dist/light.min.css"
+     * }
+     */
+    ...getParagonEntryPoints(brandThemeCss),
   },
   output: {
     path: path.resolve(process.cwd(), './dist'),
@@ -19,6 +46,23 @@ module.exports = {
     },
     extensions: ['.js', '.jsx', '.ts', '.tsx'],
   },
+  optimization: {
+    splitChunks: {
+      chunks: 'all',
+      cacheGroups: {
+        ...getParagonCacheGroups(paragonThemeCss),
+        ...getParagonCacheGroups(brandThemeCss),
+      },
+    },
+  },
+  plugins: [
+    // RemoveEmptyScriptsPlugin get rid of empty scripts generated by webpack when using mini-css-extract-plugin
+    // This helps to clean up the final bundle application
+    // See: https://www.npmjs.com/package/webpack-remove-empty-scripts#usage-with-mini-css-extract-plugin
+
+    new RemoveEmptyScriptsPlugin(),
+    new ParagonWebpackPlugin(),
+  ],
   ignoreWarnings: [
     // Ignore warnings raised by source-map-loader.
     // some third party packages may ship miss-configured sourcemaps, that interrupts the build

package/config/webpack.dev-stage.config.js

@@ -157,6 +157,7 @@ module.exports = merge(commonConfig, {
     new HtmlWebpackPlugin({
       inject: true, // Appends script tags linking to the webpack bundles at the end of the body
       template: path.resolve(process.cwd(), 'public/index.html'),
+      chunks: ['app'],
       FAVICON_URL: process.env.FAVICON_URL || null,
       OPTIMIZELY_PROJECT_ID: process.env.OPTIMIZELY_PROJECT_ID || null,
       NODE_ENV: process.env.NODE_ENV || null,

package/config/webpack.dev.config.js

@@ -1,7 +1,7 @@
 // This is the dev Webpack config. All settings here should prefer a fast build
 // time at the expense of creating larger, unoptimized bundles.
 const ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');
-
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
 const { merge } = require('webpack-merge');
 const Dotenv = require('dotenv-webpack');
 const dotenv = require('dotenv');
@@ -31,6 +31,47 @@ resolvePrivateEnvConfig('.env.private');
 const aliases = getLocalAliases();
 const PUBLIC_PATH = process.env.PUBLIC_PATH || '/';
 
+function getStyleUseConfig() {
+  return [
+    {
+      loader: 'css-loader', // translates CSS into CommonJS
+      options: {
+        sourceMap: true,
+        modules: {
+          compileType: 'icss',
+        },
+      },
+    },
+    {
+      loader: 'postcss-loader',
+      options: {
+        postcssOptions: {
+          plugins: [
+            PostCssAutoprefixerPlugin(),
+            PostCssRTLCSS(),
+            PostCssCustomMediaCSS(),
+          ],
+        },
+      },
+    },
+    'resolve-url-loader',
+    {
+      loader: 'sass-loader', // compiles Sass to CSS
+      options: {
+        sourceMap: true,
+        sassOptions: {
+          includePaths: [
+            path.join(process.cwd(), 'node_modules'),
+            path.join(process.cwd(), 'src'),
+          ],
+          // silences compiler warnings regarding deprecation warnings
+          quietDeps: true,
+        },
+      },
+    },
+  ];
+}
+
 module.exports = merge(commonConfig, {
   mode: 'development',
   devtool: 'eval-source-map',
@@ -68,43 +109,19 @@ module.exports = merge(commonConfig, {
       // flash-of-unstyled-content issues in development.
       {
         test: /(.scss|.css)$/,
-        use: [
-          'style-loader', // creates style nodes from JS strings
+        oneOf: [
           {
-            loader: 'css-loader', // translates CSS into CommonJS
-            options: {
-              sourceMap: true,
-              modules: {
-                compileType: 'icss',
-              },
-            },
-          },
-          {
-            loader: 'postcss-loader',
-            options: {
-              postcssOptions: {
-                plugins: [
-                  PostCssAutoprefixerPlugin(),
-                  PostCssRTLCSS(),
-                  PostCssCustomMediaCSS(),
-                ],
-              },
-            },
+            resource: /(@openedx\/paragon|@(open)?edx\/brand)/,
+            use: [
+              MiniCssExtractPlugin.loader,
+              ...getStyleUseConfig(),
+            ],
           },
-          'resolve-url-loader',
           {
-            loader: 'sass-loader', // compiles Sass to CSS
-            options: {
-              sourceMap: true,
-              sassOptions: {
-                includePaths: [
-                  path.join(process.cwd(), 'node_modules'),
-                  path.join(process.cwd(), 'src'),
-                ],
-                // silences compiler warnings regarding deprecation warnings
-                quietDeps: true,
-              },
-            },
+            use: [
+              'style-loader', // creates style nodes from JS strings
+              ...getStyleUseConfig(),
+            ],
           },
         ],
       },
@@ -156,10 +173,15 @@ module.exports = merge(commonConfig, {
   },
   // Specify additional processing or side-effects done on the Webpack output bundles as a whole.
   plugins: [
+    // Writes the extracted CSS from each entry to a file in the output directory.
+    new MiniCssExtractPlugin({
+      filename: '[name].css',
+    }),
     // Generates an HTML file in the output directory.
     new HtmlWebpackPlugin({
       inject: true, // Appends script tags linking to the webpack bundles at the end of the body
       template: path.resolve(process.cwd(), 'public/index.html'),
+      chunks: ['app'],
       FAVICON_URL: process.env.FAVICON_URL || null,
       OPTIMIZELY_PROJECT_ID: process.env.OPTIMIZELY_PROJECT_ID || null,
       NODE_ENV: process.env.NODE_ENV || null,

package/config/webpack.prod.config.js

@@ -114,8 +114,8 @@ module.exports = merge(commonConfig, {
                 plugins: [
                   PostCssAutoprefixerPlugin(),
                   PostCssRTLCSS(),
-                  CssNano(),
                   PostCssCustomMediaCSS(),
+                  CssNano(),
                   ...extraPostCssPlugins,
                 ],
               },
@@ -202,6 +202,7 @@ module.exports = merge(commonConfig, {
     new HtmlWebpackPlugin({
       inject: true, // Appends script tags linking to the webpack bundles at the end of the body
       template: path.resolve(process.cwd(), 'public/index.html'),
+      chunks: ['app'],
       FAVICON_URL: process.env.FAVICON_URL || null,
       OPTIMIZELY_PROJECT_ID: process.env.OPTIMIZELY_PROJECT_ID || null,
       NODE_ENV: process.env.NODE_ENV || null,

package/lib/plugins/paragon-webpack-plugin/ParagonWebpackPlugin.js

@@ -0,0 +1,126 @@
+const { Compilation, sources } = require('webpack');
+const {
+  getParagonVersion,
+  getParagonThemeCss,
+} = require('../../../config/data/paragonUtils');
+const {
+  injectMetadataIntoDocument,
+  getParagonStylesheetUrls,
+  injectParagonCoreStylesheets,
+  injectParagonThemeVariantStylesheets,
+} = require('./utils');
+
+// Get Paragon and brand versions / CSS files from disk.
+const paragonVersion = getParagonVersion(process.cwd());
+const paragonThemeCss = getParagonThemeCss(process.cwd());
+const brandVersion = getParagonVersion(process.cwd(), { isBrandOverride: true });
+const brandThemeCss = getParagonThemeCss(process.cwd(), { isBrandOverride: true });
+
+/**
+ * 1. Injects `PARAGON_THEME` global variable into the HTML document during the Webpack compilation process.
+ * 2. Injects `<link rel="preload" as="style">` element(s) for the Paragon and brand CSS into the HTML document.
+ */
+class ParagonWebpackPlugin {
+  constructor({ processAssetsHandlers = [] } = {}) {
+    this.pluginName = 'ParagonWebpackPlugin';
+    this.paragonThemeUrlsConfig = {};
+    this.paragonMetadata = {};
+
+    // List of handlers to be executed after processing assets during the Webpack compilation.
+    this.processAssetsHandlers = [
+      this.resolveParagonThemeUrlsFromConfig,
+      this.injectParagonMetadataIntoDocument,
+      this.injectParagonStylesheetsIntoDocument,
+      ...processAssetsHandlers,
+    ].map(handler => handler.bind(this));
+  }
+
+  /**
+   * Resolves the MFE configuration from ``PARAGON_THEME_URLS`` in the environment variables. `
+   *
+   * @returns {Object} Metadata about the Paragon and brand theme URLs from configuration.
+   */
+  async resolveParagonThemeUrlsFromConfig() {
+    try {
+      this.paragonThemeUrlsConfig = JSON.parse(process.env.PARAGON_THEME_URLS);
+    } catch (error) {
+      console.info('Paragon Plugin cannot load PARAGON_THEME_URLS env variable, skipping.');
+    }
+  }
+
+  /**
+   * Generates `PARAGON_THEME` global variable in HTML document.
+   * @param {Object} compilation Webpack compilation object.
+   */
+  injectParagonMetadataIntoDocument(compilation) {
+    const paragonMetadata = injectMetadataIntoDocument(compilation, {
+      paragonThemeCss,
+      paragonVersion,
+      brandThemeCss,
+      brandVersion,
+    });
+    if (paragonMetadata) {
+      this.paragonMetadata = paragonMetadata;
+    }
+  }
+
+  injectParagonStylesheetsIntoDocument(compilation) {
+    const file = compilation.getAsset('index.html');
+
+    // If the `index.html` hasn't loaded yet, or there are no Paragon theme URLs, then there is nothing to do yet.
+    if (!file || Object.keys(this.paragonThemeUrlsConfig || {}).length === 0) {
+      return;
+    }
+
+    // Generates `<link rel="preload" as="style">` element(s) for the Paragon and brand CSS files.
+    const paragonStylesheetUrls = getParagonStylesheetUrls({
+      paragonThemeUrls: this.paragonThemeUrlsConfig,
+      paragonVersion,
+      brandVersion,
+    });
+    const {
+      core: paragonCoreCss,
+      variants: paragonThemeVariantCss,
+    } = paragonStylesheetUrls;
+
+    const originalSource = file.source.source();
+
+    // Inject core CSS
+    let newSource = injectParagonCoreStylesheets({
+      source: originalSource,
+      paragonCoreCss,
+      paragonThemeCss,
+      brandThemeCss,
+    });
+
+    // Inject theme variant CSS
+    newSource = injectParagonThemeVariantStylesheets({
+      source: newSource.source(),
+      paragonThemeVariantCss,
+      paragonThemeCss,
+      brandThemeCss,
+    });
+
+    compilation.updateAsset('index.html', new sources.RawSource(newSource.source()));
+  }
+
+  apply(compiler) {
+    compiler.hooks.thisCompilation.tap(this.pluginName, (compilation) => {
+      compilation.hooks.processAssets.tap(
+        {
+          name: this.pluginName,
+          stage: Compilation.PROCESS_ASSETS_STAGE_ADDITIONS,
+          additionalAssets: true,
+        },
+        () => {
+          // Iterate through each configured handler, passing the compilation to each.
+          this.processAssetsHandlers.forEach(async (handler) => {
+            await handler(compilation);
+          });
+        },
+      );
+    });
+  }
+}
+
+module.exports = ParagonWebpackPlugin;

package/lib/plugins/paragon-webpack-plugin/index.js

@@ -0,0 +1,3 @@
+const ParagonWebpackPlugin = require('./ParagonWebpackPlugin');
+
+module.exports = ParagonWebpackPlugin;

package/lib/plugins/paragon-webpack-plugin/utils/assetUtils.js

@@ -0,0 +1,75 @@
+/**
+ * Finds the core CSS asset from the given array of Paragon assets.
+ *
+ * @param {Array} paragonAssets - An array of Paragon assets.
+ * @return {Object|undefined} The core CSS asset, or undefined if not found.
+ */
+function findCoreCssAsset(paragonAssets) {
+  return paragonAssets?.find((asset) => asset.name.includes('core') && asset.name.endsWith('.css'));
+}
+
+/**
+ * Finds the theme variant CSS assets from the given Paragon assets based on the provided options.
+ *
+ * @param {Array} paragonAssets - An array of Paragon assets.
+ * @param {Object} options - The options for finding the theme variant CSS assets.
+ * @param {boolean} [options.isBrandOverride=false] - Indicates if the theme variant is a brand override.
+ * @param {Object} [options.brandThemeCss] - The brand theme CSS object.
+ * @param {Object} [options.paragonThemeCss] - The Paragon theme CSS object.
+ * @return {Object} - The theme variant CSS assets.
+ */
+function findThemeVariantCssAssets(paragonAssets, {
+  isBrandOverride = false,
+  brandThemeCss,
+  paragonThemeCss,
+}) {
+  const themeVariantsSource = isBrandOverride ? brandThemeCss?.variants : paragonThemeCss?.variants;
+  const themeVariantCssAssets = {};
+  Object.entries(themeVariantsSource || {}).forEach(([themeVariant, value]) => {
+    const foundThemeVariantAsset = paragonAssets.find((asset) => asset.name.includes(value.outputChunkName));
+    if (!foundThemeVariantAsset) {
+      return;
+    }
+    themeVariantCssAssets[themeVariant] = {
+      fileName: foundThemeVariantAsset.name,
+    };
+  });
+  return themeVariantCssAssets;
+}
+
+/**
+ * Retrieves the CSS assets from the compilation based on the provided options.
+ *
+ * @param {Object} compilation - The compilation object.
+ * @param {Object} options - The options for retrieving the CSS assets.
+ * @param {boolean} [options.isBrandOverride=false] - Indicates if the assets are for a brand override.
+ * @param {Object} [options.brandThemeCss] - The brand theme CSS object.
+ * @param {Object} [options.paragonThemeCss] - The Paragon theme CSS object.
+ * @return {Object} - The CSS assets, including the core CSS asset and theme variant CSS assets.
+ */
+function getCssAssetsFromCompilation(compilation, {
+  isBrandOverride = false,
+  brandThemeCss,
+  paragonThemeCss,
+}) {
+  const assetSubstring = isBrandOverride ? 'brand' : 'paragon';
+  const paragonAssets = compilation.getAssets().filter(asset => asset.name.includes(assetSubstring) && asset.name.endsWith('.css'));
+  const coreCssAsset = findCoreCssAsset(paragonAssets);
+  const themeVariantCssAssets = findThemeVariantCssAssets(paragonAssets, {
+    isBrandOverride,
+    paragonThemeCss,
+    brandThemeCss,
+  });
+  return {
+    coreCssAsset: {
+      fileName: coreCssAsset?.name,
+    },
+    themeVariantCssAssets,
+  };
+}
+
+module.exports = {
+  findCoreCssAsset,
+  findThemeVariantCssAssets,
+  getCssAssetsFromCompilation,
+};

package/lib/plugins/paragon-webpack-plugin/utils/htmlUtils.js

@@ -0,0 +1,69 @@
+const { sources } = require('webpack');
+
+const { getCssAssetsFromCompilation } = require('./assetUtils');
+const { generateScriptContents, insertScriptContentsIntoDocument } = require('./scriptUtils');
+
+/**
+ * Injects metadata into the HTML document by modifying the 'index.html' asset in the compilation.
+ *
+ * @param {Object} compilation - The Webpack compilation object.
+ * @param {Object} options - The options object.
+ * @param {Object} options.paragonThemeCss - The Paragon theme CSS object.
+ * @param {string} options.paragonVersion - The version of the Paragon theme.
+ * @param {Object} options.brandThemeCss - The brand theme CSS object.
+ * @param {string} options.brandVersion - The version of the brand theme.
+ * @return {Object|undefined} The script contents object if the 'index.html' asset exists, otherwise undefined.
+ */
+function injectMetadataIntoDocument(compilation, {
+  paragonThemeCss,
+  paragonVersion,
+  brandThemeCss,
+  brandVersion,
+}) {
+  const file = compilation.getAsset('index.html');
+  if (!file) {
+    return undefined;
+  }
+  const {
+    coreCssAsset: paragonCoreCssAsset,
+    themeVariantCssAssets: paragonThemeVariantCssAssets,
+  } = getCssAssetsFromCompilation(compilation, {
+    brandThemeCss,
+    paragonThemeCss,
+  });
+  const {
+    coreCssAsset: brandCoreCssAsset,
+    themeVariantCssAssets: brandThemeVariantCssAssets,
+  } = getCssAssetsFromCompilation(compilation, {
+    isBrandOverride: true,
+    brandThemeCss,
+    paragonThemeCss,
+  });
+
+  const scriptContents = generateScriptContents({
+    paragonCoreCssAsset,
+    paragonThemeVariantCssAssets,
+    brandCoreCssAsset,
+    brandThemeVariantCssAssets,
+    paragonThemeCss,
+    paragonVersion,
+    brandThemeCss,
+    brandVersion,
+  });
+
+  const originalSource = file.source.source();
+  const newSource = insertScriptContentsIntoDocument({
+    originalSource,
+    coreCssAsset: paragonCoreCssAsset,
+    themeVariantCssAssets: paragonThemeVariantCssAssets,
+    scriptContents,
+  });
+
+  compilation.updateAsset('index.html', new sources.RawSource(newSource.source()));
+
+  return scriptContents;
+}
+
+module.exports = {
+  injectMetadataIntoDocument,
+};

package/lib/plugins/paragon-webpack-plugin/utils/index.js

@@ -0,0 +1,9 @@
+const { getParagonStylesheetUrls, injectParagonCoreStylesheets, injectParagonThemeVariantStylesheets } = require('./paragonStylesheetUtils');
+const { injectMetadataIntoDocument } = require('./htmlUtils');
+
+module.exports = {
+  injectMetadataIntoDocument,
+  getParagonStylesheetUrls,
+  injectParagonCoreStylesheets,
+  injectParagonThemeVariantStylesheets,
+};

package/lib/plugins/paragon-webpack-plugin/utils/paragonStylesheetUtils.js

@@ -0,0 +1,120 @@
+const { insertStylesheetsIntoDocument } = require('./stylesheetUtils');
+const { handleVersionSubstitution } = require('./tagUtils');
+
+/**
+ * Injects Paragon core stylesheets into the document.
+ *
+ * @param {Object} options - The options object.
+ * @param {string|object} options.source - The source HTML document.
+ * @param {Object} options.paragonCoreCss - The Paragon core CSS object.
+ * @param {Object} options.paragonThemeCss - The Paragon theme CSS object.
+ * @param {Object} options.brandThemeCss - The brand theme CSS object.
+ * @return {string|object} The modified HTML document with Paragon core stylesheets injected.
+ */
+function injectParagonCoreStylesheets({
+  source,
+  paragonCoreCss,
+  paragonThemeCss,
+  brandThemeCss,
+}) {
+  return insertStylesheetsIntoDocument({
+    source,
+    urls: paragonCoreCss.urls,
+    paragonThemeCss,
+    brandThemeCss,
+  });
+}
+
+/**
+ * Injects Paragon theme variant stylesheets into the document.
+ *
+ * @param {Object} options - The options object.
+ * @param {string|object} options.source - The source HTML document.
+ * @param {Object} options.paragonThemeVariantCss - The Paragon theme variant CSS object.
+ * @param {Object} options.paragonThemeCss - The Paragon theme CSS object.
+ * @param {Object} options.brandThemeCss - The brand theme CSS object.
+ * @return {string|object} The modified HTML document with Paragon theme variant stylesheets injected.
+ */
+function injectParagonThemeVariantStylesheets({
+  source,
+  paragonThemeVariantCss,
+  paragonThemeCss,
+  brandThemeCss,
+}) {
+  let newSource = source;
+  Object.values(paragonThemeVariantCss).forEach(({ urls }) => {
+    newSource = insertStylesheetsIntoDocument({
+      source: typeof newSource === 'object' ? newSource.source() : newSource,
+      urls,
+      paragonThemeCss,
+      brandThemeCss,
+    });
+  });
+  return newSource;
+}
+/**
+ * Retrieves the URLs of the Paragon stylesheets based on the provided theme URLs, Paragon version, and brand version.
+ *
+ * @param {Object} options - The options object.
+ * @param {Object} options.paragonThemeUrls - The URLs of the Paragon theme.
+ * @param {string} options.paragonVersion - The version of the Paragon theme.
+ * @param {string} options.brandVersion - The version of the brand theme.
+ * @return {Object} An object containing the URLs of the Paragon stylesheets.
+ */
+function getParagonStylesheetUrls({ paragonThemeUrls, paragonVersion, brandVersion }) {
+  const paragonCoreCssUrl = typeof paragonThemeUrls.core.urls === 'object' ? paragonThemeUrls.core.urls.default : paragonThemeUrls.core.url;
+  const brandCoreCssUrl = typeof paragonThemeUrls.core.urls === 'object' ? paragonThemeUrls.core.urls.brandOverride : undefined;
+
+  const defaultThemeVariants = paragonThemeUrls.defaults || {};
+
+  const coreCss = {
+    urls: {
+      default: handleVersionSubstitution({ url: paragonCoreCssUrl, wildcardKeyword: '$paragonVersion', localVersion: paragonVersion }),
+      brandOverride: handleVersionSubstitution({ url: brandCoreCssUrl, wildcardKeyword: '$brandVersion', localVersion: brandVersion }),
+    },
+  };
+
+  const themeVariantsCss = {};
+  const themeVariantsEntries = Object.entries(paragonThemeUrls.variants || {});
+  themeVariantsEntries.forEach(([themeVariant, { url, urls }]) => {
+    const themeVariantMetadata = { urls: null };
+    if (url) {
+      themeVariantMetadata.urls = {
+        default: handleVersionSubstitution({
+          url,
+          wildcardKeyword: '$paragonVersion',
+          localVersion: paragonVersion,
+        }),
+        // If there is no brand override URL, then we don't need to do any version substitution
+        // but we still need to return the property.
+        brandOverride: undefined,
+      };
+    } else {
+      themeVariantMetadata.urls = {
+        default: handleVersionSubstitution({
+          url: urls.default,
+          wildcardKeyword: '$paragonVersion',
+          localVersion: paragonVersion,
+        }),
+        brandOverride: handleVersionSubstitution({
+          url: urls.brandOverride,
+          wildcardKeyword: '$brandVersion',
+          localVersion: brandVersion,
+        }),
+      };
+    }
+    themeVariantsCss[themeVariant] = themeVariantMetadata;
+  });
+
+  return {
+    core: coreCss,
+    variants: themeVariantsCss,
+    defaults: defaultThemeVariants,
+  };
+}
+
+module.exports = {
+  injectParagonCoreStylesheets,
+  injectParagonThemeVariantStylesheets,
+  getParagonStylesheetUrls,
+};

package/lib/plugins/paragon-webpack-plugin/utils/scriptUtils.js

@@ -0,0 +1,144 @@
+const { sources } = require('webpack');
+const parse5 = require('parse5');
+
+const { getDescendantByTag, minifyScript } = require('./tagUtils');
+
+/**
+ * Finds the insertion point for a script in an HTML document.
+ *
+ * @param {Object} options - The options object.
+ * @param {Object} options.document - The parsed HTML document.
+ * @param {string} options.originalSource - The original source code of the HTML document.
+ * @throws {Error} If the body element is missing in the HTML document.
+ * @return {number} The insertion point for the script in the HTML document.
+ */
+function findScriptInsertionPoint({ document, originalSource }) {
+  const bodyElement = getDescendantByTag(document, 'body');
+  if (!bodyElement) {
+    throw new Error('Missing body element in index.html.');
+  }
+
+  // determine script insertion point
+  if (bodyElement.sourceCodeLocation?.endTag) {
+    return bodyElement.sourceCodeLocation.endTag.startOffset;
+  }
+
+  // less accurate fallback
+  return originalSource.indexOf('</body>');
+}
+
+/**
+ * Inserts the given script contents into the HTML document and returns a new source with the modified content.
+ *
+ * @param {Object} options - The options object.
+ * @param {string} options.originalSource - The original HTML source.
+ * @param {Object} options.scriptContents - The contents of the script to be inserted.
+ * @return {sources.ReplaceSource} The new source with the modified HTML content.
+ */
+function insertScriptContentsIntoDocument({
+  originalSource,
+  scriptContents,
+}) {
+  // parse file as html document
+  const document = parse5.parse(originalSource, {
+    sourceCodeLocationInfo: true,
+  });
+
+  // find the body element
+  const scriptInsertionPoint = findScriptInsertionPoint({
+    document,
+    originalSource,
+  });
+
+  // create Paragon script to inject into the HTML document
+  const paragonScript = `<script type="text/javascript">var PARAGON_THEME = ${JSON.stringify(scriptContents, null, 2)};</script>`;
+
+  // insert the Paragon script into the HTML document
+  const newSource = new sources.ReplaceSource(
+    new sources.RawSource(originalSource),
+    'index.html',
+  );
+  newSource.insert(scriptInsertionPoint, minifyScript(paragonScript));
+  return newSource;
+}
+
+/**
+ * Creates an object with the provided version, defaults, coreCssAsset, and themeVariantCssAssets
+ * and returns it. The returned object has the following structure:
+ * {
+ *   version: The provided version,
+ *   themeUrls: {
+ *     core: The provided coreCssAsset,
+ *     variants: The provided themeVariantCssAssets,
+ *     defaults: The provided defaults
+ *   }
+ * }
+ *
+ * @param {Object} options - The options object.
+ * @param {string} options.version - The version to be added to the returned object.
+ * @param {Object} options.defaults - The defaults to be added to the returned object.
+ * @param {Object} options.coreCssAsset - The coreCssAsset to be added to the returned object.
+ * @param {Object} options.themeVariantCssAssets - The themeVariantCssAssets to be added to the returned object.
+ * @return {Object} The object with the provided version, defaults, coreCssAsset, and themeVariantCssAssets.
+ */
+function addToScriptContents({
+  version,
+  defaults,
+  coreCssAsset,
+  themeVariantCssAssets,
+}) {
+  return {
+    version,
+    themeUrls: {
+      core: coreCssAsset,
+      variants: themeVariantCssAssets,
+      defaults,
+    },
+  };
+}
+
+/**
+ * Generates the script contents object based on the provided assets and versions.
+ *
+ * @param {Object} options - The options object.
+ * @param {Object} options.paragonCoreCssAsset - The asset for the Paragon core CSS.
+ * @param {Object} options.paragonThemeVariantCssAssets - The assets for the Paragon theme variants.
+ * @param {Object} options.brandCoreCssAsset - The asset for the brand core CSS.
+ * @param {Object} options.brandThemeVariantCssAssets - The assets for the brand theme variants.
+ * @param {Object} options.paragonThemeCss - The Paragon theme CSS.
+ * @param {string} options.paragonVersion - The version of the Paragon theme.
+ * @param {Object} options.brandThemeCss - The brand theme CSS.
+ * @param {string} options.brandVersion - The version of the brand theme.
+ * @return {Object} The script contents object.
+ */
+function generateScriptContents({
+  paragonCoreCssAsset,
+  paragonThemeVariantCssAssets,
+  brandCoreCssAsset,
+  brandThemeVariantCssAssets,
+  paragonThemeCss,
+  paragonVersion,
+  brandThemeCss,
+  brandVersion,
+}) {
+  const scriptContents = {};
+  scriptContents.paragon = addToScriptContents({
+    version: paragonVersion,
+    coreCssAsset: paragonCoreCssAsset,
+    themeVariantCssAssets: paragonThemeVariantCssAssets,
+    defaults: paragonThemeCss?.defaults,
+  });
+  scriptContents.brand = addToScriptContents({
+    version: brandVersion,
+    coreCssAsset: brandCoreCssAsset,
+    themeVariantCssAssets: brandThemeVariantCssAssets,
+    defaults: brandThemeCss?.defaults,
+  });
+  return scriptContents;
+}
+
+module.exports = {
+  addToScriptContents,
+  insertScriptContentsIntoDocument,
+  generateScriptContents,
+};

package/lib/plugins/paragon-webpack-plugin/utils/stylesheetUtils.js

@@ -0,0 +1,107 @@
+const parse5 = require('parse5');
+const { sources } = require('webpack');
+
+const { getDescendantByTag } = require('./tagUtils');
+
+/**
+ * Finds the insertion point for a stylesheet in an HTML document.
+ *
+ * @param {Object} options - The options object.
+ * @param {Object} options.document - The parsed HTML document.
+ * @param {string} options.source - The original source code of the HTML document.
+ * @throws {Error} If the head element is missing in the HTML document.
+ * @return {number} The insertion point for the stylesheet in the HTML document.
+ */
+function findStylesheetInsertionPoint({ document, source }) {
+  const headElement = getDescendantByTag(document, 'head');
+  if (!headElement) {
+    throw new Error('Missing head element in index.html.');
+  }
+
+  // determine script insertion point
+  if (headElement.sourceCodeLocation?.startTag) {
+    return headElement.sourceCodeLocation.startTag.endOffset;
+  }
+
+  // less accurate fallback
+  const headTagString = '<head>';
+  const headTagIndex = source.indexOf(headTagString);
+  return headTagIndex + headTagString.length;
+}
+
+/**
+ * Inserts stylesheets into an HTML document.
+ *
+ * @param {object} options - The options for inserting stylesheets.
+ * @param {string} options.source - The HTML source code.
+ * @param {object} options.urls - The URLs of the stylesheets to be inserted.
+ * @param {string} options.urls.default - The URL of the default stylesheet.
+ * @param {string} options.urls.brandOverride - The URL of the brand override stylesheet.
+ * @return {object} The new source code with the stylesheets inserted.
+ */
+function insertStylesheetsIntoDocument({
+  source,
+  urls,
+}) {
+  // parse file as html document
+  const document = parse5.parse(source, {
+    sourceCodeLocationInfo: true,
+  });
+  if (!getDescendantByTag(document, 'head')) {
+    return undefined;
+  }
+
+  const newSource = new sources.ReplaceSource(
+    new sources.RawSource(source),
+    'index.html',
+  );
+
+  // insert the brand overrides styles into the HTML document
+  const stylesheetInsertionPoint = findStylesheetInsertionPoint({
+    document,
+    source: newSource,
+  });
+
+  /**
+   * Creates a new stylesheet link element.
+   *
+   * @param {string} url - The URL of the stylesheet.
+   * @return {string} The HTML code for the stylesheet link element.
+   */
+  function createNewStylesheet(url) {
+    const baseLink = `<link
+      type="text/css"
+      rel="preload"
+      as="style"
+      href="${url}"
+      onload="this.rel='stylesheet';"
+      onerror="this.remove();"
+    />`;
+    return baseLink;
+  }
+
+  if (urls.default) {
+    const existingDefaultLink = getDescendantByTag(`link[href='${urls.default}']`);
+    if (!existingDefaultLink) {
+      // create link to inject into the HTML document
+      const stylesheetLink = createNewStylesheet(urls.default);
+      newSource.insert(stylesheetInsertionPoint, stylesheetLink);
+    }
+  }
+
+  if (urls.brandOverride) {
+    const existingBrandLink = getDescendantByTag(`link[href='${urls.brandOverride}']`);
+    if (!existingBrandLink) {
+      // create link to inject into the HTML document
+      const stylesheetLink = createNewStylesheet(urls.brandOverride);
+      newSource.insert(stylesheetInsertionPoint, stylesheetLink);
+    }
+  }
+
+  return newSource;
+}
+
+module.exports = {
+  findStylesheetInsertionPoint,
+  insertStylesheetsIntoDocument,
+};

package/lib/plugins/paragon-webpack-plugin/utils/tagUtils.js

@@ -0,0 +1,58 @@
+/**
+ * Recursively searches for a descendant node with the specified tag name.
+ *
+ * @param {Object} node - The root node to start the search from.
+ * @param {string} tag - The tag name to search for.
+ * @return {Object|null} The first descendant node with the specified tag name, or null if not found.
+ */
+function getDescendantByTag(node, tag) {
+  for (let i = 0; i < node.childNodes?.length; i++) {
+    if (node.childNodes[i].tagName === tag) {
+      return node.childNodes[i];
+    }
+    const result = getDescendantByTag(node.childNodes[i], tag);
+    if (result) {
+      return result;
+    }
+  }
+  return null;
+}
+
+/**
+ * Replaces a wildcard keyword in a URL with a local version.
+ *
+ * @param {Object} options - The options object.
+ * @param {string} options.url - The URL to substitute the keyword in.
+ * @param {string} options.wildcardKeyword - The wildcard keyword to replace.
+ * @param {string} options.localVersion - The local version to substitute the keyword with.
+ * @return {string} The URL with the wildcard keyword substituted with the local version,
+ *                 or the original URL if no substitution is needed.
+ */
+function handleVersionSubstitution({ url, wildcardKeyword, localVersion }) {
+  if (!url || !url.includes(wildcardKeyword) || !localVersion) {
+    return url;
+  }
+  return url.replaceAll(wildcardKeyword, localVersion);
+}
+
+/**
+ * Minifies a script by removing unnecessary whitespace and line breaks.
+ *
+ * @param {string} script - The script to be minified.
+ * @return {string} The minified script.
+ */
+function minifyScript(script) {
+  return script
+    .replace(/>[\r\n ]+</g, '><')
+    .replace(/(<.*?>)|\s+/g, (m, $1) => {
+      if ($1) { return $1; }
+      return ' ';
+    })
+    .trim();
+}
+
+module.exports = {
+  getDescendantByTag,
+  handleVersionSubstitution,
+  minifyScript,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openedx/frontend-build",
-  "version": "15.0.0-alpha.14",
+  "version": "15.0.0-alpha.16",
   "description": "Build tools, setup and config for frontend apps",
   "publishConfig": {
     "access": "public"
@@ -77,6 +77,7 @@
     "jest": "29.6.1",
     "jest-environment-jsdom": "29.6.1",
     "mini-css-extract-plugin": "1.6.2",
+    "parse5": "7.1.2",
     "postcss": "8.4.39",
     "postcss-custom-media": "10.0.8",
     "postcss-loader": "7.3.4",
@@ -96,7 +97,8 @@
     "webpack-bundle-analyzer": "^4.10.1",
     "webpack-cli": "^5.1.4",
     "webpack-dev-server": "^4.15.1",
-    "webpack-merge": "^5.10.0"
+    "webpack-merge": "^5.10.0",
+    "webpack-remove-empty-scripts": "1.0.4"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.18.6",