create-mf-app

@multisystemsuite/create-mf-app — TypeScript CLI that scaffolds production-grade enterprise microfrontend platforms using React 19, Vite 7, Module Federation, React Router, Material UI, Docker, and npm workspaces.

Includes 10+ architect-level pillars — security, observability, scalability, failure recovery, folder structure, CI/CD, accessibility, DX, and a capstone architect guide with audit scripts for every pillar.

Inspired by Module Federation — optimized for React microfrontends, Vite, runtime federation, SaaS dashboards, and internal developer platforms.

Table of contents

• Install & run the CLI
• What it generates
• Quick start
• How to use the generated project
• CLI reference (create-mf-app)
• Custom child & shared app names
• Enterprise platform flags
• Enterprise architect pillars
• Generated monorepo structure
• Infrastructure & deployment (parent workspaces)
• MF Platform CLI (inside generated projects)
• Using corelib (shared library)
• Enterprise design system & theming
• Module Federation
• Performance & federation architecture
• SDK packages
• Task runner & build cache
• Plugins & devtools
• Runtime configuration
• Template marketplace
• CI/CD & governance
• Code quality
• Root workspace scripts
• Docker & deployment
• Documentation in generated projects
• Node version
• Troubleshooting
• Develop & publish this package

Install & run the CLI

You do not need to clone this repo to use the tool. Install and run via npx (recommended):

npx @multisystemsuite/create-mf-app@latest my-platform --type=parent --children=billing,orders --shared=corelib --template=tsx

Or use the short binary name (same package):

npx create-mf-app my-platform --type=parent --children=billing,orders --shared=corelib

Contributors: npx installs the published npm package. To test unreleased generator changes from this repo, build and run locally — see Develop & publish this package.

npm run build
node dist/index.js my-platform --control-plane -y
node dist/index.js my-platform --type=parent --children=admin,billing --shared=corelib -y
node dist/index.js add-child analytics --cwd=./my-platform --port=4205 -y

Global install (optional):

npm install -g @multisystemsuite/create-mf-app
create-mf-app my-platform --type=parent --children=billing,orders --shared=corelib

Interactive mode (no project name — prompts for all options):

npx create-mf-app

Help:

npx create-mf-app --help

After scaffolding, always:

cd <project-name>
npm install

Then use the scripts in How to use the generated project.

What it generates

Single app (--type=child)

• React + Vite + Module Federation remote
• TypeScript (.tsx) or JavaScript (.jsx)
• Optional Docker
• Standalone dev on --port (default 3001)

Parent monorepo (--type=parent)

