@openedx/frontend-base 1.0.0-alpha.0

package/tools/dist/webpack/webpack.config.dev.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_refresh_webpack_plugin_1 = __importDefault(require("@pmmmwh/react-refresh-webpack-plugin"));
+const fork_ts_checker_webpack_plugin_1 = __importDefault(require("fork-ts-checker-webpack-plugin"));
+const mini_css_extract_plugin_1 = __importDefault(require("mini-css-extract-plugin"));
+const path_1 = __importDefault(require("path"));
+const webpack_remove_empty_scripts_1 = __importDefault(require("webpack-remove-empty-scripts"));
+const common_config_1 = require("./common-config");
+const ParagonWebpackPlugin_1 = __importDefault(require("./plugins/paragon-webpack-plugin/ParagonWebpackPlugin"));
+const getLocalAliases_1 = __importDefault(require("./utils/getLocalAliases"));
+const getPublicPath_1 = __importDefault(require("./utils/getPublicPath"));
+const getResolvedSiteConfigPath_1 = __importDefault(require("./utils/getResolvedSiteConfigPath"));
+const paragonUtils_1 = require("./utils/paragonUtils");
+const paragonThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd());
+const brandThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd(), { isBrandOverride: true });
+const aliases = (0, getLocalAliases_1.default)();
+const resolvedSiteConfigPath = (0, getResolvedSiteConfigPath_1.default)('site.config.dev.tsx');
+const config = {
+    entry: {
+        app: path_1.default.resolve(process.cwd(), 'node_modules/@openedx/frontend-base/shell/site'),
+        ...(0, paragonUtils_1.getParagonEntryPoints)(paragonThemeCss),
+        ...(0, paragonUtils_1.getParagonEntryPoints)(brandThemeCss),
+    },
+    output: {
+        path: path_1.default.resolve(process.cwd(), './dist'),
+        publicPath: (0, getPublicPath_1.default)(),
+    },
+    resolve: {
+        alias: {
+            ...aliases,
+            'site.config': resolvedSiteConfigPath,
+        },
+        extensions: ['.js', '.jsx', '.ts', '.tsx'],
+    },
+    mode: 'development',
+    devtool: 'eval-source-map',
+    module: {
+        rules: [
+            ...(0, common_config_1.getCodeRules)('dev', resolvedSiteConfigPath),
+            (0, common_config_1.getStylesheetRule)('dev'),
+            ...(0, common_config_1.getFileLoaderRules)(),
+        ],
+    },
+    optimization: {
+        splitChunks: {
+            chunks: 'all',
+            cacheGroups: {
+                ...(0, paragonUtils_1.getParagonCacheGroups)(paragonThemeCss),
+                ...(0, paragonUtils_1.getParagonCacheGroups)(brandThemeCss),
+            },
+        },
+        minimizer: (0, common_config_1.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 webpack_remove_empty_scripts_1.default(),
+        new ParagonWebpackPlugin_1.default(),
+        // Writes the extracted CSS from each entry to a file in the output directory.
+        new mini_css_extract_plugin_1.default({
+            filename: '[name].css',
+        }),
+        (0, common_config_1.getHtmlWebpackPlugin)(),
+        new react_refresh_webpack_plugin_1.default(),
+        new fork_ts_checker_webpack_plugin_1.default(),
+    ],
+    // This configures webpack-dev-server which serves bundles from memory and provides live
+    // reloading.
+    devServer: (0, common_config_1.getDevServer)(),
+};
+exports.default = config;

package/tools/dist/webpack/webpack.config.dev.shell.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ts_transformer_1 = require("@formatjs/ts-transformer");
+const react_refresh_webpack_plugin_1 = __importDefault(require("@pmmmwh/react-refresh-webpack-plugin"));
+const fork_ts_checker_webpack_plugin_1 = __importDefault(require("fork-ts-checker-webpack-plugin"));
+const mini_css_extract_plugin_1 = __importDefault(require("mini-css-extract-plugin"));
+const path_1 = __importDefault(require("path"));
+const react_refresh_typescript_1 = __importDefault(require("react-refresh-typescript"));
+const webpack_remove_empty_scripts_1 = __importDefault(require("webpack-remove-empty-scripts"));
+const common_config_1 = require("./common-config");
+const ParagonWebpackPlugin_1 = __importDefault(require("./plugins/paragon-webpack-plugin/ParagonWebpackPlugin"));
+const html_webpack_plugin_1 = __importDefault(require("html-webpack-plugin"));
+const getLocalAliases_1 = __importDefault(require("./utils/getLocalAliases"));
+const getPublicPath_1 = __importDefault(require("./utils/getPublicPath"));
+const getResolvedSiteConfigPath_1 = __importDefault(require("./utils/getResolvedSiteConfigPath"));
+const paragonUtils_1 = require("./utils/paragonUtils");
+const paragonThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd());
+const brandThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd(), { isBrandOverride: true });
+const aliases = (0, getLocalAliases_1.default)();
+const resolvedSiteConfigPath = (0, getResolvedSiteConfigPath_1.default)('shell/site.config.dev.tsx');
+const config = {
+    entry: {
+        app: path_1.default.resolve(process.cwd(), 'shell/site'),
+        ...(0, paragonUtils_1.getParagonEntryPoints)(paragonThemeCss),
+        ...(0, paragonUtils_1.getParagonEntryPoints)(brandThemeCss),
+    },
+    output: {
+        path: path_1.default.resolve(process.cwd(), './dist'),
+        publicPath: (0, getPublicPath_1.default)(),
+    },
+    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_1.default.resolve(process.cwd(), 'types'),
+                    resolvedSiteConfigPath,
+                ],
+                use: {
+                    loader: require.resolve('ts-loader'),
+                    options: {
+                        transpileOnly: true,
+                        compilerOptions: {
+                            noEmit: false,
+                        },
+                        getCustomTransformers() {
+                            return {
+                                before: [
+                                    (0, ts_transformer_1.transform)({
+                                        overrideIdFn: '[sha512:contenthash:base64:6]',
+                                    }),
+                                    (0, react_refresh_typescript_1.default)()
+                                ],
+                            };
+                        },
+                    },
+                },
+            },
+            (0, common_config_1.getStylesheetRule)('dev'),
+            ...(0, common_config_1.getFileLoaderRules)(),
+        ],
+    },
+    optimization: {
+        splitChunks: {
+            chunks: 'all',
+            cacheGroups: {
+                ...(0, paragonUtils_1.getParagonCacheGroups)(paragonThemeCss),
+                ...(0, paragonUtils_1.getParagonCacheGroups)(brandThemeCss),
+            },
+        },
+        minimizer: (0, common_config_1.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 webpack_remove_empty_scripts_1.default(),
+        new ParagonWebpackPlugin_1.default(),
+        // Writes the extracted CSS from each entry to a file in the output directory.
+        new mini_css_extract_plugin_1.default({
+            filename: '[name].css',
+        }),
+        new html_webpack_plugin_1.default({
+            inject: true, // Appends script tags linking to the webpack bundles at the end of the body
+            template: path_1.default.resolve(process.cwd(), 'shell/public/index.html'),
+            chunks: ['app'],
+        }),
+        new react_refresh_webpack_plugin_1.default(),
+        new fork_ts_checker_webpack_plugin_1.default(),
+    ],
+    // This configures webpack-dev-server which serves bundles from memory and provides live
+    // reloading.
+    devServer: (0, common_config_1.getDevServer)(),
+};
+exports.default = config;

