mfer (Micro Frontend Runner)

A powerful CLI tool designed to simplify the management and execution of multiple micro frontend applications. mfer helps developers run, update, and organize their micro frontend projects with minimal configuration and maximum efficiency.

📋 Table of Contents

• 🚀 Features
• 📦 Installation
• 🛠️ Quick Start
• 📋 Commands
• ⚙️ Configuration
• 🎯 Use Cases
• 🔧 Advanced Usage
• 🛠️ Development
• 🐛 Troubleshooting
• 🤝 Contributing
• 📄 License
• 🙏 Acknowledgments

🚀 Features

• Concurrent Execution: Run multiple micro frontends simultaneously with organized output
• Group Management: Organize micro frontends into logical groups for selective execution
• Git Integration: Pull latest changes from all repositories with a single command
• Smart Configuration: Interactive setup wizard with YAML-based configuration
• Cross-Platform: Works on Windows, macOS, and Linux
• Graceful Shutdown: Clean termination of all processes with Ctrl+C

📦 Installation

Prerequisites

• Node.js 18 or higher
• Git (for repository management)

Install from npm

npm install -g mfer

Install from source

git clone https://github.com/srimel/mfer.git
cd mfer
npm install
npm run build
npm install -g .

🛠️ Quick Start

1. Initialize Configuration

Start by setting up your mfer configuration:

mfer init

This interactive wizard will guide you through:

• Setting up your GitHub username
• Specifying the directory containing your micro frontends
• Selecting which projects to include in your default group

2. Run Your Micro Frontends

# Run all micro frontends
mfer run

# Run a specific group
mfer run frontend

# Run with a custom group name
mfer run shared

3. Update Your Repositories

# Pull latest changes from all repositories
mfer pull

# Pull from a specific group
mfer pull frontend

📋 Commands

Quick Reference

• mfer init - Interactive setup wizard
• mfer run - Run micro frontend applications
• mfer pull - Pull latest changes from git repositories
• mfer install - Install dependencies for micro frontends
• mfer clone - Clone repositories that don't exist locally
• mfer lib - Manage internal npm packages
• mfer config - Manage configuration settings
• mfer help - Display help information

mfer init

Interactive setup wizard to create your configuration file.

Options:

• -f, --force: Force re-initialization even if config exists

Example:

mfer init --force

mfer run [group_name]

Run micro frontend applications concurrently.

Arguments:

• group_name: Name of the group to run (defaults to "all")

Options:

• -c, --command <command>: Custom command to run (default: npm start)
• -a, --async: Run custom command concurrently instead of sequentially
• -s, --select: Prompt to select which micro frontends to run

Examples:

mfer run                    # Run all micro frontends with default command (npm start)
mfer run frontend          # Run only frontend group with default command
mfer run --command "npm ci" home    # Run custom command sequentially on home group
mfer run -c "yarn install" shared  # Run yarn install sequentially on shared group
mfer run --command "npm ci" --async home  # Run custom command concurrently on home group
mfer run -c "yarn install" -a shared  # Run yarn install concurrently on shared group
mfer run --command "npm run build" --select  # Select MFEs and run build command sequentially

mfer pull [group_name]

Pull latest changes from git repositories.

Arguments:

• group_name: Name of the group to pull from (defaults to "all")

Options:

• -s, --select: Prompt to select which repositories to pull

Examples:

mfer pull         # Pull from all repositories
mfer pull shared  # Pull from shared components group only
mfer pull --select # Select repositories to pull interactively
mfer pull frontend --select # Select repositories from frontend group

mfer install [group_name]

Install dependencies for all micro frontends in a group.

Arguments:

• group_name: Name of the group to install dependencies for (defaults to "all")

Options:

• -s, --select: Prompt to select which micro frontends to install

Examples:

mfer install          # Install dependencies for all micro frontends
mfer install frontend # Install dependencies for frontend group only
mfer install --select # Select micro frontends to install interactively
mfer install shared --select # Select micro frontends from shared group

mfer clone [group_name]

Clone repositories that don't exist locally.

Arguments:

• group_name: Name of the group to clone repositories from (defaults to "all")

Example:

mfer clone          # Clone all repositories
mfer clone shared   # Clone repositories in shared group only

mfer config

Manage your configuration settings.

Subcommands:

• mfer config list: Display current configuration
• mfer config edit: Open configuration file in your default editor

Example:

mfer config list    # Show current configuration
mfer config edit    # Edit configuration in your editor

mfer help

Display help information for mfer commands.

Example:

mfer help           # Show general help
mfer help run       # Show help for run command
mfer help config    # Show help for config command

mfer lib

Manage internal npm packages and their distribution to micro frontends.

Subcommands:

• mfer lib build - Build internal npm packages
• mfer lib deploy - Copy built libraries to micro frontends
• mfer lib publish - Build and deploy libraries to micro frontends
• mfer lib list - List configured libraries and their status
• mfer lib pull - Pull latest changes from library git repositories
• mfer lib install - Install dependencies for libraries

mfer lib build [lib-name]

Build internal npm packages.

Arguments:

• lib-name: Name of the library to build (builds all if not specified)

Options:

• -s, --select: Prompt to select which libraries to build

Examples:

mfer lib build                    # Build all libraries
mfer lib build my-shared-utils    # Build specific library
mfer lib build --select           # Select libraries to build interactively

