🚀 Centralized Dependency Orchestrateur for Micro-Frontends : guide to migration

📋 Part 1: Integration in Your MFE Project

Quick Setup (3 Steps)

Clean your package.json and configure the library:

{
  "name": "your-mfe-project",
  "version": "1.0.0",
  "scripts": {
    "postinstall": "node ./node_modules/@houssem__/angular-base/dist/sync-all-deps.js --mf-header"
  },
  "dependencies": {
    "@houssem__/angular-base": "^5.5.16"
  },
  "devDependencies": {}
}

Note: Replace --mf-header with your actual MFE project name from the supported list.

Then run:

npm install

🏗️ Part 2: Understanding How It Works

Execution Flow

npm install
    ↓
postinstall script runs
    ↓
sync-all-deps.js --mf-your-project
    ↓
1. Validates project name against registry
    ↓
2. Loads runtime dependencies config: mfes-libs/mf-your-project.ts
    ↓
3. Loads dev dependencies config: mfes-dev-libs/mf-your-project.ts
    ↓
4. Queues all packages from both configs
    ↓
5. Writes ALL packages to your package.json in one operation
    ↓
6. Runs a single npm install command
    ↓
✅ Dependencies synchronized!

Library File Structure

src/
├── sync-all-deps.ts                    ← Main orchestrator (CLI entry point)
│
├── types/
│   └── mfe-projects.ts                 ← PROJECT REGISTRY (10 projects)
│
├── dependencies/                       ← RUNTIME DEPENDENCIES
│   ├── versions/
│   │   └── mfes-versions.ts           ← ⚙️ VERSION DEFINITIONS (edit versions here)
│   │
│   ├── categories/
│   │   └── libs-categories.ts         ← AVAILABLE PACKAGES (organized by category)
│   │
│   ├── mfes-libs/                     ← PER-PROJECT CONFIGS
│   │   ├── mf-header.ts               ← 📝 EDIT: Add/remove packages for mf-header
│   │   ├── mf-footer.ts               ← 📝 EDIT: Add/remove packages for mf-footer
│   │   └── ...                        ← 📝 One file per MFE project (10 files)
│   │
│   └── runtime-sync.ts                ← Runtime orchestrator (called by main)
│             
└── dev-dependencies/                  ← DEV DEPENDENCIES (same structure)
    ├── versions/
    │   └── dev-versions.ts            ← ⚙️ DEV VERSION DEFINITIONS
    │
    ├── categories/
    │   └── dev-libs-categories.ts     ← AVAILABLE DEV TOOLS (organized by category)
    │
    ├── mfes-dev-libs/                 ← PER-PROJECT DEV CONFIGS
    │   ├── mf-header.ts               ← 📝 EDIT: Add/remove dev tools for mf-header
    │   ├── mf-footer.ts               ← 📝 EDIT: Add/remove dev tools for mf-footer
    │   └── ...                        ← 📝 One file per MFE project (10 files)
    │
    └── dev-sync.ts                    ← Dev orchestrator (called by main)

🔧 Part 3 : Your Project is Already Registered => Modifying Dependencies in the Library

Supported projects:

mf-footer, mf-header, mf-autocomplete, mf-search, mf-recommendation,
mf-pdp, mf-add-to-cart, mf-account, mf-cms, mf-shell

If your project is in this list, you only need to edit 2 files:

1️⃣ For Runtime Dependencies

Edit: src/dependencies/mfes-libs/mf-your-project.ts

import { MFEConfig } from '../../types/interfaces';
import { LIBS } from '../categories/libs-categories';

export const MF_YOURPROJECT_LIBS: MFEConfig = {
    // Spread common Angular packages (Core, Common, Forms, etc.)
    ...LIBS.COMMON,
    
    // Add specific packages from categories
    PLATFORM_SERVER: LIBS.ANGULAR.PLATFORM_SERVER,
    SERVICE_WORKER: LIBS.ANGULAR.SERVICE_WORKER,
    BOOTSTRAP: LIBS.UI_DESIGN.BOOTSTRAP,
    
    // Add more as needed from categories/libs-categories.ts
};

