@opensourcekd/ng-common-libs 1.2.7 → 1.2.8

package/README.md

@@ -27,6 +27,70 @@ npm install @opensourcekd/ng-common-libs
 
 ## 🔧 Usage
 
+### ⚠️ IMPORTANT: Setup for Module Federation / MicroFrontends
+
+If you're using **Module Federation** with multiple Angular applications (shell + MFEs), you **MUST** configure the services as singletons using factory functions. This ensures ONE instance is shared across all applications.
+
+**In your shell app AND each MFE's `app.config.ts` (standalone) or `app.module.ts` (NgModule):**
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { 
+  AuthService, 
+  EventBusService, 
+  getAuthService, 
+  getEventBusService,
+  configureAuth0 
+} from '@opensourcekd/ng-common-libs';
+import { APP_CONFIG } from '@opensourcekd/ng-common-libs/core';
+
+// Configure Auth0 (do this once in shell or each MFE)
+configureAuth0({
+  domain: APP_CONFIG.auth0Domain,
+  clientId: APP_CONFIG.auth0ClientId,
+  audience: APP_CONFIG.apiUrl,
+});
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // REQUIRED: Use factory functions for singleton behavior across MFEs
+    { provide: EventBusService, useFactory: getEventBusService },
+    { provide: AuthService, useFactory: getAuthService },
+    // ... your other providers
+  ]
+};
+```
+
+**Why is this needed?**  
+Angular's `providedIn: 'root'` creates one instance per Angular application. In Module Federation, each MFE is a separate Angular app, so you'd get multiple instances. Factory functions create a **JavaScript module-level singleton** that's shared across ALL applications.
+
+**For NgModule-based apps:**
+```typescript
+import { NgModule } from '@angular/core';
+import { 
+  AuthService, 
+  EventBusService, 
+  getAuthService, 
+  getEventBusService 
+} from '@opensourcekd/ng-common-libs';
+
+@NgModule({
+  providers: [
+    { provide: EventBusService, useFactory: getEventBusService },
+    { provide: AuthService, useFactory: getAuthService }
+  ]
+})
+export class AppModule { }
+```
+
+Then use normally in components with `inject()`:
+```typescript
+export class MyComponent {
+  private authService = inject(AuthService);
+  private eventBus = inject(EventBusService);
+}
+```
+
 ### Configuration (Framework-Agnostic)
 
 The library provides a framework-agnostic configuration utility with **statically configured values** from GitHub repository variables:
@@ -49,19 +113,13 @@ console.log(APP_CONFIG.auth0ClientId);  // Configured during build from GitHub v
 
 ### Auth0 Authentication
 
-Complete Auth0 integration with automatic token management and event emission:
+Complete Auth0 integration with automatic token management and event emission.
+
+**Note:** Make sure you've configured the providers as shown in the [Module Federation setup](#️-important-setup-for-module-federation--microfrontends) above first!
 
 ```typescript
 import { Component, inject } from '@angular/core';
-import { AuthService, configureAuth0 } from '@opensourcekd/ng-common-libs';
-import { APP_CONFIG } from '@opensourcekd/ng-common-libs/core';
-
-// Use pre-configured values from APP_CONFIG
-configureAuth0({
-  domain: APP_CONFIG.auth0Domain,
-  clientId: APP_CONFIG.auth0ClientId,
-  audience: APP_CONFIG.apiUrl,
-});
+import { AuthService } from '@opensourcekd/ng-common-libs';
 
 @Component({
   selector: 'app-login',
@@ -89,7 +147,9 @@ See the [Auth0 Service Usage Guide](./docs/AUTH_SERVICE_USAGE.md) for complete i
 
 ### EventBusService
 
-Cross-application event communication for MicroFrontend architectures:
+Cross-application event communication for MicroFrontend architectures.
+
+**Note:** Make sure you've configured the providers as shown in the [Module Federation setup](#️-important-setup-for-module-federation--microfrontends) above first!
 
 ```typescript
 import { Component, OnInit, inject } from '@angular/core';