• apps/main — host shell (router, sidebar, navbar, command palette)
• apps/<child> — federated remotes (names you pass in --children)
• apps/corelib (or custom --shared name) — shared federated library (design system, RBAC, UI)
• packages/* — shared npm workspace libraries
• tools/mf-cli — MF platform CLI (mf generate, mf graph, mf affected, …)
• task-runner/ — parallel builds + hash cache (.mf/cache)
• plugins/ — React, Vite, Federation, MUI, Auth, Charts, Workflow, Monitoring
• devtools/ — federation inspector, profiler, theme inspector
• runtime-config/ — tenant configs, remote manifests, pillar configs (scaling, resilience, structure, observability, architect roadmap)
• templates/ — LIMS, ERP, HMS, SaaS enterprise blueprints
• ai/ — AI-ready prompt engine + semantic search hooks
• governance/ — import boundaries, CODEOWNERS, dependency rules
• Enterprise pillar docs + audits — security, DX, observability, a11y, CI/CD, scalability, failure recovery, folder structure, architect capstone
• CI/CD — GitHub Actions, GitLab CI, Helm chart
• Root scripts for dev, watch, preview, release, affected builds, per-child dev shortcuts

Quick start

Single remote app

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

Open http://localhost:3001

Parent monorepo (full platform)

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

Open http://localhost:3000 (host). Child remotes load on routes like /billing, /orders, etc.

Full enterprise platform (all optional modules)

npx create-mf-app my-platform \
  --type=parent \
  --children=billing,orders,analytics,warehouse \
  --shared=corelib \
  --template=tsx \
  --auth \
  --charts \
  --storybook \
  --monitoring \
  --table \
  --form-engine \
  --i18n \
  --testing \
  --pwa \
  --plugin-system

How to use the generated project

First-time setup

cd my-platform
npm install          # hoisted workspaces — required for federation shared deps
npm run local        # build all apps → watch → preview all ports → live-reload

| Command | When to use | |---------|-------------| | npm run local | Default daily dev — all apps (main + every child + shared lib) | | npm run local:fast | Smart build (skip unchanged) + watch + preview — faster iteration | | npm run dev | Print env + run each app's Vite dev server (no federation build watch) | | npm run dev:fast | Dev build once, then preview + live-reload | | npm run dev:safe | Production build, then preview only |

Work on one module only (faster)

The generator creates one npm script per child name from --children. Each script starts only the apps that module needs:

| You run | Apps started | Typical URL | |---------|--------------|-------------| | npm run billing | main + corelib + billing | http://localhost:3000/billing | | npm run orders | main + corelib + orders | http://localhost:3000/orders | | npm run analytics | main + corelib + analytics | http://localhost:3000/analytics | | npm run corelib | main + corelib | http://localhost:3000 |

Example: only billing team local dev:

npm run billing
# edit apps/billing/src/...
# host reloads billing remote from localhost:3001

Scripts are generated dynamically from your --children list — if you scaffold with --children=invoicing,shipping, you get npm run invoicing and npm run shipping automatically.

Port assignment

Ports are assigned sequentially from 3000:

| App order | Example names | Port | |-----------|---------------|------| | 1st | main (always host) | 3000 | | 2nd | first child | 3001 | | 3rd | second child | 3002 | | … | … | … | | last | shared lib (corelib) | highest port |

Check your generated root README.md or .env for the exact map.

Build for environments

npm run build:local      # localdev mode — used by npm run local
npm run build:dev        # dev
npm run build:staging    # staging (+ cleanup first)
npm run build:uat        # uat
npm run build            # production (alias: build:production)

Release version

npm run release          # patch bump + build
npm run release:minor
npm run release:major

Typical developer workflow

1. Scaffold with npx create-mf-app …
2. npm install at monorepo root
3. npm run local or npm run <your-module> for focused work
4. Edit apps/<module>/src/ — routes, pages, services
5. Use corelib for shared UI, theme, RBAC (see below)
6. npm run type-check / npm run lint before commit
7. npm run build:production before deploy
8. npm run federation:verify to check remoteEntry URLs

Add a new remote after scaffold

Recommended — use create-mf-app add-child (fully wires federation, host routes, mf.json, env ports, and npm scripts):

npx create-mf-app add-child analytics --cwd=./my-platform --port=4205 -y

From the CLI repo during development:

node dist/index.js add-child analytics --cwd=./mf-structure-test --port=4205 -y

This scaffolds apps/analytics/, updates the host router (/analytics/*), corelib registries, remote-manifest.json, root package.json scripts (npm run analytics), and .env port entries — the same wiring as children created at initial scaffold time.

Alternative — MF CLI inside the monorepo (minimal scaffold; manual federation wiring may still be needed):

npm run mf -- generate app inventory

Or copy an existing child app folder and update mf.json, federation.config.ts, host routes, and root package.json scripts manually.

CLI reference (create-mf-app)

Create a new project

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

| Option | Description | |--------|-------------| | --port=3001 | Dev/preview port (single app / child mode only) | | --template=tsx\|jsx | TypeScript or JavaScript | | --typescript | Alias for --template=tsx | | --javascript | Alias for --template=jsx | | --type=parent\|child | Monorepo or single app (default: child) | | --children=billing,orders | Child remote app folder names (parent mode, required) | | --shared=corelib | Shared federated lib folder name (default: sharedlib) | | --docker=true\|false | Generate Dockerfiles (default: true) | | --federation=true\|false | Module Federation (default: true) | | --control-plane | Workflow Designer & Monitoring preset (6 apps + corelib, control-plane API, mf-* packages) | | --federation-os | Full Enterprise Federation OS preset (10 apps + corelib, runtime, observability stack) | | --lite | Faster install — skip ESLint/Vitest/Husky stack and optional SDK packages | | -y, --yes | Non-interactive (use defaults where applicable) | | -h, --help | Show help |

Faster install (--lite):

npx create-mf-app my-platform --type=parent --children=billing,orders --shared=corelib --lite -y

Skips ESLint, Prettier, Stylelint, Vitest, Husky, commitlint, and optional SDK packages (api-client, sdk-core, websocket-sdk). Federation, apps, corelib, and query-client are still included — typical install drops from ~850 to ~400 packages.

Other ways to speed up install:

• Exclude the project folder from Windows Defender real-time scan
• Second npm install is much faster (npm cache)
• Use HUSKY=0 npm install to skip git hooks on any scaffold
• Fewer --children = fewer apps = less to resolve

Add a child to an existing parent workspace

npx create-mf-app add-child <child-name> --cwd=./my-platform [options]

| Option | Description | |--------|-------------| | --cwd=./my-platform | Parent monorepo root (must contain mf.json; default: current directory) | | --port=4205 | Dev/preview port for the new remote (default: next free port after existing apps) | | -y, --yes | Non-interactive | | -h, --help | Show add-child help |

Example:

npx create-mf-app add-child analytics --cwd=./my-platform --port=4205 -y
cd my-platform
npm run analytics

What gets updated:

• apps/<child-name>/ — full enterprise child remote scaffold
• mf.json — project registry + federation remotes
• apps/main — host routes, federation config, remote type declarations
• apps/corelib — permission/module/feature registries, sidebar menu
• runtime-config/remote-manifest.json — remote entry map
• Root package.json — npm run <child>, watch/preview/build scripts
• .env / env variants — port and remoteEntry URLs
• docker-compose.yml and infrastructure/ — when present in the workspace

Rules:

• Workspace must be an existing parent monorepo with mf.json
• Child name: letters, numbers, dashes only (^[a-z0-9-]+$)
• Do not use main or the shared lib name (e.g. corelib)
• Child must not already exist under apps/

Parent mode rules:

• main is always created as the host — never pass it in --children or --shared
• --children is required in parent mode (comma- or space-separated)
• If --shared is omitted, generator uses sharedlib
• Child names become apps/<name>/ folders and npm run <name> scripts

Interactive flow (run without project name):

1. Project name
2. Application type (parent / child)
3. Parent only: Workflow Designer & Monitoring (--control-plane)?
4. Parent only (if not control-plane): Full Enterprise Federation OS (--federation-os)?
5. Child applications — checkbox pick or auto-filled when a preset is selected
6. Shared applications — comma-separated or auto-filled when a preset is selected
7. Template (tsx / jsx)
8. Port (child mode; presets assign ports from 3000 sequentially)
9. Module Federation on/off
10. Docker on/off

Preset behavior: choosing --control-plane or --federation-os skips manual child/shared selection and applies the fixed app list documented below.

Custom child & shared app names

Folder names are entirely user-defined via CLI flags:

npx create-mf-app acme-platform \
  --type=parent \
  --children=invoicing,shipping,reports \
  --shared=corelib \
  --template=tsx

Creates:

apps/main/
apps/invoicing/      → npm run invoicing
apps/shipping/       → npm run shipping
apps/reports/        → npm run reports
apps/corelib/

Host routes (auto-wired): /invoicing/*, /shipping/*, /reports/*

Rules for names:

• Letters, numbers, dashes only (^[a-z0-9-]+$)
• Lowercase recommended (billing, not Billing)
• Do not use main — reserved for host

Enterprise platform flags

Optional modules for parent monorepos (core modules are always included):

| Flag | Generated module | |------|------------------| | --auth | OAuth/OIDC foundation in apps/corelib/src/auth/ + packages/auth-sdk | | --charts | Chart widgets in apps/corelib/src/charts/ | | --storybook | .storybook/ + component stories | | --monitoring | Logger, telemetry, Sentry, audit in apps/corelib/src/monitoring/ | | --table | Advanced AppDataGrid (on by default for parent workspaces) | | --form-engine | Schema-driven forms in apps/corelib/src/form-engine/ | | --i18n | Lazy locales + RTL in apps/corelib/src/i18n/ | | --testing | Vitest workspace + Playwright + Cypress configs | | --pwa | PWA manifest placeholder | | --plugin-system | Runtime plugin registry in apps/corelib/src/plugins/ | | --federation-os | Full Enterprise Federation OS — see below | | --control-plane | Workflow Designer & Monitoring Platform — see below |

Workflow Designer & Monitoring (--control-plane)

Focused enterprise control plane matching the Micro Frontend Workflow Designer spec:

npx @multisystemsuite/create-mf-app my-control-plane --control-plane -y

| Layer | Generated | |-------|-----------| | 6 apps + corelib | shell (main), admin, analytics, auth, workflow-monitor-app, federation-registry-app, corelib | | 5 packages | @scope/shared-ui, mf-monitor, mf-workflow, mf-devtools, mf-registry | | Services | services/control-plane-api (Express + Socket.IO + MongoDB) | | UI | React Flow designer, real-time monitor, registry, deployments, analytics, environments |

Workflow Designer tab at http://localhost:3004 (or via shell at /workflow-monitor-app) — federation topology with live node health, auto-layout, and save/scan controls.

Federation Monitor tab — healthy/unhealthy summary cards and real-time remote health stream (Socket.IO from control-plane API on :4000).

npm run control-plane
npm run mss-mf -- generate workflow
npm run mss-mf -- generate monitor
npm run mss-mf -- scan federation
npm run mss-mf -- add remote analytics-app
npm run mss-mf -- generate env prod

Default ports (--control-plane):

| App | Port | |-----|------| | main (shell) | 3000 | | admin-app | 3001 | | analytics-app | 3002 | | auth-app | 3003 | | workflow-monitor-app | 3004 | | federation-registry-app | 3005 | | corelib | 3006 | | Control-plane API | 4000 |

Enterprise Federation OS (--federation-os)

One flag scaffolds the complete control plane platform:

npx @multisystemsuite/create-mf-app my-federation-platform --federation-os -y

| Layer | Generated | |-------|-----------| | 10 applications | Shell (main), admin, analytics, auth, workflow-designer, federation-monitor, federation-registry, federation-runtime, federation-governance, deployment-control-plane + corelib | | 10 packages | @scope/mf-runtime, mf-monitor, mf-workflow, mf-registry, mf-devtools, mf-observability, mf-security, mf-governance, mf-ai-assistant, shared-ui | | Services | services/control-plane-api — Express + Socket.IO + REST (registry, monitor, workflow, deployments, governance, AI) | | Runtime | runtime/ — dynamic remote loading + auto-discovery | | Monitoring | Prometheus + Grafana + OpenTelemetry configs | | Infrastructure | docker-compose.federation-os.yml, Kubernetes manifests, CI pipeline | | Architecture protection | .mss-protected.json + mss-mf protect / delete guards |

Federation OS CLI:

npm run control-plane              # API on :4000
npm run federation-os:infra        # MongoDB, Redis, Postgres, Prometheus, Grafana
npm run mss-mf -- federation scan  # Auto-discover federation configs
npm run mss-mf -- federation validate
npm run mss-mf -- runtime start
npm run mss-mf -- deploy prod

Default ports (--federation-os):

| App | Port | |-----|------| | main (shell) | 3000 | | admin-app | 3001 | | analytics-app | 3002 | | auth-app | 3003 | | workflow-designer-app | 3004 | | federation-monitor-app | 3005 | | federation-registry-app | 3006 | | federation-runtime-app | 3007 | | federation-governance-app | 3008 | | deployment-control-plane-app | 3009 | | corelib | 3010 | | Control-plane API | 4000 |

See generated docs/FEDERATION_OS.md for full architecture.

Always included for federated parent workspaces (no flag needed):

| Module | Location | |--------|----------| | Design tokens | apps/corelib/src/tokens/ | | Layouts | apps/corelib/src/layouts/ (Dashboard, Auth, Settings, Split, Fullscreen, Error) | | RBAC | apps/corelib/src/permissions/ | | Federation registry | apps/corelib/src/federation/ | | Command palette | apps/corelib/src/command-palette/ (Ctrl+K) | | Production hardening | apps/corelib/src/production/ (CSP, env validation, diagnostics) | | React architecture | apps/corelib/src/architecture/ + docs/REACT_ARCHITECTURE.md | | Security hardening | apps/corelib/src/security/ + docs/FRONTEND_SECURITY.md | | Observability | apps/corelib/src/monitoring/, observability/ + docs/OBSERVABILITY.md | | Accessibility | apps/corelib/src/accessibility/ + docs/ACCESSIBILITY.md | | Release engineering | apps/corelib/src/release/ + docs/CICD_RELEASE_ENGINEERING.md | | Scalability | apps/corelib/src/scalability/ + docs/ENTERPRISE_SCALABILITY.md | | Failure recovery | apps/corelib/src/resilience/ + docs/FAILURE_RECOVERY.md | | Folder structure | apps/corelib/src/structure/ + docs/ENTERPRISE_FOLDER_STRUCTURE.md | | Architect capstone | apps/corelib/src/architect/ + docs/ARCHITECT_LEVEL_GUIDE.md | | MF Platform CLI | tools/mf-cli/ | | Project graph | tools/project-graph/ | | Task runner + cache | task-runner/ + .mf/cache | | Smart build | smart-build.js — dependency-order parallel builds | | Developer experience | docs/DEVELOPER_EXPERIENCE.md, turbo.json, root tsconfig.json refs |

Enterprise architect pillars

Every federated parent workspace ships a full architect-level toolkit — docs, audit scripts, corelib modules, and runtime configs. Run the capstone audit first, then drill into individual pillars.

Capstone — start here

npm run architect-level:audit

| Artifact | Purpose | |----------|---------| | docs/ARCHITECT_LEVEL_GUIDE.md | Synthesizes all pillars — act as Senior Frontend Architect, Performance Engineer, Platform Engineer, Enterprise UI Architect, Microfrontend Specialist, DevOps-aware Frontend Engineer | | runtime-config/architect-roadmap.json | Phased roadmap: Foundation → Hardening → Scale → Platform → Optimize | | apps/corelib/src/architect/ | Capstone checklist + domain definitions |

All enterprise pillar audits

| Pillar | Audit command | Documentation | |--------|---------------|---------------| | Architect capstone | npm run architect-level:audit | docs/ARCHITECT_LEVEL_GUIDE.md | | Folder structure | npm run folder-structure:audit | docs/ENTERPRISE_FOLDER_STRUCTURE.md | | React architecture | npm run react:architecture-audit | docs/REACT_ARCHITECTURE.md | | Security hardening | npm run security:hardening-audit | docs/FRONTEND_SECURITY.md | | Developer experience | npm run dx:audit | docs/DEVELOPER_EXPERIENCE.md | | Observability | npm run observability:audit | docs/OBSERVABILITY.md | | Accessibility (WCAG) | npm run a11y:audit | docs/ACCESSIBILITY.md | | CI/CD + release | npm run cicd:audit | docs/CICD_RELEASE_ENGINEERING.md | | Scalability | npm run scalability:audit | docs/ENTERPRISE_SCALABILITY.md | | Failure recovery | npm run failure-recovery:audit | docs/FAILURE_RECOVERY.md | | Platform health | npm run mf:doctor | docs/ENTERPRISE_ARCHITECTURE.md | | Federation contracts | npm run federation:verify | apps/corelib/src/federation/ |

npm run mf:doctor prints reminders for every pillar audit after scaffold.

Pillar summaries

1. Security hardening

XSS prevention, CSP, secure token handling, refresh strategy (--auth), cookie flags, dependency audit, supply chain, federation remote trust, runtime script injection prevention.

• Corelib: src/security/frontendSecurityAudit.ts, src/federation/remoteTrust.ts, src/auth/refreshTokenStrategy.ts
• Config: hardened CSP in src/production/csp.ts
• Scripts: npm run security:hardening-audit, npm run security:audit

2. Developer experience (DX)

Smart parallel builds, incremental cache, live reload (SSE), affected detection, project graph.

• Root: smart-build.js (topo-sort + parallel waves), live-reload.js (port 35729), turbo.json
• Scripts: npm run local:fast, node smart-build.js localdev --skip-unchanged, npm run dx:audit
• CLI: mf cache invalidate, mf affected build

3. Observability (--monitoring for full stack)

Telemetry, distributed tracing, session replay, error tracking, user journey, performance budgets, RUM, OpenTelemetry.

• Corelib: src/monitoring/* (frontendTelemetry, distributedTracing, sessionReplay, errorTracking, userJourney, performanceBudgets, rum, opentelemetry)
• Config: runtime-config/observability.config.json
• Bootstrap: bootstrapObservability() via warmupCorelibShell() when --monitoring
• Scripts: npm run observability:audit

4. Accessibility (WCAG)

Focus management, live announcer, contrast checks, skip links, landmarks, eslint-plugin-jsx-a11y.

• Corelib: src/accessibility/focusManagement.ts, liveAnnouncer.ts, contrastCheck.ts
• Host: skip link, #main-content, LiveAnnouncerRegion, :focus-visible CSS
• Scripts: npm run a11y:audit

5. CI/CD + release engineering

Parallel CI builds, incremental deploy, federation rollout order, canary, rollback, feature-flag rollouts.

• Workflows: mf-platform-ci.yml, mf-affected-deploy.yml, mf-canary-deploy.yml, mf-rollback.yml
• Corelib: src/release/ (deploy strategy, federation rollout, rollback)
• Scripts: npm run cicd:audit, npm run release:plan, node scripts/release-deploy.js plan

6. Enterprise scalability

100k+ users, multi-tenant, CDN edge, runtime remote discovery, asset distribution, federation scaling, independent deployments.

• Corelib: src/scalability/ (multiTenant, cdnEdge, remoteDiscovery, assetDistribution, federationScaling)
• Config: runtime-config/scaling.config.json
• Scripts: npm run scalability:audit, npm run mf:graph

7. Production failure recovery

Remote fallbacks, offline strategy, retry, circuit breakers, graceful degradation, runtime remote failure handling.

• Corelib: src/resilience/ (circuitBreaker, retryPolicy, offlineStrategy, remoteFailureHandler, gracefulDegradation)
• UI: FederationFallback + RemoteRouteBoundary (emits mf:remote-failure events)
• Config: runtime-config/resilience.config.json
• Federation expose: corelib/resilience — loadRemoteWithResilience(), installRemoteFailureListener()
• Scripts: npm run failure-recovery:audit

8. Enterprise folder structure

Domain-driven frontend, feature modules, shared packages, federation boundaries, dependency isolation, plugin architecture.

• Corelib: src/structure/ (domainMap, boundaryRules, featureModules, dependencyIsolation, pluginArchitecture)
• Config: runtime-config/structure.config.json — bounded context → remote map
• Governance: governance/module-boundaries.json, mf.json tags
• Scripts: npm run folder-structure:audit

9. React architecture

State colocation, context splitting, server vs client state, feature-based layout, atomic design, smart/dumb components, Suspense/error boundaries, concurrent rendering.

• Corelib: src/architecture/reactArchitectureAudit.ts
• Scripts: npm run react:architecture-audit

10. Architect-level guide (capstone)

Enterprise-grade architecture, production optimization, scalability, security, maintainability, developer productivity, deployment strategy, observability strategy, future scalability roadmap.

• Roles: Senior Frontend Architect, Performance Engineer, Platform Engineer, Enterprise UI Architect, Microfrontend Specialist, DevOps-aware Frontend Engineer
• Roadmap: runtime-config/architect-roadmap.json — 5 phases with milestones
• Scripts: npm run architect-level:audit

Runtime configs (generated)

runtime-config/
├── remote-manifest.json      # Remote entry URLs + versions
├── tenant-config.js          # Multi-tenant SaaS
├── observability.config.json # Telemetry, RUM, OTel settings
├── scaling.config.json       # 100k+ user targets, CDN, federation scaling
├── resilience.config.json    # Retry, circuit breaker, offline policy
├── structure.config.json     # Domain → remote bounded context map
├── architect-roadmap.json    # Foundation → Optimize phase tracker
├── deployment.config.json    # Rollout strategy (release engineering)
└── feature-flags.js          # Runtime feature toggles

Pre-production checklist

npm run architect-level:audit    # capstone — verifies all pillar docs/scripts
npm run mf:doctor                # workspace health + pillar reminders
npm run federation:verify        # remoteEntry health
npm run folder-structure:audit   # DDD layout + import boundaries
npm run security:hardening-audit # CSP, remote trust, auth
npm run failure-recovery:audit   # circuit breakers + fallbacks
npm run cicd:audit               # CI/CD + canary + rollback workflows
npm run build                    # production build all apps

Generated monorepo structure

my-platform/
├── infrastructure/                  # Auto-generated nginx, apache, docker, k8s, ssl
│   ├── nginx/nginx.conf
│   ├── apache/httpd.conf
│   ├── compose/docker-compose.yml
│   ├── kubernetes/ingress.yaml
│   └── scripts/generate-routing.js
├── mf.json                          # Workspace project registry, tags, and federation config
├── apps/
│   ├── main/                        # Host shell (port 3000)
│   ├── billing/                     # Child remote (your --children names)
│   ├── orders/
│   └── corelib/                     # Shared federated library (--shared name)
├── packages/
│   ├── shared-ui/
│   ├── shared-auth/
│   ├── shared-utils/
│   ├── shared-config/
│   ├── shared-hooks/
│   ├── shared-services/
│   ├── shared-security/
│   ├── sdk-core/
│   ├── api-client/
│   ├── query-client/
│   ├── websocket-sdk/
│   └── auth-sdk/                    # with --auth
├── tools/
│   ├── mf-cli/                      # mf CLI (generate, graph, affected, …)
│   └── project-graph/
├── task-runner/
├── plugins/
├── devtools/
├── runtime-config/
│   ├── remote-manifest.json
│   ├── observability.config.json
│   ├── scaling.config.json
│   ├── resilience.config.json
│   ├── structure.config.json
│   └── architect-roadmap.json
├── templates/
├── ai/
├── governance/
├── k8s/helm/mf-platform/
├── docs/
│   ├── ENTERPRISE_ARCHITECTURE.md
│   ├── ARCHITECT_LEVEL_GUIDE.md       # capstone architect guide
│   ├── ENTERPRISE_FOLDER_STRUCTURE.md
│   ├── REACT_ARCHITECTURE.md
│   ├── FRONTEND_SECURITY.md
│   ├── DEVELOPER_EXPERIENCE.md
│   ├── OBSERVABILITY.md
│   ├── ACCESSIBILITY.md
│   ├── CICD_RELEASE_ENGINEERING.md
│   ├── ENTERPRISE_SCALABILITY.md
│   ├── FAILURE_RECOVERY.md
│   └── PLATFORM_ARCHITECTURE.md
├── scripts/
│   ├── architect-level-audit.js
│   ├── folder-structure-audit.js
│   ├── react-architecture-audit.js
│   ├── security-hardening-audit.js
│   ├── dx-audit.js
│   ├── observability-audit.js
│   ├── a11y-audit.js
│   ├── cicd-audit.js
│   ├── scalability-audit.js
│   ├── failure-recovery-audit.js
│   └── release-deploy.js
├── .github/workflows/
│   ├── mf-platform-ci.yml
│   ├── mf-affected-deploy.yml
│   ├── mf-canary-deploy.yml
│   └── mf-rollback.yml
├── docker-compose.yml
├── .env, .env.dev, .env.staging, .env.uat, .env.prod
├── live-reload.js
├── smart-build.js
└── package.json                     # npm run local, npm run billing, …

Infrastructure & deployment (parent workspaces)

Every parent + federation workspace auto-generates infrastructure/ with:

| Path | Contents | |------|----------| | infrastructure/nginx/ | nginx.conf, federation routing, upstreams, WebSocket, per-env server blocks | | infrastructure/apache/ | httpd.conf, federation vhosts, WebSocket proxy | | infrastructure/docker/ | Gateway Dockerfile + per-app production Dockerfiles | | infrastructure/compose/ | docker-compose.yml + DEV/QA/UAT/PROD overlays | | infrastructure/kubernetes/ | deployment.yaml, ingress.yaml, services, HPA | | infrastructure/ssl/ | Self-signed + Certbot scripts, env cert folders | | infrastructure/scripts/ | Auto-routing, remote detection, deploy scripts |

Deployment modes:

# Container — nginx gateway + all MFE containers
npm run infra:gateway
npm run infra:deploy:dev
npm run infra:deploy:qa
npm run infra:deploy:uat
npm run infra:deploy:prod

# Normal server — Vite apps + bare-metal nginx upstreams
npm run dev
npm run infra:health
# use infrastructure/nginx/conf.d/upstreams-bare.conf

# Auto-detect remotes → routing manifest
npm run infra:detect
npm run infra:routing

Features: federation-aware reverse proxy, dynamic remote routing (/remotes/<name>/), SSL-ready configs, load balancing, health checks, WebSocket for control plane, runtime env injection per environment.

MF Platform CLI (inside generated projects)

After scaffolding, use the mf CLI inside your monorepo:

npm run mf -- <command>
# or
node tools/mf-cli/bin/mf.js <command>

Generators

| Command | Description | |---------|-------------| | mf generate app <name> | New MFE remote (create-app, create-mfe) | | mf generate lib <name> | Shared library package (create-lib) | | mf generate plugin <name> | Platform plugin (create-plugin) | | mf generate page <name> [app] | Route page (create-page) | | mf generate layout <name> | Layout component (create-layout) | | mf generate feature <name> | Feature module (create-feature) | | mf generate component <name> | UI component in shared-ui | | mf generate dashboard <name> | Dashboard module (create-dashboard) | | mf generate workflow <name> | Workflow module (create-workflow) | | mf generate api-sdk <name> | API SDK package (create-api-sdk) | | mf generate table <name> | AppTable scaffold (create-table) | | mf generate form <name> | Form engine scaffold (create-form) | | mf generate auth <name> | Auth provider scaffold (create-auth) | | mf generate theme <name> | Theme preset (create-theme) |

Orchestration

| Command | Description | |---------|-------------| | mf graph | Export dependency graph to tools/project-graph/graph-ui/graph.json | | mf graph --federation | Federation-only graph | | mf affected build | Git-aware incremental build | | mf affected test | Run tests only on affected projects | | mf affected lint | Lint only affected projects | | mf affected <target> --base=main | Custom git base branch | | mf run <project> [target] | Run target on one project | | mf build | Build all projects (parallel) | | mf test | Test all projects | | mf lint | Lint all projects | | mf serve | Delegates to npm run local | | mf release [patch\|minor\|major] | Release workflow |

Federation & health

| Command | Description | |---------|-------------| | mf federation doctor | Check host/remotes/shared lib wiring | | mf federation graph | Export federation dependency graph | | mf federation sync | Sync remote manifests from mf.json | | mf doctor | Workspace health (circular deps, boundaries, mf.json, architecture protection, pillar audit reminders) | | npm run federation:verify | HEAD-check remoteEntry URLs (MF_REMOTES env) |

Architecture protection (mss-mf)

Enterprise parent workspaces include .mss-protected.json — a guardrail config that prevents accidental deletion or modification of federation OS core infrastructure.

| Tier | Examples | CLI behavior | |------|----------|--------------| | Hard protected | runtime/, tools/mf-cli/, governance/, federation packages | Cannot delete | | Soft protected | apps/main, apps/corelib, plugins/ | Requires --force | | Non-critical apps | Child remotes under apps/* | Requires --force |

| Command | Description | |---------|-------------| | mss-mf delete <path> | Delete path (blocked if protected) | | mss-mf delete runtime | ❌ Cannot delete protected folder: runtime | | mss-mf delete apps/billing --force | Remove non-critical child remote | | mss-mf protect validate | Workspace structure + staged-change validation | | mss-mf protect snapshot | Capture recovery snapshot in .mss/snapshots/ | | mss-mf protect recover | Restore missing paths from latest snapshot | | mss-mf protect list | List hard/soft protected paths and readonly packages | | mss-mf protect status | Quick integrity summary |

Git hooks (when .mss-protected.json exists):

• pre-commit — blocks staged deletion/modification of protected paths
• pre-push — structure validation + dependency integrity

Emergency architect override: MSS_PROTECT_OVERRIDE=1 mss-mf delete <path> --architect-override

npm script shortcuts (generated)

"mf": "node tools/mf-cli/bin/mf.js",
"mf:graph": "node tools/mf-cli/bin/mf.js graph",
"mf:affected": "node tools/mf-cli/bin/mf.js affected build",
"mf:doctor": "node tools/mf-cli/bin/mf.js doctor",
"mf:federation": "node tools/mf-cli/bin/mf.js federation doctor",
"mss-mf": "node tools/mf-cli/bin/mf.js",
"mf:protect": "node tools/mf-cli/bin/mf.js protect validate",
"mf:protect:snapshot": "node tools/mf-cli/bin/mf.js protect snapshot",
"mf:protect:recover": "node tools/mf-cli/bin/mf.js protect recover"

Using corelib (shared library)

corelib (or your --shared name) is a Module Federation remote that exposes shared UI, config, and RBAC. Child remotes and the host import it at runtime.

Host (apps/main) — single HostShell expose

The host uses a CSS-only boot shell (~137 KB gzip) and loads the MUI/RBAC shell from corelib in one federation request via corelib/HostShell:

const HostShell = React.lazy(() => import("corelib/HostShell"));

export default function App() {
  return (
    <React.Suspense fallback={<ShellSkeleton />}>
      <HostShell navLinks={<HostNavLinks />} onItemPrefetch={prefetchRemotePath}>
        <AppRouter />
      </HostShell>
    </React.Suspense>
  );
}

main.tsx bootstraps runtime remotes (manifest prefetch) before render:

await bootstrapRuntimeRemotes();
warmupCorelibShell();

Child remote — RemoteAppShell (skips duplicate providers)

When embedded in the host, RoleProvider is not mounted twice. Standalone dev still wraps with RoleProvider:

import RemoteAppShell from "corelib/RemoteAppShell";

export default function App() {
  return (
    <RemoteAppShell>
      <AppRouter />
    </RemoteAppShell>
  );
}

Available federation exports (corelib)

| Export | Purpose | |--------|---------| | ./App | Standalone corelib demo app | | ./HostShell | Host shell bundle — AppConfig, RoleProvider, Navbar, Sidebar, CommandPalette | | ./RemoteAppShell | Embedded remote wrapper — skips RoleProvider when host is active | | ./AppConfigProvider | Theme + MUI provider + CSS variables | | ./useAppConfig | Combined hook (backward compatible) | | ./AppNavbar, ./AppSidebar, ./ThemeToggle | Shell UI (also inside HostShell) | | ./EnterpriseSidebarNav | Role-filtered sidebar menu + route prefetch hook | | ./RouteGuard, ./RoleProvider, ./usePermission | RBAC | | ./CommandPalette | Ctrl+K palette (returns null when closed) | | ./DashboardLayout | Dashboard shell layout | | ./PermissionProvider, ./FederationFallback | Permissions + error UI | | ./resilience | Circuit breakers, retry, offline, loadRemoteWithResilience(), installRemoteFailureListener() | | ./ProfilerGate | Dev-only React Profiler wrapper | | ./designTokens | Token registry |

TypeScript — add declarations in host/child

Generated projects include src/types/federation-remotes.d.ts for remote module names. After adding new exposes, extend that file:

declare module "corelib/MyNewComponent" {
  const Component: React.ComponentType;
  export default Component;
}

Enterprise design system & theming

apps/corelib/src/
├── tokens/                 # colors, spacing, typography, shadows, …
├── config/
│   ├── AppConfigProvider.tsx
│   ├── themeGenerator.ts   # MUI theme from tokens
│   ├── resolveTheme.ts     # contrast-safe shell colors
│   ├── colorUtils.ts       # WCAG contrast helpers
│   └── defaultConfig.ts    # enterprise-light / enterprise-dark presets
├── layouts/
├── permissions/
├── shared-ui/
└── …

Runtime theme in your components

Split config hooks reduce re-renders (prefer these over the combined hook in hot paths):

import {
  useAppConfigPick,
  useAppConfigActions,
  useAppTheme,
  useAppConfig, // backward compatible
} from "corelib/useAppConfig";

function MyWidget() {
  const { tenantId } = useAppConfigPick("tenantId");
  const { toggleColorMode } = useAppConfigActions();
  const { palette } = useAppTheme();
  return (
    <div style={{ color: palette.textPrimary, background: palette.surface }}>
      Tenant: {tenantId}
    </div>
  );
}

Config architecture: AppConfigProvider uses three contexts — State (config object), Actions (stable mutations), Theme (resolved palette). Sidebar/nav components use CSS variables (--ds-*) where possible.

Features:

• Enterprise-light / enterprise-dark presets + Azure, Atlassian, Linear-dark, etc.
• Light/dark toggle with full palette sync (background + text together)
• Contrast-safe navbar/sidebar text (no dark-on-dark)
• CSS variables (--ds-*) applied to document.documentElement
• Responsive collapsible sidebar (flex layout, no overlap)
• MUI component overrides from design tokens

Clear cached theme (after upgrades or bad colors):

localStorage.removeItem('mf-enterprise-config')

Then hard-refresh the browser.

Module Federation

Architecture (tiered host / shared / remotes)

┌──────────────────────────────────────────────────────────────┐
│  apps/main (host) :3000  — CSS shell ~137 KB gzip             │
│  ├── eager shared: react, react-dom only                      │
│  ├── lazy shared: react-router-dom, @tanstack/react-query     │
│  ├── corelib/HostShell (single federation expose)             │
│  └── feature remotes on /admin-app/*, /analytics-app/*, …     │
└──────────────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────┐     ┌─────────────────────────────────────┐
│  apps/corelib    │     │  apps/<child> (feature remotes)      │
│  MUI, RBAC, DS   │◀────│  RemoteAppShell when embedded        │
│  :3006           │     │  standard / control-plane share tiers│
└──────────────────┘     └─────────────────────────────────────┘

Shared policy lives in packages/shared-config/src/federationShared.ts:

| Tier | Packages | Host | corelib / remotes | |------|----------|------|-------------------| | 0 | react, react-dom | eager singleton | singleton | | 1 | react-router-dom, @tanstack/react-query | lazy shared | shared | | 2 | MUI, Emotion | not on host | corelib + remotes | | 3 | zustand, @xyflow/react, … | per-app only | control-plane remotes |

Production: strictVersion: true is enabled automatically for prod, staging, and uat builds (or set VITE_MF_STRICT_SHARED=1).

Remote URLs: env-driven via packages/shared-config/src/federationRemotes.ts (VITE_<APP>_REMOTE_ENTRY). Local default:

http://localhost:<port>/assets/remoteEntry.js

After changing federation config:

npm run build:local    # rebuild ALL apps
npm run local          # restart

Use hoisted install (generated .npmrc: install-strategy=hoisted).

Performance & federation architecture

Enterprise parent workspaces (and the reference my-platform/ in this repo) include the optimizations below. Generated scaffolds follow the same patterns via apps/vite.config.base.ts, federationShared.ts, and corelib shell modules.

Bundle size & Vite

| Feature | Location | Purpose | |---------|----------|---------| | Shared Vite base | apps/vite.config.base.ts | mfSafeManualChunks, resolve.dedupe, gzip/brotli in prod | | Host thin shell | apps/main | No MUI/Emotion on host boot path | | Lazy DataGrid | corelib/AppDataGrid | @mui/x-data-grid dynamic import | | Route prefetch | main/src/routes/remoteLoaders.ts | Hover/focus prefetch before navigation | | RemoteSkeleton | main/src/components/RemoteSkeleton.tsx | Non-blocking loading UI |

Run bundle analysis:

npm run analyze:bundle
# or per app: cd apps/main && npm run analyze

Runtime remote loading

| Feature | Location | Purpose | |---------|----------|---------| | Runtime manifest | runtime-config/remote-manifest.json | CDN/prod remote entry map | | Bootstrap | main/src/module-federation/bootstrapRemotes.ts | Fetch manifest, preconnect, prefetch remoteEntry | | Dev manifest server | apps/main/vite.config.ts | Serves /runtime-config/* in local dev | | Idle warm-up | warmupCorelibShell() in main.tsx | Idle-import corelib/HostShell | | Error boundaries | main/src/components/RemoteRouteBoundary.tsx | Per-remote fallback + retry | | nginx caching | infrastructure/nginx/conf.d/federation.conf | Short cache on remoteEntry, manifest at /runtime-config/ |

Env override for manifest URL:

VITE_REMOTE_MANIFEST_URL=/runtime-config/remote-manifest.json

Re-render performance (corelib)

• Split contexts: useAppConfigState, useAppConfigActions, useAppTheme, useAppConfigPick
• Memo shell: EnterpriseSidebarNav, AppTable, AppDataGrid, host nav links
• Command palette: no render when closed
• Control plane dashboard: tab-isolated data (health WebSocket only in Monitor tab)
• Dev profiling: ProfilerGate wraps host navbar, sidebar, and router regions

Host / remote communication

| Channel | Mechanism | |---------|-----------| | Navigation | Host owns BrowserRouter; remotes use nested <Routes> | | Server state | Singleton @my-platform/query-client at host | | Theme / RBAC | corelib contexts via HostShell (single provider tree) | | Cross-MFE events | Extend with event bus / shared query keys as needed |

Reference platform

The my-platform/ directory in this repository is a fully wired reference implementation with all of the above. See my-platform/README.md for app ports, scripts, and platform-specific notes.

SDK packages

| Package | Purpose | |---------|---------| | @<project>/sdk-core | Trace IDs, error normalization | | @<project>/api-client | Axios wrapper, interceptors, API versioning | | @<project>/auth-sdk | Token refresh helpers (--auth) | | @<project>/query-client | Query key utilities | | @<project>/websocket-sdk | Reconnecting WebSocket |

Import from workspace packages in apps via file:../../packages/<name> dependencies.

Task runner & build cache

task-runner/
├── orchestrator.js      # Parallel execution, dependency-aware runs
├── cache-engine.js      # Hash-based local cache
├── executors/           # build, test, lint
└── pipelines/           # default: build → test → lint

• Cache directory: .mf/cache/ (gitignored)
• Cache key: hash of project + target + inputs
• CI: cache .mf/cache in pipeline for faster rebuilds

Plugins & devtools

Plugins (plugins/*-plugin/): register generators, executors, hooks (preBuild, postBuild, appCreated).

Devtools (devtools/):

• Federation inspector — inspect loaded remotes in browser
• Performance profiler — Web Vitals + route transition timing
• MFE debugger — window.__MF_DEBUG__ remote load tracing
• Theme inspector — CSS variable viewer
• Dependency viewer — CLI dependency tree

Runtime configuration

runtime-config/
├── remote-manifest.json      # Remote entry URLs + versions (host bootstrap)
├── tenant-config.js          # Multi-tenant SaaS configs
├── observability.config.json # Telemetry, RUM, OTel settings
├── scaling.config.json       # Scalability targets, CDN, multi-tenant
├── resilience.config.json    # Retry, circuit breaker, offline policy
├── structure.config.json     # Domain → remote bounded context map
├── architect-roadmap.json    # Foundation → Optimize phase tracker
├── deployment.config.json    # Rollout strategy (release engineering)
├── manifest-loader.js        # CDN remote manifest fetch
├── feature-flags.js          # Runtime feature toggles
└── branding.js               # Dynamic logo/colors injection

The host loads remote-manifest.json at startup (bootstrapRuntimeRemotes) to preconnect and prefetch remoteEntry.js files. In production, nginx serves /runtime-config/ with short cache headers (max-age=30, stale-while-revalidate).

Per-remote env overrides (build time):

VITE_CORELIB_REMOTE_ENTRY=http://localhost:3006/assets/remoteEntry.js
VITE_ADMIN_APP_REMOTE_ENTRY=http://localhost:3001/assets/remoteEntry.js
# … see packages/shared-config/src/federationRemotes.ts

Template marketplace

Enterprise blueprints in templates/:

| Template | Domain | |----------|--------| | lims-template | Laboratory Information Management | | hms-template | Healthcare Management | | erp-template | Enterprise Resource Planning | | analytics-template | Analytics dashboards | | admin-template | Admin portal | | saas-template | Multi-tenant SaaS | | workflow-template | Workflow automation |

CI/CD & governance

GitHub Actions:

• .github/workflows/mf-platform-ci.yml — doctor, affected lint/test/build, security audit, pillar audits
• .github/workflows/mf-affected-deploy.yml — affected deploy on main
• .github/workflows/mf-canary-deploy.yml — canary promotion with health checks
• .github/workflows/mf-rollback.yml — federation rollback workflow

Also generated:

• .gitlab-ci.yml
• k8s/helm/mf-platform/ — Helm chart for host + remotes
• governance/module-boundaries.json — import boundary rules
• governance/CODEOWNERS — team ownership
• governance/dependency-rules.json — license governance

Deploy strategy:

1. mf affected build on merge
2. Upload apps/*/dist to CDN
3. Host loads remote manifests at runtime
4. Helm/Kubernetes for containerized host + ingress

