The build-and-deploy process for micro-frontends (MFEs) throughout Open edX include running the MFE through a production Webpack build process, relying on configuration specified in a webpack.prod.config.js file. The resulting file assets are what ultimately get released to production and served to users. However, it is currently non-obvious how to preview the production file assets generated by npm run build locally should the need arise (e.g., to have more confidence in the resulting Webpack output and/or behavior before relying on the build-and-deploy process to release to a staging/production environment).
Most micro-frontends (MFEs) throughout the Open edX platform rely on a npm run build script that runs a production Webpack build based on the configuration specified in a webpack.prod.config.js file. The webpack-prod.config.js may be provided either by consumers in the root of their MFE's repository (i.e., typically using createConfig to extend/override parts of the default production Webpack configuration), or simply rely on the default webpack.prod.config.js configuration file provided by @edx/frontend-build.
The output from npm run build is generated in a Git-ignored dist directory, and contains the actual files that should be deployed to production.
Included in the dist directory's files is the MFE's index.html file that needs to be served for all routes the user may try loading. By simply loading index.html in the browser, it will inevitably run into some issues (e.g., not supporting React routing, etc.).
To mitigate this, this ADR describes a new mechanism to provide a standard, documented way to serve the generated assets from the production Webpack build when running npm run build.
We will create a new serve command for fedx-scripts that creates an Express.js server to run the generated dist file assets (e.g., index.html) on the PORT specified in the MFE's env.config.js and/or .env.development|private file(s) on localhost.
If no env.config.js and/or .env.development|private file(s) exist and/or no PORT setting is specified those files, the serve command will fallback to a default port 8080, which is similar to the default ports our typical example MFE applications use.
The new serve command will live as under a new scripts directory under lib.
Once in place, a MFE application may add a serve script to its NPM scripts in the package.json file:
{
"scripts": {
"serve": "fedx-scripts serve"
}
}Then, running npm run serve in the root of that MFE application will run the new serve command in @edx/frontend-build, serving the assets in the MFE's dist directory on the PORT specified in the env.config.js file or .env.development|private file(s).