package/tools/eslint/base.eslint.config.js

@@ -0,0 +1,124 @@
+// @ts-check
+
+const { fixupPluginRules } = require('@eslint/compat');
+const eslint = require('@eslint/js');
+const formatjs = require('eslint-plugin-formatjs');
+const jest = require('eslint-plugin-jest');
+const jsxA11y = require('eslint-plugin-jsx-a11y');
+const react = require('eslint-plugin-react');
+const reactHooks = require('eslint-plugin-react-hooks');
+const globals = require('globals');
+const tseslint = require('typescript-eslint');
+const stylistic = require('@stylistic/eslint-plugin');
+
+module.exports = tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.stylisticTypeChecked,
+  ...tseslint.configs.recommended,
+  stylistic.configs['recommended-flat'],
+  {
+    ignores: [
+      'coverage/*',
+      'dist/*',
+      'node_modules/*',
+      '**/__mocks__/*',
+      '**/__snapshots__/*',
+    ],
+  },
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+      }
+    }
+  },
+  {
+    languageOptions: {
+      ...(react.configs.flat !== undefined ? react.configs.flat.recommended.languageOptions : {}),
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.jest,
+        PARAGON_THEME: 'readonly',
+        newrelic: 'readonly',
+      },
+    },
+    plugins: {
+      jest,
+      // Type assertion is workaround for incorrect TypeScript
+      // types in eslint-plugin-react
+      //
+      // TODO: Remove when types are fixed in eslint-plugin-react
+      // - https://github.com/jsx-eslint/eslint-plugin-react/issues/3838
+      react: /** @type {import('eslint').ESLint.Plugin} */ (react),
+      'react-hooks': fixupPluginRules(reactHooks),
+      formatjs,
+      'jsx-a11y': jsxA11y,
+    },
+    settings: {
+      react: {
+        version: 'detect',
+      }
+    }
+  },
+  {
+    rules: {
+      // For some reasons the 'flat' key in react.configs is optional, so Typescript complains if
+      // we don't guard using it.  But... it exists in the export, so something's odd with their types.
+      ...(react.configs.flat !== undefined ? react.configs.flat.recommended.rules : {}),
+      ...(react.configs.flat !== undefined ? react.configs.flat['jsx-runtime'].rules : {}),
+      ...reactHooks.configs.recommended.rules,
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/non-nullable-type-assertion-style': 'off',
+      'react/no-array-index-key': 'error',
+      'formatjs/enforce-description': ['error', 'literal'],
+      'jsx-a11y/label-has-associated-control': ['error', {
+        labelComponents: [],
+        labelAttributes: [],
+        controlComponents: [],
+        assert: 'htmlFor',
+        depth: 25,
+      }],
+      // https://github.com/evcohen/eslint-plugin-jsx-a11y/issues/340#issuecomment-338424908
+      'jsx-a11y/anchor-is-valid': ['error', {
+        components: ['Link'],
+        specialLink: ['to'],
+      }],
+      '@typescript-eslint/no-unused-vars': ['error', {
+        caughtErrors: 'none',
+      }],
+      '@typescript-eslint/no-empty-function': 'off',
+      '@stylistic/semi': ['error', 'always', { omitLastInOneLineBlock: true, omitLastInOneLineClassBody: true }],
+      '@stylistic/quotes': ['error', 'single', {
+        avoidEscape: true,
+        allowTemplateLiterals: true,
+      }],
+      '@stylistic/comma-dangle': 'off',
+      '@stylistic/quote-props': ['error', 'as-needed'],
+      '@stylistic/arrow-parens': 'off',
+      '@stylistic/jsx-one-expression-per-line': 'off',
+      '@stylistic/multiline-ternary': 'off',
+      '@stylistic/brace-style': ['error', '1tbs'],
+      '@stylistic/member-delimiter-style': ['error', {
+        multiline: {
+          delimiter: 'comma',
+          requireLast: true,
+        },
+        singleline: {
+          delimiter: 'comma',
+          requireLast: false,
+        }
+      }],
+    },
+  },
+  {
+    files: [
+      'babel.config.js',
+      'jest.config.js',
+      'eslint.config.js'
+    ],
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off'
+    }
+  }
+);

