@multisystemsuite/create-mf-app 1.0.5

package/README.md

@@ -0,0 +1,249 @@
+# 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:
+
+```bash
+npx create-mf-app inventory --template=tsx --port=3001
+cd inventory
+npm install
+npm run dev
+```
+
+Parent monorepo:
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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
+
+```text
+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:
+
+```text
+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:
+
+```text
+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`:
+
+```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:
+  ```bash
+  rmdir /s /q node_modules
+  del package-lock.json
+  npm cache verify
+  npm install
+  ```
+
+Published files:
+
+- `dist/`
+- `README.md`

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }