create-mf-app

TypeScript CLI that scaffolds enterprise microfrontend applications and monorepos using React 19, Vite 7, Module Federation, React Router, Docker, and npm workspaces.

What it generates

• Single app scaffold (child mode)
• Parent monorepo scaffold (parent mode) with:
  • apps/main host
  • multiple remote apps
  • shared app(s) such as sharedlib
  • root scripts for dev/build/watch/preview/release

Quick start

Single app:

npx create-mf-app inventory --template=tsx --port=3001
cd inventory
npm install
npm run dev

Parent monorepo:

npx create-mf-app my-platform --type=parent --children=billing,orders,analytics,warehouse --shared=corelib --template=tsx
cd my-platform
npm install
npm run local

CLI usage

npx create-mf-app <project-name> [options]

Options:

• --port=3001
• --template=tsx|jsx
• --typescript (alias for --template=tsx)
• --javascript (alias for --template=jsx)
• --type=parent|child
• --children=billing,orders,analytics
• --shared=sharedlib
• --docker=true|false
• --federation=true|false
• -y, --yes
• -h, --help

Interactive flow

When running npx create-mf-app:

• Project Name
• Application Type (Parent / Child)
• Child Applications (for parent)
• Shared Applications (for parent)
• Template (TSX / JSX)
• Port
• Module Federation (Yes/No)
• Docker (Yes/No)

Parent mode behavior

• main is mandatory and reserved as host.
• main is auto-created and cannot be passed in children or shared.
• If --shared is omitted in parent mode, generator auto-adds sharedlib.
• Children can be passed comma-separated or space-separated.

Example:

npx create-mf-app my-platform --type parent --children billing orders analytics --template tsx

You can use any project/module names (for example billing, orders, analytics) except reserved main.

Generated parent structure

my-platform/
├── apps/
│   ├── main/
│   ├── billing/
│   ├── orders/
│   ├── analytics/
│   └── corelib/
├── packages/
│   ├── shared-ui/
│   ├── shared-utils/
│   └── shared-auth/
├── scripts/
├── docker-compose.yml
├── .env
├── package.json
├── live-reload.js
├── smart-build.js
├── print-env.js
└── README.md

Root workspace scripts (parent mode)

Generated root scripts include:

• local, dev, dev:watch, dev:fast, dev:safe
• build:local, build:dev, build:staging, build:uat, build:production
• app-specific scripts like billing, orders, analytics, warehouse
• watch:*, preview:*, watch:local:*, preview:local:*
• release, release:minor, release:major

Module Federation wiring

Generator configures:

• remoteEntry.js
• host remotes registration in main
• remote exposes (./App)
• shared singleton dependencies:
  • react
  • react-dom
  • react-router-dom

Sharedlib integration

• corelib exposes ./SharedBadge
• child apps consume corelib/SharedBadge
• main app provides navbar + route-based remote loading:
  • /billing/*
  • /orders/*
  • /analytics/*
  • etc.

Shared configuration system (enterprise)

For parent mode with shared app (for example sharedlib or corelib), generator scaffolds centralized runtime configuration:

apps/sharedlib/src/config/
├── AppConfigProvider.tsx
├── configStore.ts
├── defaultConfig.ts
├── themeGenerator.ts
├── useAppConfig.ts
└── types.ts

It powers:

• branding and title settings
• color and typography runtime changes
• sidebar/navbar/layout toggles
• dark/light mode switching
• preset themes
• import/export config JSON
• localStorage persistence

MUI settings page is generated at:

• apps/sharedlib/src/pages/Settings/SettingsPage.tsx

Main app exposes routes:

• /settings/theme
• /settings/layout
• /settings/branding

Shared UI foundation is also generated:

apps/sharedlib/src/shared-ui/
├── AppButton/
├── AppCard/
├── AppDialog/
├── AppTable/
├── AppInput/
├── AppNavbar/
├── AppSidebar/
└── ThemeProvider/

Additional enterprise placeholders are scaffolded (permissions, feature flags, plugin registry, route guard, error boundary, global snackbar, i18n starter, command palette, notification center, profile dropdown, analytics/audit placeholders).

Template support

TSX template

• App.tsx, main.tsx, vite.config.ts, tsconfig.json
• Type declaration files for federated remotes are generated automatically in parent mode

JSX template

• App.jsx, main.jsx, vite.config.js, jsconfig.json

Environment files

Each app gets app-level .env:

VITE_PORT=3001
VITE_APP_NAME=billing
VITE_REMOTE_ENTRY=http://localhost:3001/assets/remoteEntry.js

Parent workspace also gets root .env with all app ports/remote URLs.

Docker support

• Dockerfile generated per app (if Docker enabled)
• parent mode generates docker-compose.yml

Node version requirement

Generated projects use Vite 7. Use Node:

• >=20.19.0 or
• >=22.12.0 (recommended: Node 22)

If using Node 18, Vite commands will fail.

Troubleshooting

• "local" cannot be used as a mode name
  • fixed by using localdev mode in generated scripts
• useRoutes() may be used only in context of a <Router>
  • fixed by sharing react-router-dom singleton in federation config
• MUI/CSS not applied across remotes
  • fixed by sharing @mui/material, @mui/icons-material, @emotion/react, and @emotion/styled as federation singletons
• Cannot find module 'billing/App' in TS
  • fixed via generated .d.ts federation module declarations in TSX parent apps
• Task not found: live-reload
  • fixed via generated root script "live-reload": "node live-reload.js"
• Install succeeded but Vite binary missing (ERR_MODULE_NOT_FOUND ... vite/dist/node/cli.js)
  • clean and reinstall in generated workspace:

  rmdir /s /q node_modules
  del package-lock.json
  npm cache verify
  npm install

Published files:

• dist/
• README.md