@openedx/frontend-base 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,112 @@
+# Open edX frontend framework
+
+| :rotating_light: Alpha                                                                |
+|:------------------------------------------------------------------------------------------|
+| frontend-base is under **active development** and may change significantly without warning. |
+
+This library is a **future** replacement for many of the foundational libraries in the Open edX frontend.
+
+Development of this library is part of a project to create a reference implementation for [OEP-65: Frontend Composability](https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0065-arch-frontend-composability.html).
+
+It will replace:
+
+- https://github.com/openedx/frontend-build
+- https://github.com/openedx/frontend-platform
+- https://github.com/openedx/frontend-plugin-framework
+- https://github.com/openedx/frontend-component-header
+- https://github.com/openedx/frontend-component-footer
+
+The new frontend framework will completely take over responsibility for the functionality of those libraries, and will also include a "shell" application.
+
+It will enable Open edX frontends to be loaded as "direct plugins" as part of a single, unified application.   It will also support creation of "project" repositories as a central place to check in an Open edX instance's frontend customizations and extensions.
+
+## Further reading
+
+- [OEP-65: Frontend composability](https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0065-arch-frontend-composability.html)
+- [ADR 0001: Create a unified platform library](https://github.com/openedx/open-edx-proposals/pull/598)
+- [Discourse discussion on frontend projects](https://discuss.openedx.org/t/oep-65-adjacent-a-frontend-architecture-vision/13223)
+
+## Communication
+
+You can follow ongoing progress on the project's [Github project board](https://github.com/orgs/openedx/projects/65/views/1).
+
+Feel free to reach out in [#wg-frontend on Slack](https://openedx.slack.com/archives/C04BM6YC7A6) with any questions.
+
+## Development
+
+This library is under development and for now is released manually to npm.
+
+### Developing with Tutor
+
+In order to use develop frontend-base with Tutor, you need to create a Tutor plugin which patches some of the LMS's development settings.
+
+```
+from tutormfe.hooks import MFE_APPS, MFE_ATTRS_TYPE
+
+from tutor import hooks
+
+hooks.Filters.ENV_PATCHES.add_item(
+  (
+    "openedx-lms-development-settings",
+    """
+CORS_ORIGIN_WHITELIST.append("http://{{ MFE_HOST }}:8080")
+LOGIN_REDIRECT_WHITELIST.append("http://{{ MFE_HOST }}:8080")
+CSRF_TRUSTED_ORIGINS.append("http://{{ MFE_HOST }}:8080")
+"""
+    )
+)
+```
+
+Once you enable this plugin, you can start the development site with:
+
+```
+nvm use
+npm ci
+npm run dev
+```
+
+The development site will be available at `http://apps.local.openedx.io:8080`.
+
+## Migrating an MFE to `frontend-base`
+
+See the [Frontend App Migration How To](./docs/how_tos/migrate-frontend-app.md).
+
+# Notable changes
+
+This is a list of notable changes from the previous paradigm:
+
+- Cease using `AUTHN_MINIMAL_HEADER`, replace it with an actual minimal header.
+- No more using `process.env` in runtime code.
+- Removed dotenv.  Use `site.config.*.tsx`.
+- Removed Purge CSS.  We do not believe that Purge CSS works properly with Paragon in general.
+- Removed `ensureConfig` function.  This sort of type safety should happen with TypeScript types in the site config file.
+- Removed `ensureDefinedConfig` function.  Similar to ensureConfig, this sort of type safety should be handled by TypeScript.
+- A number of site config variables now have sensible defaults:
+  - accessTokenCookieName: 'edx-jwt-cookie-header-payload',
+  - csrfTokenApiPath: '/csrf/api/v1/token',
+  - languagePreferenceCookieName: 'openedx-language-preference',
+  - userInfoCookieName: 'edx-user-info',
+  - environment: 'production',
+- the `basename` and export has been replaced by: `getBasename`.  This is because it may not be possible to determine the values of the original constants at code initialization time, since our config may arrive asynchronously.  This ensures that anyone trying to get these values gets a current value.
+- the `history` export no longer exists.  Consumers should be using react-router 6's `useNavigate()` API instead.
+- When using MockAuthService, set the authenticated user by calling setAuthenticatedUser after instantiating the service.  It's not okay for us to add arbitrary config values to the site config.
+- `REFRESH_ACCESS_TOKEN_ENDPOINT` has been replaced with `refreshAccessTokenApiPath`.  It is now a path that defaults to '/login_refresh'.  The Auth service assumes it is an endpoint on the LMS, and joins the path with `lmsBaseUrl`.  This change creates more parity with other paths such as `csrfTokenApiPath`.
+
+The following config variables have been removed, in favor of defining roles for specific modules, `externalRoutes`, or app-specific custom config as necessary:
+
+- ACCOUNT_PROFILE_URL
+- ACCOUNT_SETTINGS_URL
+- LEARNING_BASE_URL
+- ORDER_HISTORY_URL
+- MARKETING_SITE_BASE_URL
+- LEARNER_DASHBOARD_URL
+- STUDIO_BASE_URL
+- ACCESSIBILITY_URL
+- PRIVACY_POLICY_URL
+- TERMS_OF_SERVICE_URL
+- SUPPORT_URL
+- SUPPORT_EMAIL
+- ECOMMERCE_BASE_URL
+- DISCOVERY_API_BASE_URL
+- CREDENTIALS_BASE_URL
+- PUBLISHER_BASE_URL

package/config/babel/babel.config.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * This Babel configuration file is for Jest.  The Webpack build does not use Babel.
+ */
+module.exports = {
+    presets: [
+        [
+            require.resolve('@babel/preset-env'), {
+                targets: { node: 'current' },
+            },
+        ],
+        [
+            require.resolve('@babel/preset-react'), {
+                runtime: 'automatic',
+            },
+        ],
+        require.resolve('@babel/preset-typescript'),
+    ],
+    env: {
+        i18n: {
+            plugins: [
+                [
+                    'formatjs',
+                ],
+            ],
+        },
+    },
+};

package/config/config-helpers/createConfig.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = createConfig;
+const webpack_merge_1 = require("webpack-merge");
+const getBaseConfig_1 = __importDefault(require("./getBaseConfig"));
+function createConfig(configType, configFragment = {}) {
+    const baseConfig = (0, getBaseConfig_1.default)(configType);
+    return (0, webpack_merge_1.merge)(baseConfig, configFragment);
+}
+;

package/config/config-helpers/createLintConfig.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = createLintConfig;
+const typescript_eslint_1 = __importDefault(require("typescript-eslint"));
+const types_1 = require("../types");
+const getBaseConfig_1 = __importDefault(require("./getBaseConfig"));
+function createLintConfig(...configs) {
+    const baseConfig = (0, getBaseConfig_1.default)(types_1.ConfigTypes.LINT);
+    return typescript_eslint_1.default.config({
+        extends: baseConfig,
+    }, ...configs);
+}
+;

package/config/config-helpers/getBaseConfig.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getBaseConfig;
+const defaultConfigPaths_1 = require("../defaultConfigPaths");
+function getBaseConfig(configType) {
+    const configPaths = defaultConfigPaths_1.defaultConfigPaths[configType];
+    if (configPaths === undefined) {
+        throw new Error(`openedx: ${configType} is not a supported config type.`);
+    }
+    return require(require.resolve(configPaths[configPaths.length - 1]));
+}
+;

package/config/defaultConfigPaths.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfigPaths = void 0;
+const path_1 = __importDefault(require("path"));
+const types_1 = require("./types");
+// These config paths are tested in the order they're defined, so the last ones are the last fallback.
+exports.defaultConfigPaths = {
+    [types_1.ConfigTypes.BABEL]: [
+        path_1.default.resolve(process.cwd(), 'babel.config.js'),
+        path_1.default.resolve(__dirname, './babel/babel.config.js'),
+    ],
+    [types_1.ConfigTypes.WEBPACK_BUILD]: [
+        path_1.default.resolve(process.cwd(), 'webpack.config.build.js'),
+        path_1.default.resolve(__dirname, './webpack/webpack.config.build.js'),
+    ],
+    [types_1.ConfigTypes.WEBPACK_DEV]: [
+        path_1.default.resolve(process.cwd(), 'webpack.config.dev.js'),
+        path_1.default.resolve(__dirname, './webpack/webpack.config.dev.js'),
+    ],
+    [types_1.ConfigTypes.WEBPACK_DEV_SHELL]: [
+        path_1.default.resolve(process.cwd(), 'webpack.config.dev.shell.js'),
+        path_1.default.resolve(__dirname, './webpack/webpack.config.dev.shell.js'),
+    ],
+    [types_1.ConfigTypes.LINT]: [
+        path_1.default.resolve(process.cwd(), 'eslint.config.js'),
+        path_1.default.resolve(__dirname, './eslint/base.eslint.config.js'),
+    ],
+    [types_1.ConfigTypes.TEST]: [
+        path_1.default.resolve(process.cwd(), 'jest.config.js'),
+        path_1.default.resolve(__dirname, './jest/jest.config.js'),
+    ],
+};

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

@@ -0,0 +1,113 @@
+"use strict";
+// @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/config/index.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBaseConfig = exports.createLintConfig = exports.createConfig = void 0;
+var createConfig_1 = require("./config-helpers/createConfig");
+Object.defineProperty(exports, "createConfig", { enumerable: true, get: function () { return __importDefault(createConfig_1).default; } });
+var createLintConfig_1 = require("./config-helpers/createLintConfig");
+Object.defineProperty(exports, "createLintConfig", { enumerable: true, get: function () { return __importDefault(createLintConfig_1).default; } });
+var getBaseConfig_1 = require("./config-helpers/getBaseConfig");
+Object.defineProperty(exports, "getBaseConfig", { enumerable: true, get: function () { return __importDefault(getBaseConfig_1).default; } });

package/config/jest/jest.config.js

@@ -0,0 +1,30 @@
+"use strict";
+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/config/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/config/types.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandTypes = exports.ConfigTypes = void 0;
+var ConfigTypes;
+(function (ConfigTypes) {
+    ConfigTypes["BABEL"] = "babel";
+    ConfigTypes["WEBPACK_BUILD"] = "webpack-build";
+    ConfigTypes["WEBPACK_DEV"] = "webpack-dev";
+    ConfigTypes["WEBPACK_DEV_SHELL"] = "webpack-dev-shell";
+    ConfigTypes["LINT"] = "lint";
+    ConfigTypes["TEST"] = "test";
+})(ConfigTypes || (exports.ConfigTypes = ConfigTypes = {}));
+var CommandTypes;
+(function (CommandTypes) {
+    CommandTypes["RELEASE"] = "release";
+    CommandTypes["PACK"] = "pack";
+    CommandTypes["LINT"] = "lint";
+    CommandTypes["TEST"] = "test";
+    CommandTypes["BUILD"] = "build";
+    CommandTypes["DEV_SHELL"] = "dev:shell";
+    CommandTypes["DEV"] = "dev";
+    CommandTypes["FORMAT_JS"] = "formatjs";
+    CommandTypes["SERVE"] = "serve";
+    CommandTypes["HELP"] = "help";
+})(CommandTypes || (exports.CommandTypes = CommandTypes = {}));

package/config/webpack/common-config/all/getCodeRules.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getCodeRules;
+const ts_transformer_1 = require("@formatjs/ts-transformer");
+const react_refresh_typescript_1 = __importDefault(require("react-refresh-typescript"));
+function getCodeRules(mode, resolvedSiteConfigPath) {
+    const rules = [
+        {
+            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 = [
+                            (0, ts_transformer_1.transform)({
+                                overrideIdFn: '[sha512:contenthash:base64:6]',
+                            }),
+                        ];
+                        if (mode === 'dev') {
+                            before.push((0, react_refresh_typescript_1.default)());
+                        }
+                        return {
+                            before,
+                        };
+                    },
+                },
+            },
+        },
+    ];
+    if (mode === 'production') {
+        rules.push({
+            test: /\.(js|jsx|ts|tsx)$/,
+            use: [
+                require.resolve('source-map-loader'),
+            ],
+            enforce: 'pre',
+        });
+    }
+    return rules;
+}

package/config/webpack/common-config/all/getFileLoaderRules.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getFileLoaderRules;
+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/config/webpack/common-config/all/getIgnoreWarnings.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getIgnoreWarnings;
+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) => !!(
+        // @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/config/webpack/common-config/all/getImageMinimizer.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getImageMinimizer;
+const image_minimizer_webpack_plugin_1 = __importDefault(require("image-minimizer-webpack-plugin"));
+function getImageMinimizer() {
+    return [
+        '...',
+        new image_minimizer_webpack_plugin_1.default({
+            minimizer: {
+                implementation: image_minimizer_webpack_plugin_1.default.sharpMinify,
+                options: {
+                    encodeOptions: {
+                        ...['png', 'jpeg', 'jpg'].reduce((accumulator, value) => ({ ...accumulator, [value]: { progressive: true, quality: 65 } }), {}),
+                        gif: {
+                            effort: 5,
+                        },
+                    },
+                },
+            },
+        }),
+    ];
+}