package/tools/eslint/modules.d.ts

@@ -0,0 +1,5 @@
+// This file needs to exist to declare modules for dependencies that don't publish their types.
+
+declare module 'eslint-plugin-jest';
+declare module 'eslint-plugin-jsx-a11y';
+declare module 'eslint-plugin-react-hooks';

package/tools/eslint.config.js

@@ -0,0 +1,15 @@
+// @ts-check
+
+const tseslint = require('typescript-eslint');
+const eslintConfig = require('./eslint/base.eslint.config.js');
+
+module.exports = tseslint.config(
+  {
+    extends: eslintConfig,
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off'
+    }
+  },
+);

package/tools/index.ts

@@ -0,0 +1,3 @@
+export { default as createConfig } from './config-helpers/createConfig';
+export { default as createLintConfig } from './config-helpers/createLintConfig';
+export { default as getBaseConfig } from './config-helpers/getBaseConfig';

package/tools/jest/jest.config.js

@@ -0,0 +1,30 @@
+const path = require('path');
+
+module.exports = {
+  testEnvironment: 'jsdom',
+  testEnvironmentOptions: {
+    url: 'http://localhost/',
+  },
+  rootDir: process.cwd(),
+  moduleNameMapper: {
+    '\\.(css|scss)$': require.resolve('identity-obj-proxy'),
+    'site.config': path.resolve(process.cwd(), './site.config.test.tsx'),
+  },
+  collectCoverageFrom: [
+    'src/**/*.{js,jsx,ts,tsx}',
+  ],
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+  ],
+  transformIgnorePatterns: [
+    '/node_modules/(?!(@openedx|@edx)/)',
+  ],
+  modulePathIgnorePatterns: [
+    '/dist/',
+  ],
+  testPathIgnorePatterns: [
+    '/site.config.test.tsx',
+    '/node_modules/',
+    '/dist/',
+  ],
+};