Code quality

Generated parent workspaces include:

| Script | Purpose | |--------|---------| | npm run lint / lint:fix | ESLint across apps + packages | | npm run format / format:check | Prettier | | npm run stylelint | CSS / SCSS | | npm run type-check | TypeScript every workspace app | | npm run test / test:watch / test:ci | Vitest + coverage | | npm run cleanup | lint:fix → imports → type-check | | npm run analyze:bundle | Rollup visualizer per app | | npm run security:audit | npm audit | | npm run security:hardening-audit | Frontend security pillar audit | | npm run architect-level:audit | Capstone — verifies all enterprise pillar docs/scripts | | npm run folder-structure:audit | DDD layout, federation boundaries, dependency isolation | | npm run react:architecture-audit | React architecture pillars | | npm run dx:audit | Developer experience maturity | | npm run observability:audit | Telemetry, RUM, tracing, error tracking | | npm run a11y:audit | WCAG accessibility checklist | | npm run cicd:audit | CI/CD + release engineering | | npm run scalability:audit | 100k+ users, CDN, multi-tenant | | npm run failure-recovery:audit | Circuit breakers, retry, fallbacks | | npm run production:hygiene | Fail on console/debugger in sources |

Husky: lint-staged + type-check + tests on pre-commit; lint + tests on pre-push. Commitlint for Conventional Commits.

