feat: expose PARAGON as a global variable

config/.eslintrc.js

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

config/data/paragonUtils.js

@@ -0,0 +1,157 @@
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * 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) {
+  const pathToPackageJson = `${dir}/node_modules/@edx/paragon/package.json`;
+  if (!fs.existsSync(pathToPackageJson)) {
+    return undefined;
+  }
+  return JSON.parse(fs.readFileSync(pathToPackageJson)).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
+ * @property {boolean} default
+ * @property {boolean} dark
+ */
+
+/**
+ * @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 `@edx/paragon` package.
+ * @param {string} dir Path to directory containing `node_modules`.
+ * @returns {ParagonThemeCss}
+ */
+function getParagonThemeCss(dir) {
+  const pathToParagonThemeOutput = path.resolve(dir, './node_modules/@edx/paragon', 'dist', 'paragon-theme.json');
+  if (!fs.existsSync(pathToParagonThemeOutput)) {
+    return undefined;
+  }
+  const paragonConfig = JSON.parse(fs.readFileSync(pathToParagonThemeOutput));
+  const {
+    core: themeCore,
+    variants: themeVariants,
+  } = paragonConfig?.themeUrls || {};
+
+  const pathToCoreCss = path.resolve(dir, './node_modules/@edx/paragon', 'dist', themeCore.paths.minified);
+  const coreCssExists = fs.existsSync(pathToCoreCss);
+
+  const validThemeVariantPaths = Object.entries(themeVariants || {}).filter(([, value]) => {
+    const themeVariantCssDefault = path.resolve(dir, './node_modules/@edx/paragon', 'dist', value.paths.default);
+    const themeVariantCssMinified = path.resolve(dir, './node_modules/@edx/paragon', 'dist', value.paths.minified);
+    return fs.existsSync(themeVariantCssDefault) && fs.existsSync(themeVariantCssMinified);
+  });
+
+  if (!coreCssExists || validThemeVariantPaths.length === 0) {
+    return undefined;
+  }
+  const coreResult = {
+    filePath: path.resolve(dir, pathToCoreCss),
+    entryName: 'paragon.theme.core',
+    outputChunkName: 'paragon-theme-core',
+  };
+
+  const themeVariantResults = {};
+  validThemeVariantPaths.forEach(([themeVariant, value]) => {
+    themeVariantResults[themeVariant] = {
+      filePath: path.resolve(dir, './node_modules/@edx/paragon', 'dist', value.paths.minified),
+      entryName: `paragon.theme.variants.${themeVariant}`,
+      outputChunkName: `paragon-theme-variant-${themeVariant}`,
+      default: value.default,
+      dark: value.dark,
+    };
+  });
+
+  return {
+    core: fs.existsSync(pathToCoreCss) ? coreResult : undefined,
+    variants: themeVariantResults,
+  };
+}
+
+/**
+ * Replaces all periods in a string with hyphens.
+ * @param {string} str A string containing periods to replace with hyphens.
+ * @returns The input string with periods replaced with hyphens.
+ */
+function replacePeriodsWithHyphens(str) {
+  return str.replaceAll('.', '-');
+}
+
+/**
+ * @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) {
+  const cacheGroups = {};
+  if (!paragonThemeCss) {
+    return cacheGroups;
+  }
+  cacheGroups[paragonThemeCss.core.entryName] = {
+    type: 'css/mini-extract',
+    name: replacePeriodsWithHyphens(paragonThemeCss.core.entryName),
+    chunks: chunk => chunk.name === paragonThemeCss.core.entryName,
+    enforce: true,
+  };
+  Object.values(paragonThemeCss.variants).forEach(({ entryName }) => {
+    cacheGroups[entryName] = {
+      type: 'css/mini-extract',
+      name: replacePeriodsWithHyphens(entryName),
+      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.
+ */
+function getParagonEntryPoints(paragonThemeCss) {
+  const entryPoints = {};
+  if (!paragonThemeCss) {
+    return entryPoints;
+  }
+  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,
+  replacePeriodsWithHyphens,
+};

config/jest/setupTest.js

@@ -8,3 +8,19 @@ const testEnvFile = path.resolve(process.cwd(), '.env.test');
 if (fs.existsSync(testEnvFile)) {
   dotenv.config({ path: testEnvFile });
 }
+
+global.PARAGON = {
+  version: '1.0.0',
+  themeUrls: {
+    core: {
+      fileName: 'core.min.css',
+    },
+    variants: {
+      light: {
+        fileName: 'light.min.css',
+        default: true,
+        dark: false,
+      },
+    },
+  },
+};

config/webpack.common.config.js

@@ -1,8 +1,19 @@
 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());
 
 module.exports = {
   entry: {
     app: path.resolve(process.cwd(), './src/index'),
+    ...getParagonEntryPoints(paragonThemeCss),
   },
   output: {
     path: path.resolve(process.cwd(), './dist'),
@@ -19,4 +30,16 @@ module.exports = {
     },
     extensions: ['.js', '.jsx'],
   },
+  optimization: {
+    splitChunks: {
+      chunks: 'all',
+      cacheGroups: {
+        ...getParagonCacheGroups(paragonThemeCss),
+      },
+    },
+  },
+  plugins: [
+    new RemoveEmptyScriptsPlugin(),
+    new ParagonWebpackPlugin(),
+  ],
 };

config/webpack.dev-stage.config.js

@@ -155,6 +155,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,

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,45 @@ 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'),
+          ],
+        },
+      },
+    },
+  ];
+}
+
 module.exports = merge(commonConfig, {
   mode: 'development',
   devtool: 'eval-source-map',
@@ -68,41 +107,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: /paragon/,
+            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'),
-                ],
-              },
-            },
+            use: [
+              'style-loader', // creates style nodes from JS strings
+              ...getStyleUseConfig(),
+            ],
           },
         ],
       },
@@ -154,10 +171,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,

config/webpack.prod.config.js

@@ -115,8 +115,8 @@ module.exports = merge(commonConfig, {
                 plugins: [
                   PostCssAutoprefixerPlugin(),
                   PostCssRTLCSS(),
-                  CssNano(),
                   PostCssCustomMediaCSS(),
+                  CssNano(),
                   ...extraPostCssPlugins,
                 ],
               },
@@ -201,6 +201,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,

example/.env.development

@@ -1,2 +1,3 @@
+BASE_URL='http://localhost:8080'
 FAVICON_URL=https://edx-cdn.org/v3/default/favicon.ico
 TEST_VARIABLE='foo'