package/tools/jest.config.js

@@ -0,0 +1,19 @@
+module.exports = {
+  testEnvironment: 'node',
+  testEnvironmentOptions: {
+    url: 'http://localhost/',
+  },
+  collectCoverageFrom: [
+    'cli/**/*.{js,jsx,ts,tsx}',
+  ],
+  transformIgnorePatterns: [
+    '/node_modules/(?!(@openedx|@edx)/)',
+  ],
+  modulePathIgnorePatterns: [
+    '/dist/',
+  ],
+  testPathIgnorePatterns: [
+    '/node_modules/',
+    '/dist/',
+  ],
+};

package/tools/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "@tsconfig/node20/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+    "noEmit": false,
+    "allowJs": true,
+    "resolveJsonModule": true,
+  },
+  "include": [
+    "babel/**/*",
+    "cli/**/*",
+    "config-helpers/**/*",
+    "jest/jest.config.js",
+    "typescript/tsconfig.json",
+    "webpack/**/*",
+    "types.ts",
+    "index.ts",
+    "defaultConfigPaths.ts",
+    "eslint/**/*",
+    "eslint.config.js",
+    "jest.config.js",
+  ],
+}

package/tools/types.ts

@@ -0,0 +1,21 @@
+export enum ConfigTypes {
+  BABEL = 'babel',
+  WEBPACK_BUILD = 'webpack-build',
+  WEBPACK_DEV = 'webpack-dev',
+  WEBPACK_DEV_SHELL = 'webpack-dev-shell',
+  LINT = 'lint',
+  TEST = 'test',
+}
+
+export enum CommandTypes {
+  RELEASE = 'release',
+  PACK = 'pack',
+  LINT = 'lint',
+  TEST = 'test',
+  BUILD = 'build',
+  DEV_SHELL = 'dev:shell',
+  DEV = 'dev',
+  FORMAT_JS = 'formatjs',
+  SERVE = 'serve',
+  HELP = 'help',
+}

package/tools/typescript/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react-jsx",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ESNext",
+      "esnext.intl",
+      "es2017.intl",
+      "es2018.intl"
+    ],
+    "isolatedModules": true,
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "noEmit": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": false,
+    "noImplicitThis": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "strictFunctionTypes": false,
+    "target": "ES6"
+  }
+}

package/tools/webpack/common-config/README.md

@@ -0,0 +1,15 @@
+# Using this 'common-config' folder
+
+**Don't try too hard to re-use code.**
+
+If extracting webpack config to this folder makes the config harder to reason, then it's not worth it.
+
+The things that have been extracted so far are either:
+
+1) So similar (or exactly the same) across configs that they're easy to understand.  `getHtmlWebpackPlugin`, `getImageMinimizer`, `ignoreWarnings`, and `getFileLoaderRules` fit in this category.
+2) Need to be kept in sync and tended to drift, despite being a bit different.  The `getStylesheetRule` and `getCodeRules` functions fit in this category.  They are arguably easier to reason all in one place so we can understand the differences between
+them.
+
+What they all share in common is that they're fairly long and make the configs harder to read.  Extracting them has made the configs about a page of text and all the important high-level stuff that makes them different is still present.
+
+More or less.  Use your judgment.

package/tools/webpack/common-config/all/getCodeRules.ts