Root workspace scripts

Full platform

| Script | Purpose | |--------|---------| | local | Main dev command — build:local + watch + preview + live-reload (all apps) | | local:fast | Smart build (skip unchanged) + watch + preview + live-reload | | build:local | node smart-build.js localdev — parallel dependency-order build | | dev | print-env + parallel Vite dev servers | | dev:watch | Same as local | | dev:fast | dev build once + preview + live-reload | | dev:safe | production build + preview only | | build | Production build (runs cleanup first) | | build:local | localdev mode build for all apps | | build:dev / build:staging / build:uat | Environment-specific builds | | watch:<app> | Vite watch for one app | | preview:<app> | Vite preview for one app | | release / release:minor / release:major | Version bump + build | | federation:verify | Remote entry health check | | architect-level:audit | Capstone enterprise platform audit | | folder-structure:audit | Domain-driven folder structure audit | | react:architecture-audit | React architecture audit | | security:hardening-audit | Frontend security hardening audit | | dx:audit | Developer experience audit | | observability:audit | Observability stack audit | | a11y:audit | Accessibility (WCAG) audit | | cicd:audit | CI/CD + release engineering audit | | scalability:audit | Enterprise scalability audit | | failure-recovery:audit | Production failure recovery audit | | release:plan | Deployment rollout plan | | mf, mf:graph, mf:affected, mf:doctor, mss-mf, mf:protect | Platform CLI + architecture protection | | infra:gateway, infra:deploy:{dev,qa,uat,prod}, infra:detect, infra:routing, infra:health | Auto-generated reverse proxy + deployment (parent workspaces) | | control-plane, federation-os:infra | Control-plane API + Federation OS observability stack |

