npm package: @houssem__/xxxx
Description: Centralized dependency management for micro-frontend projects - TypeScript Edition
Latest version: 7.0.3

# 🚀 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:**

```json
{
  "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:**
```bash
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`

```typescript
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`

```typescript
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:**
```bash
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:**
   ```bash
   # 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/core@18.2.0`
   - Library might have: `@angular/core@19.2.14`
   - **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:**
   ```bash
   # 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`:

```typescript
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`:

```typescript
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`:

```typescript
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`:
```typescript
export { MF_YOUR_NEW_PROJECT_LIBS } from './mf-your-new-project';
```

Update `src/dev-dependencies/mfes-dev-libs/index.ts`:
```typescript
export { MF_YOUR_NEW_PROJECT_DEV_LIBS } from './mf-your-new-project';
```

#### Step 5: Build, Test, and Publish

```bash
# 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`:

```typescript
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`:

```typescript
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`:

```typescript
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`:

```typescript
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

```bash
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

```bash
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

```dockerfile
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:**

```json
{
  "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:**

```bash
# 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

```bash
# 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:
```bash
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** 💰

---