@openedx/frontend-build 12.10.0-alpha.1

package/README.md

@@ -0,0 +1,314 @@
+# frontend-build
+
+[![Build
+Status](https://api.travis-ci.com/edx/frontend-build.svg?branch=master)](https://travis-ci.com/edx/frontend-build)
+![npm\_version](https://img.shields.io/npm/v/@openedx/frontend-build.svg)
+[![Codecov](https://img.shields.io/codecov/c/github/edx/frontend-build)](https://codecov.io/gh/edx/frontend-build)
+[![license](https://img.shields.io/npm/l/@openedx/frontend-build.svg)](https://github.com/edx-unsupported/frontend-base/blob/master/LICENSE)
+
+## Purpose
+
+The purpose of this package is to provide a common sense foundation and
+setup for frontend projects including:
+
+-   linting (eslint)
+-   testing (jest)
+-   development server (webpack-dev-server)
+-   build (webpack)
+
+This package can serve as a single dev dependency replacing a large
+number of dev and build dependencies. It aims to provide common sense
+defaults that should be good for most edX projects out of the box, but
+can extended or overridden where needed.
+
+## Cloning and Startup
+
+``` {.}
+1. Clone your new repo:
+
+  ``git clone https://github.com/openedx/frontend-build.git``
+
+2. Use node v18.x.
+
+  The current version of the micro-frontend build scripts support node 18.
+  Using other major versions of node *may* work, but this is unsupported.  For
+  convenience, this repository includes an .nvmrc file to help in setting the
+  correct node version via `nvm <https://github.com/nvm-sh/nvm>`_.
+
+3. Install npm dependencies:
+
+  ``cd frontend-build && npm ci``
+```
+
+## Usage
+
+CLI commands are structured: `fedx-scripts <targetScript> <options>`.
+Options are passed on to the target script, so refer to each target
+script\'s CLI documentation to learn what options are available. Example
+package.json:
+
+    {
+       "scripts": {
+          "build": "fedx-scripts webpack",
+          "i18n_extract": "fedx-scripts formatjs extract",
+          "lint": "fedx-scripts eslint --ext .jsx,.js .",
+          "precommit": "npm run lint",
+          "snapshot": "fedx-scripts jest --updateSnapshot",
+          "start": "fedx-scripts webpack-dev-server --progress",
+          "test": "fedx-scripts jest --coverage --passWithNoTests",
+          "serve": "fedx-scripts serve"
+       },
+       "dependencies": {
+          ...
+       },
+       "devDependencies": {
+          "@openedx/frontend-build": "1.0.0"
+       }
+    }
+
+## Extending or Overriding Config Presets
+
+This package contains a set of configuration presets:
+
+-   webpack-prod (or webpack)
+-   webpack-dev (or webpack-dev-server)
+-   webpack-dev-stage (for running development apps against stage apis)
+-   babel
+-   babel-preserve-modules
+-   jest
+-   eslint
+
+If you need to extend or modify a configuration you can add your own
+configuration files, either by extending frontend-build\'s configuration
+files or supplying your own wholesale.
+
+Method 1: Extend base config (babel.config.js):
+
+    const { createConfig } = require('@openedx/frontend-build');
+    module.exports = createConfig('babel', {
+       /* option overrides or extensions */
+    });
+
+Method 2: Custom manipulations (babel.config.js):
+
+    const { getBaseConfig } = require('@openedx/frontend-build');
+    const config = getBaseConfig('babel');
+
+    /* Custom config manipulations */
+
+    module.exports = config;
+
+Frontend build will look in the following locations for configuration
+files in your project.
+
+-   eslint: `<project_root>/.eslintrc.js`
+-   jest: `<project_root>/jest.config.js`
+-   babel: `<project_root>/babel.config.js`
+-   webpack-prod: `<project_root>/webpack.prod.config.js`
+-   webpack-dev-server: `<project_root>/webpack.dev.config.js`
+
+You may specify custom config file locations via the command line if you
+prefer a different location. Example package.json:
+
+    {
+       "scripts": {
+          "build": "fedx-scripts webpack --config ./config/webpack.config.js",
+          "start:stage": "fedx-scripts webpack-dev-server --config webpack.dev-stage.config.js",
+          ...
+       }
+    }
+
+Note, specifying a custom config location for babel may cause issues
+with other tools in frontend-build. eslint, jest, webpack, and
+webpack-dev-server configuration presets rely upon the babel config and
+resolve the location of the config file according to the default
+locations described above. If you need to move the babel config file to
+a custom location, you may also need to customize references to its
+location in other configuration files. Please reach out to the FedX team
+if you need to do this and are running into problems.
+
+## Local module configuration for Webpack
+
+
+The development webpack configuration allows engineers to create a
+\"module.config.js\" file containing local module overrides. This means
+that if you\'re developing a new feature in a shared library
+(\@edx/frontend-platform, \@openedx/paragon, etc.), you can add the local
+location of that repository to your module.config.js file and the
+webpack build for your application will automatically pick it up and use
+it, rather than its node\_modules version of the file.
+
+**NOTE: This module.config.js file should be added to your**
+[.gitignore]{.title-ref}.
+
+An example module.config.js file looks like the following. You can copy
+this into your application to use local versions of paragon and
+frontend-platform:
+
+    module.exports = {
+      /*
+      Modules you want to use from local source code.  Adding a module here means that when this app
+      runs its build, it'll resolve the source from peer directories of this app.
+
+      moduleName: the name you use to import code from the module.
+      dir: The relative path to the module's source code.
+      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: '@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' },
+        { moduleName: '@edx/frontend-platform', dir: '../src/frontend-platform', dist: 'dist' },
+      ],
+    };
+
+## Steps
+
+1.  Copy the `module.config.js` into your frontend app repository,
+    modifying it as necessary.
+2.  Run `npm install && npm run build` within any shared NPM package you
+    want to use locally.
+3.  Restart your app.
+
+## Notes
+
+-   The \"dir\" and \"dist\" keys give you granular control over the
+    shape of your repository\'s distribution. Paragon, for instance,
+    needs two separate entries to pick up both JS and SCSS imports.
+-   The directory location `../src` (relative to the root of your
+    frontend app repository) is recommended for shared NPM package
+    repositories, since it will work whether or not you are running your
+    frontend via devstack. If you are *not* running your frontend via
+    devstack, then you can place your shared libraries anywhere in your
+    file system, updating the \"dir\" key accordingly. To learn more,
+    see [this devstack ADR on local
+    packages](https://github.com/openedx/devstack/tree/master/docs/decisions/0005-frontend-package-mounts.rst).
+-   This mechanism uses Webpack resolve aliases, as documented here:
+    <https://webpack.js.org/configuration/resolve/#resolvealias>
+
+## Override default .env.development environment variables with .env.private
+
+In some situations, you may want to override development environment
+variables defined in .env.development with private environment variables
+that should never be checked into a repository. For example, a
+.env.development file may contain secrets for a third-party service
+(e.g., Algolia) that you\'d like to use during development but want to
+ensure these secrets are not checked into Git.
+
+You may create a [.env.private]{.title-ref} with any overrides of the
+environment settings configured in [.env.development]{.title-ref}.
+
+**Note: .env.private should be added to your project\'s .gitignore so it
+does not get checked in.**
+
+## Serving a production Webpack build locally
+
+In some scenarios, you may want to run a production Webpack build
+locally. To serve a production build locally:
+
+1.  Create an `env.config.js` file containing the configuration for
+    local development, with the exception of `NODE_ENV='production'`.
+2.  Run `npm run build` to build the production assets. The output
+    assets will rely on the local development configuration specified in
+    the prior step.
+3.  Add an NPM script `serve` to your application\'s `package.json`
+    (i.e., `"serve": "fedx-scripts serve"`).
+4.  Run `npm run serve` to serve your production build assets. It will
+    attempt to run the build on the same port specified in the
+    `env.config.js` file.
+
+## Local module configuration for TypeScript
+
+#. Create file in repository `tsconfig.json`, with a clause `"extends": "@openedx/frontend-build"`
+#. Set "rootDir" to the root of the source code folders
+#. Set "include" to wildcard patterns specifying the subdirectories/files under rootDir where source code can be found
+#. Include any wildcards under rootDir that should be excluded using "exclude"
+
+```Sample json
+{
+  "extends": "@openedx/frontend-build",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules"]
+}
+```
+
+## Development
+
+This project leverages the command line interface for webpack, jest,
+eslint, and babel. Because of this, local development can be tricky. The
+easiest way to do local development on this project is to either run
+scripts inside the project in example or to test with an existing
+project you can do the following:
+
+1.  Delete the node\_modules directories in the host project:
+    `rm -rf node_modules/`
+2.  Move frontend-build inside the host project and delete its node
+    modules folder
+    `mv ../frontend-build ./ && rm -rf frontend-build/node_modules`
+3.  Install the development version of frontend-build
+    `npm i --save-dev @openedx/frontend-build@file:./frontend-build`.
+
+## License
+
+The code in this repository is licensed under the AGPLv3 unless
+otherwise noted.
+
+Please see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are very welcome. Please read [How To
+Contribute](https://openedx.org/r/how-to-contribute) for details.
+
+This project is currently accepting all types of contributions, bug
+fixes, security fixes, maintenance work, or new features. However,
+please make sure to have a discussion about your new feature idea with
+the maintainers prior to beginning development to maximize the chances
+of your change being accepted. You can start a conversation by creating
+a new issue on this repo summarizing your idea.
+
+## Getting Help
+
+If you\'re having trouble, we have discussion forums at
+<https://discuss.openedx.org> where you can connect with others in the
+community.
+
+Our real-time conversations are on Slack. You can request a [Slack
+invitation](https://openedx.org/slack), then join our [community Slack
+workspace](https://openedx.slack.com/). Because this is a frontend
+repository, the best place to discuss it would be in the [\#wg-frontend
+channel](https://openedx.slack.com/archives/C04BM6YC7A6).
+
+For anything non-trivial, the best path is to open an issue in this
+repository with as many details about the issue you are facing as you
+can provide.
+
+<https://github.com/openedx/frontend-build/issues>
+
+For more information about these options, see the [Getting
+Help](https://openedx.org/community/connect) page.
+
+## Reporting Security Issues
+
+Please do not report security issues in public. Please email
+<security@openedx.org>.
+
+## Optimization
+
+To increase optimization by reducing unused CSS, you can set
+`USE_PURGECSS=true` in `.env` or as ENV var in the corresponding MFE.
+However, note that doing this will increase build time by 30%. It\'s
+thus not recommended to use this option during development. On the other
+hand, enabling PurgeCSS will increase browser performance for the end
+user by as much as 20% (as measured by
+[lighthouse](https://developer.chrome.com/docs/lighthouse/overview/)).
+Operators are encouraged to do so for production deployments.
+
+For more information about optimizing MFEs, refer to the [issue
+\#138](https://github.com/openedx/wg-frontend/issues/138) in the
+wg-frontend repository.

package/bin/fedx-scripts.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+const chalk = require('chalk');
+
+const presets = require('../lib/presets');
+
+/**
+ * TLDR:
+ *  - Find the command to be run in process.argv
+ *  - Remove fedx-scripts in process.argv
+ *  - Add a --config option to process.argv if one is missing
+ *  - Execute the command's bin script by pulling it directly in with require()
+ *
+ * This file forwards cli commands by manipulating process.argv values and then
+ * directly requiring bin scripts from the specified packages (as opposed to
+ * attempting to run them from the aliases npm copies to the .bin folder upon
+ * install). This seems like a relatively safe thing to do since these file
+ * names are identical to their cli name and this method of requiring/executing
+ * them should behave the same as if run from the command line as usual.
+ */
+
+function optionExists(keys) {
+  return process.argv.some((arg) => {
+    // eslint-disable-next-line no-plusplus
+    for (let i = 0; i < keys.length; i++) {
+      if (arg.startsWith(keys[i])) {
+        return true;
+      }
+    }
+    return false;
+  });
+}
+
+// Ensures that a config option already exists and if it does not adds a default
+function ensureConfigOption(preset, keys = ['--config', '-c']) {
+  if (!optionExists(keys)) {
+    console.log(`Running with resolved config:\n${preset.resolvedFilepath}\n`);
+    process.argv.push(keys[0]);
+    process.argv.push(preset.resolvedFilepath);
+  }
+}
+
+// commandName is the third argument after node and fedx-scripts
+const commandName = process.argv[2];
+
+// remove fedx-scripts from process.argv to allow subcommands to read options properly
+process.argv.splice(1, 1);
+
+switch (commandName) {
+  case 'babel':
+    ensureConfigOption(presets.babel, ['--config-file']);
+    require('@babel/cli/bin/babel');
+    break;
+  case 'eslint':
+    ensureConfigOption(presets.eslint);
+    // eslint-disable-next-line import/extensions, import/no-extraneous-dependencies
+    require('.bin/eslint');
+    break;
+  case 'jest':
+    ensureConfigOption(presets.jest);
+    require('jest/bin/jest');
+    break;
+  case 'webpack':
+    ensureConfigOption(presets.webpack);
+    require('webpack/bin/webpack');
+    break;
+  case 'webpack-dev-server':
+    ensureConfigOption(presets.webpackDevServer);
+    require('webpack-dev-server/bin/webpack-dev-server');
+    break;
+  case 'formatjs': {
+    const commonArgs = [
+      '--format', 'node_modules/@openedx/frontend-build/lib/formatter.js',
+      '--ignore', 'src/**/*.json',
+      '--out-file', './temp/babel-plugin-formatjs/Default.messages.json',
+      '--', 'src/**/*.js*',
+    ];
+    process.argv = process.argv.concat(commonArgs);
+    ensureConfigOption(presets.formatjs);
+    require('@formatjs/cli/bin/formatjs');
+    break;
+  }
+  case 'serve':
+    require('../lib/scripts/serve');
+    break;
+  default:
+    console.log(chalk.red(`[ERROR] fedx-scripts: The command ${chalk.bold.red(commandName)} is unsupported.`));
+}

package/config/.eslintrc.js

@@ -0,0 +1,46 @@
+const { babel } = require('../lib/presets');
+
+module.exports = {
+  extends: '@edx/eslint-config',
+  plugins: ['@typescript-eslint'],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    requireConfigFile: true,
+    babelOptions: {
+      configFile: babel.resolvedFilepath || babel.defaultFilepath,
+    },
+  },
+  rules: {
+    'import/no-extraneous-dependencies': [
+      'error',
+      {
+        devDependencies: [
+          '**/*.config.*',
+          '**/*.test.*',
+          '**/setupTest.js',
+        ],
+      },
+    ],
+    'import/no-unresolved': [
+      'error',
+      {
+        ignore: [
+          'env.config',
+        ],
+      },
+    ],
+    // https://github.com/evcohen/eslint-plugin-jsx-a11y/issues/340#issuecomment-338424908
+    'jsx-a11y/anchor-is-valid': ['error', {
+      components: ['Link'],
+      specialLink: ['to'],
+    }],
+    'import/no-import-module-export': 'off',
+    'react/function-component-definition': [2, { namedComponents: 'arrow-function' }],
+  },
+  globals: {
+    newrelic: false,
+  },
+  ignorePatterns: [
+    'module.config.js',
+  ],
+};

package/config/babel-preserve-modules.config.js

@@ -0,0 +1,30 @@
+module.exports = {
+  presets: [
+    [
+      '@babel/preset-env',
+      {
+        modules: false,
+      },
+    ],
+    '@babel/preset-react',
+  ],
+  plugins: [
+    '@babel/plugin-proposal-object-rest-spread',
+    '@babel/plugin-proposal-class-properties',
+    '@babel/plugin-syntax-dynamic-import',
+  ],
+  env: {
+    i18n: {
+      plugins: [
+        [
+          'formatjs',
+        ],
+      ],
+    },
+    test: {
+      presets: [
+        '@babel/preset-env',
+      ],
+    },
+  },
+};

package/config/babel-typescript.config.js

@@ -0,0 +1,5 @@
+const config = require('./babel.config');
+
+config.presets.push('@babel/preset-typescript');
+
+module.exports = config;

package/config/babel.config.js

@@ -0,0 +1,41 @@
+module.exports = {
+  presets: [
+    '@babel/preset-env',
+    [
+      '@babel/preset-react', {
+        runtime: 'automatic',
+      },
+    ],
+  ],
+  plugins: [
+    '@babel/plugin-proposal-object-rest-spread',
+    '@babel/plugin-proposal-class-properties',
+    '@babel/plugin-syntax-dynamic-import',
+    [
+      'transform-imports',
+      {
+        '@fortawesome/free-brands-svg-icons': {
+          transform: '@fortawesome/free-brands-svg-icons/${member}',
+          skipDefaultConversion: true,
+        },
+        '@fortawesome/free-regular-svg-icons': {
+          transform: '@fortawesome/free-regular-svg-icons/${member}',
+          skipDefaultConversion: true,
+        },
+        '@fortawesome/free-solid-svg-icons': {
+          transform: '@fortawesome/free-solid-svg-icons/${member}',
+          skipDefaultConversion: true,
+        },
+      },
+    ],
+  ],
+  env: {
+    i18n: {
+      plugins: [
+        [
+          'formatjs',
+        ],
+      ],
+    },
+  },
+};

package/config/getLocalAliases.js

@@ -0,0 +1,67 @@
+const path = require('path');
+const fs = require('fs');
+
+/*
+This function reads in a 'module.config.js' file if it exists and uses its contents to define
+a set of webpack resolve.alias aliases for doing local development of application dependencies.
+It reads the package.json file of the dependency to determine if it has any peer dependencies, and
+then forces those peer dependencies to be resolved with the application's version.  Primarily, this
+is useful for making sure there's only one version of those dependencies loaded at once, which is a
+problem with both react and react-intl.
+
+The module.config.js file should have the form:
+
+{
+  localModules: [
+    { moduleName: 'nameOfPackage', dir: '../path/to/repo', dist: '/path/to/dist/in/repo' },
+    ... others...
+  ],
+}
+
+Some working examples, as of the time of this writing:
+
+{ moduleName: '@openedx/paragon/scss', dir: '../paragon', dist: 'scss' }
+{ moduleName: '@openedx/paragon', dir: '../paragon', dist: 'dist' }
+{ moduleName: '@edx/frontend-platform', dir: '../frontend-platform', dist: 'dist' }
+
+*/
+function getLocalAliases() {
+  const aliases = {};
+
+  try {
+    const moduleConfigPath = path.resolve(process.cwd(), 'module.config.js');
+    if (!fs.existsSync(moduleConfigPath)) {
+      console.log('No local module configuration file found. This is fine.');
+      return aliases;
+    }
+    // eslint-disable-next-line import/no-dynamic-require, global-require
+    const { localModules } = require(moduleConfigPath);
+
+    let allPeerDependencies = [];
+    const excludedPeerPackages = [];
+    if (localModules.length > 0) {
+      console.info('Resolving modules from local directories via module.config.js.');
+    }
+    localModules.forEach(({ moduleName, dir, dist = '' }) => {
+      console.info(`Using local version of ${moduleName} from ${dir}/${dist}.`);
+      // eslint-disable-next-line import/no-dynamic-require, global-require
+      const { peerDependencies = {}, name } = require(path.resolve(process.cwd(), dir, 'package.json'));
+      allPeerDependencies = allPeerDependencies.concat(Object.keys(peerDependencies));
+      aliases[moduleName] = path.resolve(process.cwd(), dir, dist);
+      excludedPeerPackages.push(name);
+    });
+
+    allPeerDependencies = allPeerDependencies.filter((dep) => !excludedPeerPackages.includes(dep));
+
+    allPeerDependencies.forEach((dep) => {
+      aliases[dep] = path.resolve(process.cwd(), 'node_modules', dep);
+    });
+  } catch (e) {
+    console.error(e);
+    console.error('Error in module.config.js parsing. module.config.js will be ignored.');
+    return {};
+  }
+  return aliases;
+}
+
+module.exports = getLocalAliases;

package/config/jest/fallback.env.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  // DO NOT PUT ANY CONFIGURATION IN THIS FILE.
+
+  // The existence of this file is a technical detail of the mechanism used to implement
+  // env.config.js files for jest.
+
+  // This file is used as a fallback to prevent build errors if an env.config.js file has not been
+  // defined in a consuming application.  If we could inline an empty object instead of needing a
+  // file to reference, that'd be clearer, but doesn't seem to be an option.
+
+  // This is NOT an appropriate place to put actual configuration values for tests.
+};

package/config/jest/fileMock.js

@@ -0,0 +1 @@
+module.exports = 'test-file-stub';

package/config/jest/setupTest.js

@@ -0,0 +1,10 @@
+const path = require('path');
+const fs = require('fs');
+const dotenv = require('dotenv');
+require('babel-polyfill');
+
+const testEnvFile = path.resolve(process.cwd(), '.env.test');
+
+if (fs.existsSync(testEnvFile)) {
+  dotenv.config({ path: testEnvFile });
+}

package/config/jest/svgrMock.js

@@ -0,0 +1,4 @@
+export const ReactComponent = 'IconMock';
+
+const mock = 'icon/mock/path';
+export default mock;

package/config/jest.config.js

@@ -0,0 +1,45 @@
+const path = require('path');
+const fs = require('fs');
+const { jsWithTs: tsjPreset } = require('ts-jest/presets');
+
+const presets = require('../lib/presets');
+
+let envConfigPath = path.resolve(__dirname, './jest/fallback.env.config.js');
+const appEnvConfigPath = path.resolve(process.cwd(), './env.config.js');
+
+if (fs.existsSync(appEnvConfigPath)) {
+  envConfigPath = appEnvConfigPath;
+}
+
+module.exports = {
+  testURL: 'http://localhost/',
+  setupFiles: [
+    path.resolve(__dirname, 'jest/setupTest.js'),
+  ],
+  rootDir: process.cwd(),
+  moduleNameMapper: {
+    '\\.svg': path.resolve(__dirname, 'jest/svgrMock.js'),
+    '\\.(jpg|jpeg|png|gif|eot|otf|webp|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': path.resolve(__dirname, 'jest/fileMock.js'),
+    '\\.(css|scss)$': 'identity-obj-proxy',
+    'env.config': envConfigPath,
+  },
+  collectCoverageFrom: [
+    'src/**/*.{js,jsx}',
+  ],
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    'setupTest.js',
+  ],
+  transformIgnorePatterns: [
+    '/node_modules/(?!@(open)?edx)',
+  ],
+  transform: {
+    '^.+\\.jsx?$': [
+      'babel-jest',
+      {
+        configFile: presets.babel.resolvedFilepath,
+      },
+    ],
+    ...tsjPreset.transform,
+  },
+};