Create a module federation app

Developed by Jack Herrington , co-author of the "Practical Module Federation" book and technology-focused YouTuber.

create-mf-app is a tool that creates a Module Federation application, API server, or library based on one of multiple different templates.

Generating Application

This guide provides a comprehensive walkthrough on how to use the create-mf-app tool to create a Module Federation application and integrate it with Zephyr.

To execute npm package binaries, use the npx command as follows:

Terminal
npx create-mf-app

Choose a name for your application. Ensure you designate one host and at least one remote, choosing names that reflect their roles accordingly.

? Pick the name of your app: (host)

Select the type of application:

? Project Type: (Use arrow keys) Application API Server Library

You may use the default port option:

? Port number: (8080)

We conducted tests using React, but other frameworks may also be compatible. See a list of tested framework here

? Framework: (Use arrow keys) lit-html preact react react-esm solid-js svelte vanilla (Move up and down to reveal more choices)

We prefer TypeScript, but Zephyr is compatible with both TypeScript and JavaScript.

? Language: typescript javascript

Both CSS and Tailwind are viable options for styling:

? CSS: (Use arrow keys) CSS Tailwind

While both packing options are viable, we strongly recommend Rspack for its performance. See benchmark of Rspack.

? Bundler: (Use arrow keys) Webpack Rspack

Adding Zephyr to Your Module Federation App

Installing Zephyr plugin:

Terminal
cd create-mf-app-rspack-host npm install zephyr-webpack-plugin --save

Zephyr Configuration Integration

Incorporate the Zephyr configuration into your existing setup by wrapping the current configuration object with Zephyr's functionality. This enhancement is performed using the zephyr-webpack-plugin, as demonstrated below:

rspack.config.js
module.exports = {/* the existing config object */}; const { withZephyr } = require('zephyr-webpack-plugin'); module.exports = withZephyr()({/* the existing config object */});

Setting a Git Origin

  1. Initialize the Git Repository:

Initialize the Git repository to start tracking your project:

Terminal
git init
  1. Stage Files for Commit:

Add all files to the staging area in preparation for the initial commit:

Terminal
git add --all
  1. Create an Initial Commit:

Commit the staged files to your repository with a descriptive message:

Terminal
git commit -m "Initial commit with Zephyr"
  1. Set the Default Branch Name:

Define 'main' as the default branch for your repository:

Terminal
git branch -M main
  1. Add a Remote Origin: Zephyr requires a Git origin to establish a unique project, application, and version combination. Replace User and UserRepo with your GitHub username and repository name:
Terminal
git remote add origin https://github.com/User/UserRepo.git
  1. Push to GitHub (Optional):

Optionally, you can push your code to GitHub to store your changes remotely:

Terminal
git push -u origin main
INFO

Error Handling: If you encounter errors due to unset Git configurations, ensure you have set both your Git user.name and user.email, and that you have a valid 'git remote origin' set up.

[ConfigurationError: [zephyr]: git is not configured properly - please set git user.name and user.email - please set valid 'git remote origin' ]

If this error show up - create a new repository and copy the link to that repository, do:

Terminal
git remote add origin [email protected]:User/UserRepo.git

Using Zephyr

Zephyr operates as a side effect of the build process, allowing you to execute the build in watch mode for continuous updates.

INFO

Please note that until Alpha 1 is released to production, you will need to operate within our development environment using the following environment variable:

Terminal
npm run build --watch
INFO

The first time you initiate a build with Zephyr, it will prompt you to log in by directing you to the Zephyr website. This login is required only on your first build; subsequent builds will not require a login.

Understanding Build Outputs

During the build process, three distinct URIs are generated as follows:

  1. An individual snapshot of the build.
  2. The current tag.
  3. The current environment.

For a detailed explanation of these outputs, please refer to our versioning documentation.

terminal
[zephyr]: [zephyr-2.zephyr-2.zackarychapple](zack_zephyr-cloud_io)[10]: deploying to https://zack_zephyr-cloud_io_10-zephyr-2-zephyr-2-zackarychapple-ze.valorkin.dev [zephyr]: [zephyr-2.zephyr-2.zackarychapple](zack_zephyr-cloud_io)[10]: deploying to https://zephyr-2-zephyr-2-zackarychapple-ze.valorkin.dev [zephyr]: [zephyr-2.zephyr-2.zackarychapple](zack_zephyr-cloud_io)[10]: deploying to https://t_main_zack_zephyr-cloud_io-zephyr-2-zephyr-2-zackary-5c1b61-ze.valorkin.dev
INFO

Please note that the live reload functionality on remotes is currently unavailable and will be addressed shortly.

Next Steps

You can now proceed to add remotes and start building your federated application as planned.

For insights on building micro-frontends with Rspack and Create MF App, Jack offers an informative video tutorial. We have also curated a resource page related to micro-frontend and module federation here.