@yaagoub/federation-tools 1.2.7 → 1.2.8

package/README.md

@@ -1,63 +1,220 @@
 # FederationTools
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.3.0.
+**FederationTools** is a lightweight utility library designed to simplify **environment variables**, **assets**, and **internationalization (i18n)** management across **Angular micro-frontend architectures** (Module Federation / Native Federation).
 
-## Code scaffolding
+It provides a **single, consistent API** that works across the **shell** and all **remote MFEs**, without iframes and without leaking configuration to `window`.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+---
+
+## 📦 Installation
+
+Add the library to your workspace:
 
 ```bash
-ng generate component component-name
+npm install @yaagoub/federation-tools
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+---
 
-```bash
-ng generate --help
+## 📁 Project Structure (Shell)
+
+The shell application acts as the **single source of truth** for:
+
+* environment variables
+* translations
+* asset origins
+
+Recommended structure:
+
+```
+└── 📁settings
+    ├── 📁env
+    │   └── env.json                # Shell environment variables
+    │
+    ├── 📁i18n
+    │   ├── en.json                 # English translations
+    │   └── ar.json                 # Arabic translations
+    │
+    └── 📁manifest
+        ├── 📁assets
+        │   └── assets.manifest.json
+        │       {
+        │         "shell": "http://localhost:4200",
+        │         "mfe1":  "http://localhost:4201",
+        │         "mfe2":  "http://localhost:4202"
+        │       }
+        │
+        ├── 📁env
+        │   └── env.manifest.json
+        │       {
+        │         "shell": "http://localhost:4200",
+        │         "mfe1":  "http://localhost:4201",
+        │         "mfe2":  "http://localhost:4202"
+        │       }
+        │
+        └── 📁i18n
+            └── i18n.manifest.json
+                {
+                  "shell": "http://localhost:4200",
+                  "mfe1":  "http://localhost:4201",
+                  "mfe2":  "http://localhost:4202"
+                }
 ```
 
-## Building
+for  remotes Recommended structure:
 
-To build the library, run:
+```
+└── 📁settings
+    ├── 📁env
+    │   └── env.json                # mfe environment variables
+    │
+    ├── 📁i18n
+    │   ├── en.json                 # English translations
+    │   └── ar.json                 # Arabic translations
+```
 
-```bash
-ng build federation-tools
+Each manifest defines **where to fetch data from** for each micro frontend.
+
+---
+
+## ⚙️ Development Configuration (Angular)
+
+During development, expose the manifests and settings using the Angular assets configuration:
+
+```json
+"development": {
+  "assets": [
+    {
+      "glob": "**/*",
+      "input": "projects/lkhedma/public"
+    },
+    {
+      "glob": "env.manifest.json",
+      "input": "projects/../src/settings/manifest/env",
+      "output": "."
+    },
+    {
+      "glob": "assets.manifest.json",
+      "input": "projects/../src/settings/manifest/assets",
+      "output": "."
+    },
+    {
+      "glob": "i18n.manifest.json",
+      "input": "projects/../src/settings/manifest/i18n",
+      "output": "."
+    },
+    {
+      "glob": "**/*",
+      "input": "projects/../src/settings/i18n",
+      "output": "i18n"
+    },
+    {
+      "glob": "env.json",
+      "input": "projects/../src/settings/env",
+      "output": "."
+    }
+  ],
+  "optimization": false,
+  "extractLicenses": false,
+  "sourceMap": true
+}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+> 💡 In production, these files are typically served by the shell (CDN, Nginx, or gateway).
 
-### Publishing the Library
+---
 
-Once the project is built, you can publish your library by following these steps:
+## 🔌 Shell Providers Setup
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/federation-tools
-   ```
+Register the FederationTools providers **once** in the shell application:
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+```ts
+provideFederationAsset(),
+provideFederationEnv(),
+provideFederationTranslation('en') // default language
+```
 
-## Running unit tests
+These providers automatically:
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+* load manifests
+* fetch remote data
+* cache results
+* expose a unified API to all MFEs
 
-```bash
-ng test
+---
+
+## 🖼️ Federated Assets
+
+Use assets from **any MFE** by prefixing the asset name with the micro frontend key.
+
+```html
+<img [asset]="'mfe1:logo.png'" />
 ```
 
-## Running end-to-end tests
+### Supported elements
 
-For end-to-end (e2e) testing, run:
+The `asset` directive works with:
 
-```bash
-ng e2e
+* `img`
+* `video`
+* `audio`
+* `iframe`
+* `source`
+* `a`
+* `object`
+
+The prefix (`mfe1`) must exist in `assets.manifest.json`.
+
+---
+
+## 🌍 Internationalization (i18n)
+
+FederationTools provides a federated translation system shared across all MFEs.
+
+### Template usage
+
+```html
+{{ 'home.title' | t }}
+```
+
+### Programmatic usage
+
+```ts
+import { inject } from '@angular/core';
+import { TranslationService } from '@yaagoub/federation-tools';
+
+const translationService = inject(TranslationService);
+
+translationService.t('home.title');
+```
+
+Translations are:
+
+* loaded lazily
+* merged across shell + MFEs
+* automatically updated when the language changes
+
+---
+
+## 🔐 Environment Variables
+
+Environment variables are **not exposed on `window`** and are only accessible through the FederationTools API.
+
+### Waiting for environment initialization
+
+```ts
+import { from } from 'rxjs';
+import { waitForFederationEnv } from '@yaagoub/federation-tools';
+
+from(waitForFederationEnv('mfe1')).subscribe(env => {
+  // Safe access to federated environment variables
+});
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+### Key guarantees
 
-## Additional Resources
+* ✔️ Shell loads the environment first
+* ✔️ MFEs wait safely for availability
+* ✔️ Immutable, frozen configuration
+* ✔️ No global leaks
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaagoub/federation-tools",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "peerDependencies": {
     "@angular/common": ">=15.0.0",
     "@angular/core": ">=15.0.0"