@openedx/frontend-base 1.0.0-alpha.0

package/tools/webpack/utils/paragonUtils.ts

@@ -0,0 +1,152 @@
+import fs from 'fs';
+import path from 'path';
+import { Chunk } from 'webpack';
+import { ParagonThemeCss, ParagonThemeUrlsFile } from '../types';
+
+/**
+ * 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: string) {
+  const appDependencies = JSON.parse(fs.readFileSync(path.resolve(dir, 'package.json'), 'utf-8')).dependencies;
+  return Object.keys(appDependencies).find((key) => /@(open)?edx\/brand/.exec(key)) ?? '';
+}
+
+/**
+ * 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
+ */
+export function getParagonVersion(dir: string, { 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;
+}
+
+/**
+ * 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}
+ */
+export function getParagonThemeCss(dir: string, { isBrandOverride = false } = {}): ParagonThemeCss | undefined {
+  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: ParagonThemeUrlsFile = 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 || Object.keys(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.
+ */
+export function getParagonCacheGroups(paragonThemeCss: ParagonThemeCss | undefined) {
+  if (!paragonThemeCss) {
+    return {};
+  }
+  const cacheGroups: Record<string, { type: string, name: string, chunks: (chunk: Chunk) => boolean, enforce: boolean }> = {};
+
+  if (paragonThemeCss.core !== undefined) {
+    const { core } = paragonThemeCss;
+    cacheGroups[paragonThemeCss.core.outputChunkName] = {
+      type: 'css/mini-extract',
+      name: paragonThemeCss.core.outputChunkName,
+      chunks: (chunk: Chunk) => chunk.name === core.entryName,
+      enforce: true,
+    };
+  }
+
+  Object.values(paragonThemeCss.variants).forEach(({ entryName, outputChunkName }) => {
+    cacheGroups[outputChunkName] = {
+      type: 'css/mini-extract',
+      name: outputChunkName,
+      chunks: (chunk: 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"
+ * }
+ * ```
+ */
+export function getParagonEntryPoints(paragonThemeCss: ParagonThemeCss | undefined) {
+  if (!paragonThemeCss) {
+    return {};
+  }
+
+  const entryPoints: Record<string, string> = {};
+  if (paragonThemeCss.core !== undefined) {
+    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;
+}

package/tools/webpack/webpack.config.build.ts

@@ -0,0 +1,93 @@
+import ForkTsCheckerWebpackPlugin from 'fork-ts-checker-webpack-plugin';
+import MiniCssExtractPlugin from 'mini-css-extract-plugin';
+import path from 'path';
+import { Configuration } from 'webpack';
+import { BundleAnalyzerPlugin } from 'webpack-bundle-analyzer';
+import RemoveEmptyScriptsPlugin from 'webpack-remove-empty-scripts';
+
+import {
+  getCodeRules,
+  getFileLoaderRules,
+  getHtmlWebpackPlugin,
+  getImageMinimizer,
+  getStylesheetRule
+} from './common-config';
+
+import ParagonWebpackPlugin from './plugins/paragon-webpack-plugin/ParagonWebpackPlugin';
+
+import getLocalAliases from './utils/getLocalAliases';
+import getPublicPath from './utils/getPublicPath';
+import getResolvedSiteConfigPath from './utils/getResolvedSiteConfigPath';
+import {
+  getParagonCacheGroups,
+  getParagonEntryPoints,
+  getParagonThemeCss,
+} from './utils/paragonUtils';
+
+const paragonThemeCss = getParagonThemeCss(process.cwd());
+const brandThemeCss = getParagonThemeCss(process.cwd(), { isBrandOverride: true });
+const aliases = getLocalAliases();
+const resolvedSiteConfigPath = getResolvedSiteConfigPath('site.config.build.tsx');
+
+const config: Configuration = {
+  mode: 'production',
+  devtool: 'source-map',
+  entry: {
+    app: path.resolve(process.cwd(), 'node_modules/@openedx/frontend-base/shell/site'),
+    ...getParagonEntryPoints(paragonThemeCss),
+    ...getParagonEntryPoints(brandThemeCss),
+  },
+  output: {
+    filename: '[name].[chunkhash].js',
+    path: path.resolve(process.cwd(), 'dist'),
+    publicPath: getPublicPath(),
+    clean: true, // Clean the output directory before emit.
+  },
+  resolve: {
+    alias: {
+      ...aliases,
+      'site.config': resolvedSiteConfigPath,
+    },
+    extensions: ['.js', '.jsx', '.ts', '.tsx'],
+  },
+  module: {
+    rules: [
+      ...getCodeRules('production', resolvedSiteConfigPath),
+      getStylesheetRule('production'),
+      ...getFileLoaderRules(),
+    ],
+  },
+  // Extract common modules among all chunks to one common chunk and extract the Webpack runtime to a single runtime chunk.
+  optimization: {
+    runtimeChunk: 'single',
+    splitChunks: {
+      chunks: 'all',
+      cacheGroups: {
+        ...getParagonCacheGroups(paragonThemeCss),
+        ...getParagonCacheGroups(brandThemeCss),
+      },
+    },
+    minimizer: getImageMinimizer(),
+  },
+  // Specify additional processing or side-effects done on the Webpack output bundles as a whole.
+  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(),
+    // Writes the extracted CSS from each entry to a file in the output directory.
+    new ParagonWebpackPlugin(),
+    new MiniCssExtractPlugin({
+      filename: '[name].[chunkhash].css',
+    }),
+    getHtmlWebpackPlugin(),
+    new ForkTsCheckerWebpackPlugin(),
+    new BundleAnalyzerPlugin({
+      analyzerMode: 'static',
+      openAnalyzer: false,
+    }),
+  ],
+};
+
+export default config;

package/tools/webpack/webpack.config.dev.shell.ts

@@ -0,0 +1,122 @@
+import { transform } from '@formatjs/ts-transformer';
+import ReactRefreshWebpackPlugin from '@pmmmwh/react-refresh-webpack-plugin';
+import ForkTsCheckerWebpackPlugin from 'fork-ts-checker-webpack-plugin';
+import MiniCssExtractPlugin from 'mini-css-extract-plugin';
+import path from 'path';
+import ReactRefreshTypeScript from 'react-refresh-typescript';
+import { Configuration } from 'webpack';
+import RemoveEmptyScriptsPlugin from 'webpack-remove-empty-scripts';
+
+import {
+  getDevServer,
+  getFileLoaderRules,
+  getImageMinimizer,
+  getStylesheetRule
+} from './common-config';
+
+import ParagonWebpackPlugin from './plugins/paragon-webpack-plugin/ParagonWebpackPlugin';
+
+import HtmlWebpackPlugin from 'html-webpack-plugin';
+import getLocalAliases from './utils/getLocalAliases';
+import getPublicPath from './utils/getPublicPath';
+import getResolvedSiteConfigPath from './utils/getResolvedSiteConfigPath';
+import {
+  getParagonCacheGroups,
+  getParagonEntryPoints,
+  getParagonThemeCss,
+} from './utils/paragonUtils';
+
+const paragonThemeCss = getParagonThemeCss(process.cwd());
+const brandThemeCss = getParagonThemeCss(process.cwd(), { isBrandOverride: true });
+const aliases = getLocalAliases();
+const resolvedSiteConfigPath = getResolvedSiteConfigPath('shell/site.config.dev.tsx');
+
+const config: Configuration = {
+  entry: {
+    app: path.resolve(process.cwd(), 'shell/site'),
+    ...getParagonEntryPoints(paragonThemeCss),
+    ...getParagonEntryPoints(brandThemeCss),
+  },
+  output: {
+    path: path.resolve(process.cwd(), './dist'),
+    publicPath: getPublicPath(),
+  },
+  resolve: {
+    alias: {
+      ...aliases,
+      'site.config': resolvedSiteConfigPath,
+    },
+    extensions: ['.js', '.jsx', '.ts', '.tsx'],
+  },
+  mode: 'development',
+  devtool: 'eval-source-map',
+  module: {
+    rules: [
+      {
+        test: /\.(js|jsx|ts|tsx)$/,
+        include: [
+          /shell/,
+          /runtime/,
+          path.resolve(process.cwd(), 'types'),
+          resolvedSiteConfigPath,
+        ],
+        use: {
+          loader: require.resolve('ts-loader'),
+          options: {
+            transpileOnly: true,
+            compilerOptions: {
+              noEmit: false,
+            },
+            getCustomTransformers() {
+              return {
+                before: [
+                  transform({
+                    overrideIdFn: '[sha512:contenthash:base64:6]',
+                  }),
+                  ReactRefreshTypeScript()
+                ],
+              };
+            },
+          },
+        },
+      },
+      getStylesheetRule('dev'),
+      ...getFileLoaderRules(),
+    ],
+  },
+  optimization: {
+    splitChunks: {
+      chunks: 'all',
+      cacheGroups: {
+        ...getParagonCacheGroups(paragonThemeCss),
+        ...getParagonCacheGroups(brandThemeCss),
+      },
+    },
+    minimizer: getImageMinimizer(),
+  },
+  // Specify additional processing or side-effects done on the Webpack output bundles as a whole.
+  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(),
+    // Writes the extracted CSS from each entry to a file in the output directory.
+    new MiniCssExtractPlugin({
+      filename: '[name].css',
+    }),
+    new HtmlWebpackPlugin({
+      inject: true, // Appends script tags linking to the webpack bundles at the end of the body
+      template: path.resolve(process.cwd(), 'shell/public/index.html'),
+      chunks: ['app'],
+    }),
+    new ReactRefreshWebpackPlugin(),
+    new ForkTsCheckerWebpackPlugin(),
+  ],
+  // This configures webpack-dev-server which serves bundles from memory and provides live
+  // reloading.
+
+  devServer: getDevServer(),
+};
+
+export default config;

package/tools/webpack/webpack.config.dev.ts

@@ -0,0 +1,90 @@
+import ReactRefreshWebpackPlugin from '@pmmmwh/react-refresh-webpack-plugin';
+import ForkTsCheckerWebpackPlugin from 'fork-ts-checker-webpack-plugin';
+import MiniCssExtractPlugin from 'mini-css-extract-plugin';
+import path from 'path';
+import { Configuration } from 'webpack';
+import RemoveEmptyScriptsPlugin from 'webpack-remove-empty-scripts';
+
+import {
+  getCodeRules,
+  getDevServer,
+  getFileLoaderRules,
+  getHtmlWebpackPlugin,
+  getImageMinimizer,
+  getStylesheetRule
+} from './common-config';
+
+import ParagonWebpackPlugin from './plugins/paragon-webpack-plugin/ParagonWebpackPlugin';
+
+import getLocalAliases from './utils/getLocalAliases';
+import getPublicPath from './utils/getPublicPath';
+import getResolvedSiteConfigPath from './utils/getResolvedSiteConfigPath';
+import {
+  getParagonCacheGroups,
+  getParagonEntryPoints,
+  getParagonThemeCss,
+} from './utils/paragonUtils';
+
+const paragonThemeCss = getParagonThemeCss(process.cwd());
+const brandThemeCss = getParagonThemeCss(process.cwd(), { isBrandOverride: true });
+const aliases = getLocalAliases();
+const resolvedSiteConfigPath = getResolvedSiteConfigPath('site.config.dev.tsx');
+
+const config: Configuration = {
+  entry: {
+    app: path.resolve(process.cwd(), 'node_modules/@openedx/frontend-base/shell/site'),
+    ...getParagonEntryPoints(paragonThemeCss),
+    ...getParagonEntryPoints(brandThemeCss),
+  },
+  output: {
+    path: path.resolve(process.cwd(), './dist'),
+    publicPath: getPublicPath(),
+  },
+  resolve: {
+    alias: {
+      ...aliases,
+      'site.config': resolvedSiteConfigPath,
+    },
+    extensions: ['.js', '.jsx', '.ts', '.tsx'],
+  },
+  mode: 'development',
+  devtool: 'eval-source-map',
+  module: {
+    rules: [
+      ...getCodeRules('dev', resolvedSiteConfigPath),
+      getStylesheetRule('dev'),
+      ...getFileLoaderRules(),
+    ],
+  },
+  optimization: {
+    splitChunks: {
+      chunks: 'all',
+      cacheGroups: {
+        ...getParagonCacheGroups(paragonThemeCss),
+        ...getParagonCacheGroups(brandThemeCss),
+      },
+    },
+    minimizer: getImageMinimizer(),
+  },
+  // Specify additional processing or side-effects done on the Webpack output bundles as a whole.
+  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(),
+    // Writes the extracted CSS from each entry to a file in the output directory.
+    new MiniCssExtractPlugin({
+      filename: '[name].css',
+    }),
+    getHtmlWebpackPlugin(),
+    new ReactRefreshWebpackPlugin(),
+    new ForkTsCheckerWebpackPlugin(),
+  ],
+  // This configures webpack-dev-server which serves bundles from memory and provides live
+  // reloading.
+
+  devServer: getDevServer(),
+};
+
+export default config;

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "./tools/typescript/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+  },
+  "include": [
+    "runtime/**/*",
+    "shell/**/*",
+    "index.ts",
+    "jest.config.js",
+    "babel.config.js",
+    "eslint.config.js",
+    "frontend-base.d.ts",
+  ],
+  "exclude": [
+    "test-site/**/*",
+    "dist/**/*",
+    "coverage/**/*",
+    "tools/**/*",
+    "config/**/*",
+  ],
+}

package/types.ts

@@ -0,0 +1,99 @@
+import { FC, ReactElement, ReactNode } from 'react';
+import { MessageDescriptor } from 'react-intl';
+import { RouteObject } from 'react-router';
+import { SlotOperation } from './runtime/slots/types';
+
+// Apps
+
+export interface ExternalRoute {
+  role: string,
+  url: string,
+}
+
+export type RoleRouteObject = RouteObject & {
+  handle?: {
+    /**
+     * A route role is used to identify a route that fulfills a particular role in the site, such as "login", "learnerHome", or "profile".
+     */
+    role?: string,
+  },
+};
+
+export type AppConfig = Record<string, unknown>;
+
+export type AppProvider = FC<{ children?: ReactNode }>;
+
+export interface App {
+  appId: string,
+  messages?: LocalizedMessages,
+  routes?: RoleRouteObject[],
+  providers?: AppProvider[],
+  slots?: SlotOperation[],
+  config?: AppConfig,
+}
+
+// Site Config
+
+export interface RequiredSiteConfig {
+  siteId: string,
+  siteName: string,
+  baseUrl: string,
+
+  // Backends
+  lmsBaseUrl: string,
+
+  // Frontends
+  loginUrl: string,
+  logoutUrl: string,
+}
+
+export type LocalizedMessages = Record<string, Record<string, string>>;
+
+export interface OptionalSiteConfig {
+  // Site environment
+  environment: EnvironmentTypes,
+
+  // Apps, routes, and URLs
+  apps: App[],
+  basename: string,
+  externalRoutes: ExternalRoute[],
+  externalLinkUrlOverrides: string[],
+  mfeConfigApiUrl: string | null,
+
+  // Cookies
+  accessTokenCookieName: string,
+  languagePreferenceCookieName: string,
+  userInfoCookieName: string,
+
+  // Paths
+  csrfTokenApiPath: string,
+  refreshAccessTokenApiPath: string,
+
+  // Logging
+  ignoredErrorRegex: RegExp | null,
+
+  // Analytics
+  segmentKey: string | null,
+}
+
+export type SiteConfig = RequiredSiteConfig & Partial<OptionalSiteConfig>;
+
+export interface User {
+  administrator: boolean,
+  email: string,
+  name: string,
+  roles: string[],
+  userId: number,
+  username: string,
+  avatar: string,
+}
+
+export enum EnvironmentTypes {
+  PRODUCTION = 'production',
+  DEVELOPMENT = 'development',
+  TEST = 'test',
+}
+
+// Menu Items
+
+export type MenuItemName = string | MessageDescriptor | ReactElement;