mfer lib deploy [lib-name]

Copy built libraries to micro frontends.

Arguments:

• lib-name: Name of the library to deploy (deploys all if not specified)

Options:

• -s, --select: Prompt to select which libraries to deploy

Examples:

mfer lib deploy                    # Deploy all libraries
mfer lib deploy my-shared-utils    # Deploy specific library
mfer lib deploy --select           # Select libraries to deploy interactively

mfer lib publish [lib-name]

Build and deploy libraries to micro frontends.

Arguments:

• lib-name: Name of the library to publish (publishes all if not specified)

Options:

• -s, --select: Prompt to select which libraries to publish

Examples:

mfer lib publish                    # Publish all libraries
mfer lib publish my-shared-utils    # Publish specific library
mfer lib publish --select           # Select libraries to publish interactively

mfer lib list

List configured libraries and their status.

Example:

mfer lib list    # Show all configured libraries and their build status

mfer lib pull [lib-name]

Pull latest changes from library git repositories.

Arguments:

• lib-name: Name of the library to pull from (pulls all if not specified)

Options:

• -s, --select: Prompt to select which libraries to pull

Examples:

mfer lib pull                    # Pull from all libraries
mfer lib pull my-shared-utils    # Pull from specific library only
mfer lib pull --select           # Select libraries to pull interactively
mfer lib pull my-design-system --select # Select libraries from specific library

mfer lib install [lib-name]

Install dependencies for libraries.

Arguments:

• lib-name: Name of the library to install dependencies for (installs all if not specified)

Options:

• -s, --select: Prompt to select which libraries to install

Examples:

mfer lib install                    # Install dependencies for all libraries
mfer lib install my-shared-utils    # Install dependencies for specific library only
mfer lib install --select           # Select libraries to install interactively
mfer lib install my-design-system --select # Select libraries from specific library

⚙️ Configuration

mfer uses a YAML configuration file located at ~/.mfer/config.yaml. Here's an example structure:

base_github_url: "https://github.com/your-username"
mfe_directory: "/path/to/your/micro-frontends"
lib_directory: "/path/to/your/internal-libs"
libs:
  - my-shared-utils
  - my-design-system
  - my-common-components
groups:
  all:
    - my-main-app
    - my-admin-panel
    - my-shared-components
  main:
    - my-main-app
    - my-shared-components
  admin:
    - my-admin-panel
    - my-shared-components

Configuration Options

• base_github_url: Your GitHub base URL for repository operations
• mfe_directory: Path to the directory containing all your micro frontend projects
• lib_directory: Path to the directory containing your internal npm packages (optional)
• libs: List of internal npm package names to manage (optional)
• groups: Named collections of micro frontend projects
  • all: Default group containing all projects (required)
  • Custom groups: Any additional groups you want to create

Editing Configuration

You can edit your configuration in several ways:

1. Interactive editor (recommended):

   mfer config edit

2. Direct file editing:

   # On macOS/Linux
   nano ~/.mfer/config.yaml
   
   # On Windows
   notepad %USERPROFILE%\.mfer\config.yaml

🎯 Use Cases

Development Workflow

# Start your day
mfer pull          # Get latest changes
mfer run main      # Start main application

# Later, switch to admin panel work
mfer run admin     # Start admin panel

Project Organization

Organize your micro frontends into logical groups:

groups:
  all:
    - main-app
    - admin-panel
    - user-dashboard
    - shared-components
    - design-system
  core:
    - main-app
    - shared-components
    - design-system
  admin:
    - admin-panel
    - user-dashboard
    - shared-components
  ui:
    - shared-components
    - design-system

Team Collaboration

• Share configuration files with your team
• Standardize development environment setup
• Ensure everyone runs the same services

🔧 Advanced Usage

Custom Start Commands

By default, mfer runs npm start in each project directory. You can currently only customize this by modifying the run command in the source code.

Adding configurable custom start commands is something I plan on adding in the near future. I also welcome anyone to open a PR for that!

Environment Variables

mfer respects your existing environment setup and will use the same Node.js and npm versions you have configured.

Process Management

• All processes are managed concurrently with organized output
• Use Ctrl+C to gracefully shut down all running services
• Failed processes are reported with detailed error information

🛠️ Development

Local Development Setup

For contributing to mfer or setting up a local development environment:

git clone https://github.com/srimel/mfer.git
cd mfer
npm install
npm run build
npm install -g .

Testing with Playground

The project includes a comprehensive playground for testing mfer commands with sample micro frontends. The playground contains:

• libs/common-utils: A shared utility library
• frontends/mfe1, mfe2, mfe3: Three React micro frontends with different themes
• Complete setup instructions and testing scenarios

📖 View detailed local development guide →

🐛 Troubleshooting

Common Issues

"No configuration file detected"

# Run the initialization wizard
mfer init

"Group not found"

# Check available groups
mfer config list

# Edit configuration to add missing group
mfer config edit

"Directory does not exist"

• Ensure the mfe_directory path in your configuration is correct
• Use absolute paths for better reliability
• Check that the directory exists and is accessible

"Not a git repository"

• Ensure all projects in your configuration are valid git repositories
• Run mfer clone to clone missing repositories

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with:

• Commander.js - CLI framework
• Inquirer - Interactive prompts
• Concurrently - Process management
• Chalk - Terminal styling
• YAML - Configuration parsing