Developing microfrontends

What is a microfrontend (mfe)?

Single-spa allows us to connect independently-running applications into our root IA app and display them as pieces of our app. They can be developed and deployed separately from our root app while still being integrated and displayed as needed.
Once a mfe insertion point has been set up within IA, develop your mfe and enter your mfe’s URL using IA’s UI at the desired insertion point.

Developing your microfrontend

**** Please browse our existing microfrontends in case one already meets your needs. If you need to create a new one, consider following the instructions within that Github repository to add your plugin there so that it will be available for reuse in the future. If you’d prefer to host your plugin separately, proceed with the instructions below: ****

If you choose to host your own microfrontend:

Single-spa is built so you can write your mfe and host it wherever you’d like (e.g., GitHub, Bitbucket, etc.) We recommend using the following because we have tested this approach, and you can benefit from our shared utility functions, which are written in TypeScript:
- Webpack
- React TypeScript
- Hosted on GitHub (unless you provide a link to your code’s compiled JavaScript entry file).
Follow the instructions for create-single-spa to set up your app. When asked to select the type to generate, choose single-spa application/parcel and React TypeScript.
Build your app.
Deploying and updating: Provide a URL that points to your application’s JavaScript entry file. Here is an example of how to do this if you have hosted your code on GitHub:
- Build your code for production, push your code, including the dist folder to GitHub, and create a release on GitHub. Ensure your gitignore doesn’t list your dist folder when you commit it.
- Using jsDelivr, follow the instructions for linking to the release version you just created (e.g., https://cdn.jsdelivr.net/gh/<yourUser>/<repoName>@<version>/dist/<orgName-org-projectName>.js).
- Edit your URL in IA so that it contains the new release.

Imports and utils

We have included a handful of packages in the import-map of our root app. They are available to be shared by your mfe without compiling them. You still need to install any of these packages you’d like to use to find their TypeScript types. Here are the versions you need to install to match the version within IA:

npm install react@^17.0.2;
npm install react-dom@^17.0.2;
npm install single-spa@^5.9.4;
npm install react-query@^3.34.7;
npm install @material-ui/core@4.12.4;
npm install @material-ui/icons@4.11.3;
npm install @material-ui/lab@4.0.0-alpha.61;
npm install react-router-dom@^6.3.0;
npm install @clearblade/ia-mfe-core@latest; // This contains our exposed utility functions and types
npm install @clearblade/ia-mfe-react@latest; // This contains our exposed utility functions and types that depend on react

If you use any of these packages, add them to your external configuration within your webpack.config to avoid compiling them. Single-spa automatically includes react, react-dom, and single-spa in your externals.

// within webpack.config.js

return merge(defaultConfig, {
    externals: [
      '@clearblade/ia-mfe-core',
      '@clearblade/ia-mfe-react',
      'react-query',
      '@material-ui/core',
      '@material-ui/icons',
      '@material-ui/lab',
      'react-router-dom',
      'single-spa',
    ],
  });

Helpful tips for development

Here is a list of useful libraries we do not include in our import map but that may be useful in achieving certain features for your microfrontend

IA local development

Run the IA repo and mfe locally.
Point your plugin URL to your local mfe: (e.g., //localhost:8081/my-mfe-entry-point.js).
When you’re happy with your local code, publish a new version and point the plugin URL to that new version (see deploying instructions below).