Per-module dev (dynamic — one script per --children name)

| Script | Apps included | |--------|----------------| | npm run billing | main + corelib + billing | | npm run orders | main + corelib + orders | | npm run <child> | main + corelib + <child> | | npm run corelib | main + corelib |

Supporting scripts (auto-generated):

• build:local:<child>-only — build subset for that scenario
• watch:local:<child>-only — watch subset
• watch:local:<app> / preview:local:<app> — per-app watch/preview in localdev mode

Docker & deployment

• Dockerfile per app (Node 22 Alpine, healthcheck)
• docker-compose.yml — all apps on mapped ports
• .npmrc — install-strategy=hoisted for federation shared deps

Per-app environment:

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

Root .env lists all app ports and remote URLs (.env.dev, .env.staging, .env.uat, .env.prod variants).

docker compose up --build

For container-to-container federation, replace localhost remote URLs with Docker service hostnames.

Documentation in generated projects

| File | Contents | |------|----------| | README.md | Ports, quick start, Docker, quality scripts | | docs/ARCHITECT_LEVEL_GUIDE.md | Capstone — all architect roles, 9 deliverables, master audit suite, roadmap | | docs/ENTERPRISE_ARCHITECTURE.md | Design system, RBAC, federation, SDK, deployment, all pillar links | | docs/ENTERPRISE_FOLDER_STRUCTURE.md | DDD, feature modules, packages, federation boundaries, plugins | | docs/REACT_ARCHITECTURE.md | State, context, Suspense, error boundaries, feature layout | | docs/FRONTEND_SECURITY.md | XSS, CSP, remote trust, auth, supply chain | | docs/DEVELOPER_EXPERIENCE.md | Smart build, live reload, affected builds, caching | | docs/OBSERVABILITY.md | Telemetry, tracing, RUM, session replay, OTel | | docs/ACCESSIBILITY.md | WCAG, keyboard, ARIA, focus management | | docs/CICD_RELEASE_ENGINEERING.md | Parallel CI, canary, rollback, federation rollout | | docs/ENTERPRISE_SCALABILITY.md | Multi-tenant, CDN, remote discovery, 100k+ users | | docs/FAILURE_RECOVERY.md | Circuit breakers, retry, offline, graceful degradation | | docs/RUNTIME_PERFORMANCE.md | Runtime profiler (--monitoring) | | docs/PLATFORM_ARCHITECTURE.md | MF CLI, graph, cache, plugins, CI/CD | | docs/ARCHITECTURE_PROTECTION.md | Protected structure, .mss-protected.json | | docs/CONTROL_PLANE.md | Workflow designer, monitor, registry (with --control-plane) | | docs/FEDERATION_OS.md | Full Federation OS architecture (with --federation-os) | | mf.json | Project registry, tags, federation config | | templates/README.md | Template marketplace usage | | ai/README.md | AI layer integration guide |