2️⃣ For Dev Dependencies

Edit: src/dev-dependencies/mfes-dev-libs/mf-your-project.ts

import { MFEConfig } from '../../types/interfaces';
import { DEV_LIBS } from '../categories/dev-libs-categories';

export const MF_YOURPROJECT_DEV_LIBS: MFEConfig = {
    // Spread common dev tools (Build, TypeScript, Testing, Linting)
    ...DEV_LIBS.COMMON,
    
    // Add specific dev tools from categories
    ANGULAR_CLI: DEV_LIBS.BUILD.ANGULAR_CLI,
    TYPESCRIPT: DEV_LIBS.TYPESCRIPT.TYPESCRIPT,
    JEST: DEV_LIBS.TESTING.JEST,
    ESLINT: DEV_LIBS.LINTING.ESLINT,
    PRETTIER: DEV_LIBS.FORMATTING.PRETTIER,
    
    // Add more as needed from categories/dev-libs-categories.ts
};

Then build and publish:

npm run build
npm version patch
npm publish

⚠️ Version Management - Important!

This library contains the highest/latest approved versions for all mfes cited (10).

Before publishing a new version:

1. Check what versions will be used:

   # Look at the library's version definitions
   cat node_modules/@houssem__/angular-base/dist/dependencies/versions/mfes-versions.js

2. Compare with your current project versions:

   • Your project might have: @angular/[email protected]
   • Library might have: @angular/[email protected]
   • Result: Updating will upgrade to version 19.2.14 ⚠️

3. Before publishing to Nexus:

   • ✅ Check Angular migration guides for major version changes
   • ✅ Review breaking changes for all upgraded packages
   • ✅ Test in a development branch first
   • ✅ Update your application code if needed

4. If everything works:

   # Publish library to Nexus
   npm publish
      
   # Update your MFE project's package.json
   {
     "dependencies": {
       "@houssem__/angular-base": "^5.5.17"  // New version
     }
   }
      
   # Install and verify
   npm install

➕ Part 4: Your Project is NOT Registered => Adding a New Project to the Registry

Follow these steps to add a new MFE project:

Step 1: Register Project Name

Edit src/types/mfe-projects.ts:

export const MicroFrontends = [
    'mf-footer',
    'mf-header',
    'mf-autocomplete',
    'mf-search',
    'mf-recommendation',
    'mf-pdp',
    'mf-add-to-cart',
    'mf-account',
    'mf-cms',
    'mf-shell',
    'mf-your-new-project'  // ← Add your project here
] as const;

Step 2: Create Runtime Dependencies Config

Create src/dependencies/mfes-libs/mf-your-new-project.ts:

import { MFEConfig } from '../../types/interfaces';
import { LIBS } from '../categories/libs-categories';

export const MF_YOUR_NEW_PROJECT_LIBS: MFEConfig = {
    // Spread common Angular packages
    ...LIBS.COMMON,
    
    // Add specific packages you need
    PLATFORM_SERVER: LIBS.ANGULAR.PLATFORM_SERVER,
    BOOTSTRAP: LIBS.UI_DESIGN.BOOTSTRAP,
    // Check categories/libs-categories.ts for all available packages
};

Step 3: Create Dev Dependencies Config

Create src/dev-dependencies/mfes-dev-libs/mf-your-new-project.ts:

import { MFEConfig } from '../../types/interfaces';
import { DEV_LIBS } from '../categories/dev-libs-categories';

export const MF_YOUR_NEW_PROJECT_DEV_LIBS: MFEConfig = {
    // Spread common dev tools
    ...DEV_LIBS.COMMON,
    
    // Add specific dev tools you need
    ANGULAR_CLI: DEV_LIBS.BUILD.ANGULAR_CLI,
    JEST: DEV_LIBS.TESTING.JEST,
    // Check categories/dev-libs-categories.ts for all available tools
};

Step 4: Export Your Configs

Update src/dependencies/mfes-libs/index.ts:

export { MF_YOUR_NEW_PROJECT_LIBS } from './mf-your-new-project';

Update src/dev-dependencies/mfes-dev-libs/index.ts:

export { MF_YOUR_NEW_PROJECT_DEV_LIBS } from './mf-your-new-project';

Step 5: Build, Test, and Publish

# Build the library
npm run build

# Test your new project
node ./dist/sync-all-deps.js --mf-your-new-project

# Verify it appears in the list
node ./dist/sync-all-deps.js --list

# If everything works, publish
npm version patch
npm publish

🆕 Part 5: Adding a New Package (Not in Library)

Example: Adding ngx-translate package

If you need a package that doesn't exist in the library yet (e.g., ngx-translate):

Step 1: Add Version Definition

Edit src/dependencies/versions/mfes-versions.ts:

export const MFE_VERSIONS = {
    // ...existing versions...
    ANGULAR_CORE: '19.2.14',
    ANGULAR_COMMON: '19.2.14',
    RXJS: '7.8.1',
    BOOTSTRAP: '5.3.3',
    
    // Add your new package version
    NGX_TRANSLATE: '15.0.0',  // ← New package version
};

For dev dependencies, edit src/dev-dependencies/versions/dev-versions.ts:

export const DEV_VERSIONS = {
    // ...existing versions...
    TYPESCRIPT: '5.3.3',
    JEST: '29.7.0',
    
    // Add your new dev package version
    STORYBOOK: '7.6.0',  // ← New dev package version
};

Step 2: Add to Category

Edit src/dependencies/categories/libs-categories.ts:

export const LIBS = {
    // ...existing categories...
    
    // Create new category or add to existing one
    INTERNATIONALIZATION: {
        NGX_TRANSLATE: {
            name: '@ngx-translate/core',
            version: MFE_VERSIONS.NGX_TRANSLATE
        },
        NGX_TRANSLATE_HTTP: {
            name: '@ngx-translate/http-loader',
            version: MFE_VERSIONS.NGX_TRANSLATE
        }
    },
};

Note: Feel free to create new categories that suit your needs. Follow the same structure.

Step 3: Use in Your Project Config

Update your project config src/dependencies/mfes-libs/mf-your-project.ts:

import { MFEConfig } from '../../types/interfaces';
import { LIBS } from '../categories/libs-categories';

export const MF_YOURPROJECT_LIBS: MFEConfig = {
    ...LIBS.COMMON,
    
    // Add the new package
    NGX_TRANSLATE: LIBS.INTERNATIONALIZATION.NGX_TRANSLATE,
    NGX_TRANSLATE_HTTP: LIBS.INTERNATIONALIZATION.NGX_TRANSLATE_HTTP,
};

Step 4: Build and Publish

npm run build
npm version patch
npm publish

🐳 Part 6: Production Builds & Docker Integration

Using --production Flag

When building Docker images for production, you only need runtime dependencies, not dev dependencies (testing tools, linters, etc.).

Production Sync Command

node ./node_modules/@houssem__/angular-base/dist/sync-all-deps.js --mf-your-project --production

What --production does:

• ✅ Installs only runtime dependencies (from dependencies/mfes-libs/)
• ❌ Skips dev dependencies (from dev-dependencies/mfes-dev-libs/)
• 🎯 Results in smaller node_modules and faster Docker builds

Docker Use Case

Your Dockerfile uses npm ci --omit=dev, which already excludes devDependencies. Here's how to integrate with this library:

Dockerfile Example

FROM rxlhqdevdcenboregistry01.azurecr.io/node-microfront-v2
WORKDIR /app

COPY package*.json ./
COPY docker/run.sh /run.sh

RUN npm install -g envsub

# Use --production flag to sync only runtime dependencies
RUN npx @houssem__/angular-base sync --mf-your-project --production

# Install only production dependencies (no dev tools)
RUN npm ci --omit=dev

RUN npm install elastic-apm-node
RUN dos2unix /run.sh && chmod +x /run.sh

COPY dist dist/

EXPOSE 80

CMD ["/bin/sh", "-c", "/run.sh"]

Alternative: Pre-build Approach (Recommended)

Build your app locally with all dependencies:

{
  "scripts": {
    "postinstall": "node ./node_modules/@houssem__/angular-base/dist/sync-all-deps.js --mf-your-project",
    "build": "ng build",
    "docker:prepare": "node ./node_modules/@houssem__/angular-base/dist/sync-all-deps.js --mf-your-project --production"
  }
}

Then in CI/CD pipeline:

# Development: Full install with dev dependencies
npm install
npm run build

# Production: Generate package.json with only runtime deps
npm run docker:prepare
# This creates a clean package.json with only production dependencies

# Docker build uses the production-ready package.json
docker build -t your-mfe .

Flag Comparison

| Command | Dependencies Installed | Use Case | |---------|----------------------|----------| | sync-all-deps.js --mf-header | Runtime + Dev | Local development, CI builds | | sync-all-deps.js --mf-header --production | Runtime only | Docker images, production deployments |

Benefits of --production:

• 📦 Smaller Docker images (no testing/linting tools)
• ⚡ Faster npm ci in Docker (fewer packages)
• 🔒 Production containers only contain necessary runtime code

🚀 Part 7: Performance Testing & Monitoring

Why Performance Matters

When managing dependencies for 10 micro-frontends with 100+ packages each, performance is critical:

• ⚡ Developer Experience: Slow npm install frustrates developers
• 🔄 CI/CD Pipeline Speed: Every second counts in automated builds
• 📦 Build Time: Faster dependency resolution = faster deployments
• 💰 Cost Efficiency: Reduced CI/CD minutes = lower infrastructure costs

Built-in Performance Testing

This library includes a performance monitoring tool to ensure the dependency management system stays fast as it grows.

Running Performance Tests

# In the library project
npm run perf

Expected Output:

🔍 Performance Test - Dependency Management System

📊 Results:
⏱️  Total Time: 0.27ms
💾 Memory: 3.74MB
📦 Runtime Versions: 69
📂 Runtime Categories: 13
🛠️  Dev Versions: 81
📂 Dev Categories: 12
🎯 Available MFEs: 10
📋 First MFE (mf-footer): 35 runtime deps, 65 dev deps
🎯 Performance: ✅ EXCELLENT

Performance Benchmarks

| Metric | Threshold | Status | |--------|-----------|--------| | < 100ms | Excellent ✅ | Zero noticeable delay | | 100-200ms | Good ✅ | Acceptable for production | | > 200ms | Needs Optimization ⚠️ | Consider refactoring |

What Gets Measured

1. Loading Speed - Time to load all versions and categories
2. Memory Usage - RAM consumption during execution
3. Package Count - Total runtime and dev dependencies
4. Category Organization - Number of logical groupings
5. MFE Discovery - Time to detect all registered projects
6. Config Loading - Sample MFE dependency resolution

When to Run Performance Tests

✅ Before publishing a new version to Nexus
✅ After adding multiple new packages or categories
✅ After registering a new MFE project
✅ Weekly as part of maintenance routine
✅ If developers report slow npm install times

Performance Impact on MFEs

When an MFE project runs:

npm install  # Triggers postinstall script

The library's performance directly affects:

• Local development: Developer waiting time
• CI/CD pipelines: Build minutes consumed
• Docker builds: Image creation speed

Current performance (0.27ms) means:

• ✅ Imperceptible delay for developers
• ✅ Negligible impact on CI/CD
• ✅ Optimized for 100+ packages per MFE

Optimization Tips

If performance degrades over time:

1. Avoid Dynamic Imports - Use static imports for categories
2. Minimize File I/O - Keep version lookups in-memory
3. Optimize Loops - Use efficient iteration patterns
4. Lazy Loading - Only load configs when needed
5. Cache Results - Store repeated calculations

Real-World Impact

Example: 10 MFEs in CI/CD

Without optimization:

• Each MFE sync: 500ms
• Total pipeline delay: 5 seconds
• Monthly builds (100/MFE): 8.3 minutes wasted

With current performance (0.27ms):

• Each MFE sync: 0.27ms
• Total pipeline delay: 2.7ms
• Monthly builds (100/MFE): ~0.5 seconds total

Savings: ~8 minutes per month per MFE = 80+ minutes monthly across all MFEs 💰