@@ -0,0 +1,51 @@
+import { transform } from '@formatjs/ts-transformer';
+import ReactRefreshTypeScript from 'react-refresh-typescript';
+
+import { RuleSetRule } from 'webpack';
+
+export default function getCodeRules(mode: 'dev' | 'production', resolvedSiteConfigPath: string) {
+  const rules: RuleSetRule[] = [
+    {
+      test: /\.(js|jsx|ts|tsx)$/,
+      include: [
+        /src/,
+        /node_modules\/@openedx\/frontend-base/,
+        resolvedSiteConfigPath,
+      ],
+      use: {
+        loader: require.resolve('ts-loader'),
+        options: {
+          transpileOnly: true,
+          compilerOptions: {
+            noEmit: false,
+          },
+          getCustomTransformers() {
+            const before = [
+              transform({
+                overrideIdFn: '[sha512:contenthash:base64:6]',
+              }),
+            ];
+            if (mode === 'dev') {
+              before.push(ReactRefreshTypeScript());
+            }
+            return {
+              before,
+            };
+          },
+        },
+      },
+    },
+  ];
+
+  if (mode === 'production') {
+    rules.push({
+      test: /\.(js|jsx|ts|tsx)$/,
+      use: [
+        require.resolve('source-map-loader'),
+      ],
+      enforce: 'pre',
+    });
+  }
+
+  return rules;
+}

package/tools/webpack/common-config/all/getFileLoaderRules.ts

@@ -0,0 +1,23 @@
+export default function getFileLoaderRules() {
+  return [
+    // Webpack, by default, uses the url-loader for images and fonts that are required/included by
+    // files it processes, which just base64 encodes them and inlines them in the javascript
+    // bundles. This makes the javascript bundles ginormous and defeats caching so we will use the
+    // file-loader instead to copy the files directly to the output directory.
+    {
+      test: /\.(woff2?|ttf|svg|eot)(\?v=\d+\.\d+\.\d+)?$/,
+      loader: require.resolve('file-loader'),
+    },
+    {
+      test: /favicon.ico$/,
+      loader: require.resolve('file-loader'),
+      options: {
+        name: '[name].[ext]', // <-- retain original file name
+      },
+    },
+    {
+      test: /\.(jpe?g|png|gif)(\?v=\d+\.\d+\.\d+)?$/,
+      loader: require.resolve('file-loader'),
+    },
+  ];
+}

package/tools/webpack/common-config/all/getIgnoreWarnings.ts

@@ -0,0 +1,13 @@
+import { WebpackError } from 'webpack';
+
+export default function getIgnoreWarnings() {
+  return [
+    // Ignore warnings raised by source-map-loader.
+    // some third party packages may ship miss-configured sourcemaps, that interrupts the build
+    // See: https://github.com/facebook/create-react-app/discussions/11278#discussioncomment-1780169
+    (warning: WebpackError) => !!(
+      // @ts-expect-error 'resource' is something TypeScript can't find for whatever reason.
+      warning.module?.resource.includes('node_modules')
+      && warning.details?.includes('source-map-loader')),
+  ];
+}

package/tools/webpack/common-config/all/getImageMinimizer.ts

@@ -0,0 +1,26 @@
+import ImageMinimizerPlugin, { Compiler } from 'image-minimizer-webpack-plugin';
+import { WebpackPluginInstance } from 'webpack';
+
+// This is pulled from the definition of optimization.minimizer in the webpack Configuration type.
+type ImageMinimizerReturnType = (false | '' | 0 | '...' | ((this: Compiler, compiler: Compiler) => void) | WebpackPluginInstance | null | undefined)[] | undefined;
+
+export default function getImageMinimizer(): ImageMinimizerReturnType {
+  return [
+    '...',
+    new ImageMinimizerPlugin({
+      minimizer: {
+        implementation: ImageMinimizerPlugin.sharpMinify,
+        options: {
+          encodeOptions: {
+            ...['png', 'jpeg', 'jpg'].reduce((accumulator, value) => (
+              { ...accumulator, [value]: { progressive: true, quality: 65 } }
+            ), {}),
+            gif: {
+              effort: 5,
+            },
+          },
+        },
+      },
+    }),
+  ];
+}