Node version

Generated projects use Vite 7. Requires:

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

Node 18 will fail on Vite 7 commands.

Troubleshooting

| Issue | Fix | |-------|-----| | "local" cannot be used as a mode name | Generator uses localdev mode in Vite scripts | | useRoutes() may be used only in context of a <Router> | Share react-router-dom as federation singleton | | MUI/CSS not applied across remotes | Share @mui/material, @emotion/* as singletons | | Cannot find module 'billing/App' | Add federation .d.ts declarations in host | | Task not found: live-reload | Root "live-reload": "node live-reload.js" | | Vite binary missing after install | Clean reinstall (see below) | | npm install very slow (~2 min+) | Use --lite for faster scaffold; exclude project from antivirus scan; second install uses npm cache | | npm run local fails on api-client build | Update to latest CLI (smart-build skips source-only packages) or patch smart-build.js | | Sidebar overlaps main content | Use generated flex sidebar in corelib | | Text invisible on dark header/sidebar | Clear localStorage key mf-enterprise-config; hard refresh | | provider support react(undefined) / useState null | Rebuild all apps after federation config change; host uses exact version: "19.0.0", remotes use requiredVersion: "^19.0.0" | | ENOENT @mui/icons-material in host | Hoisted install + federation shared versions on host | | Build error Could not resolve enterpriseGlobalCss | Update to latest @multisystemsuite/create-mf-app |

Clean reinstall:

rmdir /s /q node_modules
del package-lock.json
npm cache verify
npm install
npm run build:local

Reset theme cache:

localStorage.removeItem('mf-enterprise-config')

Develop & publish this package

For contributors working on the CLI itself (this repo):

git clone https://github.com/Abhishek2122/create-mf-app
cd create-mf-app
npm install
npm run build          # tsup → dist/ + copy docs/ → dist/docs/
npm run dev            # run dist/index.js locally (pass args after --)

# test generator changes locally (uses dist/, not published npm)
node dist/index.js my-platform --control-plane -y
node dist/index.js my-platform --type=parent --children=admin,billing --shared=corelib -y
node dist/index.js my-federation-platform --federation-os -y
node dist/index.js test-app --type=child --port=3001 --template=tsx
node dist/index.js add-child analytics --cwd=./mf-structure-test --port=4205 -y

# patch in-repo test workspaces (mf-test-jsx, my-platform-cp) after pillar changes
node scripts/patch-architect-level-test-repos.js
node scripts/patch-folder-structure-test-repos.js
node scripts/patch-failure-recovery-test-repos.js
node scripts/patch-scalability-test-repos.js
node scripts/patch-cicd-test-repos.js
node scripts/patch-a11y-test-repos.js
node scripts/patch-observability-test-repos.js
node scripts/patch-security-test-repos.js
node scripts/patch-dx-test-repos.js

# optional: link CLI globally
npm link
create-mf-app my-platform --control-plane -y

# dry-run npm pack contents
npm run pack:check

# publish to npm (maintainers)
npm run rebuild
npm publish --access public

Package name: @multisystemsuite/create-mf-app
Binary: create-mf-app
Published files: dist/ (includes dist/docs/), docs/ (README screenshots), README.md

README images: served from the published npm package via unpkg (docs/images/). After changing screenshots, run npm run rebuild, publish, then commit docs/images/ to GitHub.

Summary

| Layer | How you use it | |-------|----------------| | Scaffold | npx create-mf-app <name> --type=parent --children=… --shared=corelib | | Control plane preset | --control-plane → workflow designer, monitor, registry, API | | Federation OS preset | --federation-os → full runtime, governance, observability stack | | Daily dev | npm run local (all apps) or npm run billing (one module) | | Shared UI / theme | Import from corelib/* federation exposes | | New remote | npx create-mf-app add-child <name> --cwd=./my-platform or npm run mf -- generate app <name> | | Enterprise modules | Flags: --auth, --charts, --i18n, … | | Architect pillars | 10 enterprise audits — start with npm run architect-level:audit | | Monorepo platform | mf graph, mf affected build, mf doctor | | Architecture protection | .mss-protected.json + mss-mf protect / delete guards | | Infrastructure | Auto infrastructure/ — nginx, docker, k8s, SSL, env deploy scripts | | Federation | Host :3000 loads remotes; shared React/MUI singletons | | Design system | AppConfigProvider + tokens + runtime theme toggle | | Deploy | npm run build → CDN dist + infra:deploy:* / Helm / Docker | | Local CLI dev | npm run build then node dist/index.js <name> [flags] |

Module Federation + Vite — React-first, enterprise-grade, plugin-driven.