Merge branch 'main' of https://github.com/angular-architects/module-federation-plugin into main

Author: manfredsteyer

libs/mf-tools/README.md

@@ -91,6 +91,67 @@ bootstrap(AppModule, {
 
 > Use this bootstrap helper for **both**, your shell and your micro frontends!
 
+## Sharing Zone.js
+
+In order to share zone.js, call our ``shareNgZone`` helper when starting the shell. 
+
+```typescript
+import { Component, NgZone } from '@angular/core';
+import { shareNgZone } from '@angular-architects/module-federation-tools';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+})
+export class AppComponent {
+  title = 'shell';
+
+  constructor(private ngZone: NgZone) {
+    shareNgZone(ngZone);
+  }
+
+}
+```
+
+The micro frontends will pick it up, if they are bootstrapped with the ``bootstrap`` helper (see above).
+
+## Details on ngZone and Platform sharing
+
+> In a multi version micro frontend strategy, it is important to load the zone.js bundle to the window object only once. Also, one need to make sure that only one instance of the ngZone is used by all the micro frontends.
+
+If you share `@angular/core` and therefore also have one technical reference to the BrowserPlatform, that is used by more than one micro frondend, Angular's default setup is, to support only one platform instance per shared version. Be aware that you **need** to create multi platform instances in case of different versions, but also in case the version is the same, but `@angular/core` is not shared, but packed into the micro frontend's bundles directly (like in Angular's default way w/o module federation).
+
+Naturally, such technical details are hard to get into. Therefore the `bootstrap()` function of this package helps to implement your multi version strategy w/o the need of implementing those low-level aspects on your own.
+
+Some optional flags are offered to provide options for custom behavior of the `bootstrap()` function:
+
+- `ngZoneSharing: false`: Deactivate ngZone sharing in the window object (not recommended):
+  ```typescript
+  bootstrap(AppModule, {
+    production: environment.production,
+    ngZoneSharing: false // defaults to true
+  });
+  ```
+- `platformSharing: false`: Deactivate Platform sharing in the window object (not recommended):
+  ```typescript
+  bootstrap(AppModule, {
+    production: environment.production,
+    platformSharing: false // defaults to true
+  });
+  ```
+  - Possible, if dependencies are not shared or each bootstrapped remote app uses a different version.
+- `activeLegacyMode: false`: Deactivates the legacy mode that provides backwards compatibility for Platform sharing:
+  ```typescript
+  bootstrap(AppModule, {
+    production: environment.production,
+    activeLegacyMode: false // defaults to true
+  });
+  ```
+  - If all your micro frontends use `@angular-architects/module-federation-tools` in version `^12.6.0`, `^13.1.0` or any newer major version you can switch off the legacy mode manually.
+  - Those versions introduced new features on how to share the Platform in the window object.
+  - This allows to use the `bootstrap()` function even in such cases, where the same version is packed into different micro frontend bundles.
+
+
 ## Routing to Web Components
 
 The ``WebComponentWrapper`` helps you to route to web components:
@@ -216,30 +277,6 @@ events = {
 <mft-wc-wrapper [options]="item" [props]="props" [events]="events"></mft-wc-wrapper>
 ```
 
-## Sharing Zone.js
-
-In order to share zone.js, call our ``shareNgZone`` helper when starting the shell. 
-
-```typescript
-import { Component, NgZone } from '@angular/core';
-import { shareNgZone } from '@angular-architects/module-federation-tools';
-
-@Component({
-  selector: 'app-root',
-  templateUrl: './app.component.html',
-})
-export class AppComponent {
-  title = 'shell';
-
-  constructor(private ngZone: NgZone) {
-    shareNgZone(ngZone);
-  }
-
-}
-```
-
-The micro frontends will pick it up, if they are bootstrapped with the ``bootstrap`` helper (see above).
-
 ## More about the underlying ideas
 
 Please find more information on the underlying ideas in this [blog article](https://www.angulararchitects.io/aktuelles/multi-framework-and-version-micro-frontends-with-module-federation-the-good-the-bad-the-ugly).

libs/mf-tools/src/lib/utils/global-state.ts

@@ -0,0 +1,23 @@
+export const packageNamespace = '@angular-architects/module-federation-tools';
+
+function getGlobalState<T>(): T {
+    const globalState = (window as unknown as { [packageNamespace]: T });
+    globalState[packageNamespace] = globalState[packageNamespace] || ({} as unknown as T);
+    return globalState[packageNamespace];
+}
+
+export function getGlobalStateSlice<T>(): T;
+export function getGlobalStateSlice<T, R>(selector: (globalState: T) => R): R;
+export function getGlobalStateSlice<T, R>(
+    selector?: (globalState: T) => R
+): R | T {
+    const globalState = getGlobalState<T>();
+    return selector ? selector(globalState) : globalState;
+}
+
+export function setGlobalStateSlice<T>(slice: T): T {
+    return Object.assign(
+        getGlobalState<T>(),
+        slice
+    );
+}

libs/mf-tools/src/lib/web-components/bootstrap-utils.ts

@@ -1,12 +1,33 @@
-import { CompilerOptions, enableProdMode, NgModuleRef, NgZone, PlatformRef, Type } from "@angular/core";
+import { CompilerOptions, enableProdMode, NgModuleRef, NgZone, PlatformRef, Type, Version } from "@angular/core";
 import { platformBrowser } from "@angular/platform-browser";
 import { VERSION } from '@angular/core';
+import { getGlobalStateSlice, setGlobalStateSlice } from "../utils/global-state";
 
 export type Options = {
     production: boolean,
     platformFactory?: () => PlatformRef,
     compilerOptions?: CompilerOptions & BootstrapOptions,
-    version?: () => string,
+    version?: () => string | Version,
+    /**
+     * Opt-out of ngZone sharing.
+     * Not recommanded.
+     * Default value true.
+     */
+    ngZoneSharing?: boolean,
+    /**
+     * Opt-out of platformSharing sharing.
+     * Possible, if dependencies are not shared or each bootstrapped
+     * remote app uses a different version.
+     * Default value true.
+     */
+    platformSharing?: boolean,
+    /**
+     * Deactivate support for legacy mode.
+     * Only recommanded if all used implementations depend on
+     * @angular-architects/module-federation-tools > 13.0.1.
+     * Default value true.
+     */
+    activeLegacyMode?: boolean
 };
 
 declare interface BootstrapOptions {
@@ -15,9 +36,9 @@ declare interface BootstrapOptions {
     ngZoneRunCoalescing?: boolean;
 }
 
-export type PlatformCache = {
-    platform: Map<unknown, PlatformRef>
-};
+let ngZoneSharing = true;
+let platformSharing = true;
+let legacyMode = true;
 
 export function getMajor(version: string): string {
     const pre = version.match(/\d+/)[0];
@@ -34,47 +55,111 @@ export function getMajor(version: string): string {
     return pre;
 }
 
-function getPlatformCache(): PlatformCache {
-    const platformCache = window as unknown as PlatformCache;
-    platformCache.platform = platformCache.platform || new Map<unknown, PlatformRef>();
+/**
+ * LEGACY IMPLEMENTATIONS START
+ *
+ * Can be deprecated in later major releases.
+ *
+ * To increase backwards compatibility legacy and current namespaces
+ * within the window object are used.
+ */
+
+export type LegacyPlatformCache = {
+    platform: Record<string, PlatformRef>;
+};
+
+function getLegacyPlatformCache(): LegacyPlatformCache {
+    const platformCache = window as unknown as LegacyPlatformCache;
+    platformCache.platform = platformCache.platform || {};
     return platformCache;
 }
 
-function getNgZone(): NgZone {
+function getLegacyPlatform(key: string): PlatformRef {
+    const platform = getLegacyPlatformCache().platform[key];
+    /**
+     * If dependencies are not shared, platform with same version is different
+     * and shared platform will not be returned.
+     */
+    return platform instanceof PlatformRef ? platform : null;
+}
+
+function setLegacyPlatform(key: string, platform: PlatformRef): void {
+    getLegacyPlatformCache().platform[key] = platform;
+}
+
+function getLegacyNgZone(): NgZone {
     return window['ngZone'];
-}   
+}
 
-export function shareNgZone(zone: NgZone): void {
+function setLegacyNgZone(zone: NgZone): void {
     window['ngZone'] = zone;
 }
 
-export function bootstrap<M>(module: Type<M>, options: Options): Promise<NgModuleRef<M>> {
+/**
+ * LEGACY IMPLEMENTATIONS END
+ */
 
-    if (!options.platformFactory) {
-        options.platformFactory = () => platformBrowser();
+function getPlatformCache(): Map<Version, PlatformRef> {
+    return getGlobalStateSlice(
+        (state: { platformCache: Map<Version, PlatformRef> }) => state.platformCache
+    ) || setGlobalStateSlice({
+        platformCache: new Map<Version, PlatformRef>()
+    }).platformCache;
+}
+
+function setPlatform(version: Version, platform: PlatformRef): void {
+    if (platformSharing) {
+      legacyMode && setLegacyPlatform(version.full, platform);
+      getPlatformCache().set(version, platform);
     }
+}
 
-    if (!options.compilerOptions?.ngZone) {
-        options.compilerOptions = options.compilerOptions || {};
-        options.compilerOptions.ngZone = getNgZone();
+function getPlatform(options: Options): PlatformRef {
+    if (!platformSharing) {
+        return options.platformFactory();
     }
 
-    // if (!options.version) {
-    //     options.version = () => VERSION.full;
-    // }
+    const versionResult = options.version();
+    const version = versionResult === VERSION.full ? VERSION : versionResult;
+    const versionKey = typeof version === 'string' ? version : version.full;
 
-    // const key = options.version(); 
-    const platformCache = getPlatformCache();
+    let platform =
+        getPlatformCache().get(version as Version) ||
+        (legacyMode && getLegacyPlatform(versionKey));
 
-    let platform = platformCache.platform.get(VERSION);
     if (!platform) {
         platform = options.platformFactory();
-        platformCache.platform.set(VERSION, platform); 
+        setPlatform(VERSION, platform);
+    }
+
+    return platform;
+}
 
-        if (options.production) {
-            enableProdMode();
-        }
+function getNgZone(): NgZone {
+    return getGlobalStateSlice(
+        (state: { ngZone: NgZone }) => state.ngZone
+    ) || getLegacyNgZone();
+}
+
+export function shareNgZone(zone: NgZone): void {
+    if (ngZoneSharing) {
+      legacyMode && setLegacyNgZone(zone);
+      setGlobalStateSlice({ ngZone: zone });
     }
+}
 
-    return platform.bootstrapModule(module, options.compilerOptions);
-}
+export function bootstrap<M>(module: Type<M>, options: Options): Promise<NgModuleRef<M>> {
+    ngZoneSharing = options.ngZoneSharing !== false;
+    platformSharing = options.platformSharing !== false;
+    legacyMode = options.activeLegacyMode !== false;
+    options.platformFactory = options.platformFactory || (() => platformBrowser());
+    options.version = options.version || (() => VERSION);
+    options.production && enableProdMode();
+
+    if (ngZoneSharing && !options.compilerOptions?.ngZone) {
+        options.compilerOptions = options.compilerOptions || {};
+        options.compilerOptions.ngZone = getNgZone();
+    }
+
+    return getPlatform(options).bootstrapModule(module, options.compilerOptions);
+}

libs/mf/README.md

@@ -226,7 +226,7 @@ plugins: [
 
 The helper function share adds some additional options for the shared dependencies:
 
-```json
+```typescript
 shared: share({
     "@angular/common": { 
         singleton: true, 
@@ -282,7 +282,7 @@ shared: share({
 
 The ``shareAll`` helper shares all your dependencies defined in your ``package.json``. The ``package.json`` is look up as described above:
 
-```json
+```typescript
 shared: {
   ...shareAll({ 
       singleton: true, 
@@ -401,20 +401,20 @@ If you get the warning _No required version specified and unable to automaticall
 
 To avoid this warning you can specify to used version by hand:
 
-```json
+```typescript
 shared: { 
     "@angular/common": { 
         singleton: true, 
         strictVersion: true, 
-        requireVersion: '12.0.0  
+        requireVersion: '12.0.0'  
     },
     [...]
 },
 ```
 
 You can also use our ``share`` helper that infers the version number from your ``package.json`` when setting ``requireVersion`` to ``'auto'``:
 
-```json
+```typescript
 shared: share({
     "@angular/common": { 
         singleton: true, 

libs/mf/src/utils/share-utils.ts

@@ -1,12 +1,15 @@
 import callsite = require('callsite');
 import path = require('path');
 import fs = require('fs');
+import { SharedConfig } from './webpack.types';
 
 let inferVersion = false;
 
-type VersionMap = { [packageName:string]: string };
+type VersionMap = Record<string, string>;
 type IncludeSecondariesOptions = { skip: string | string[] } | boolean;
-type Config =  { [setting:string]: unknown };
+type CustomSharedConfig =  SharedConfig & { includeSecondaries: IncludeSecondariesOptions };
+type ConfigObject = Record<string, CustomSharedConfig>;
+type Config = (string | ConfigObject)[] | ConfigObject;
 
 function findPackageJson(folder: string): string {
     while (
@@ -127,7 +130,7 @@ export function setInferVersion(infer: boolean): void {
     inferVersion = infer;
 }
 
-export function share(shareObjects: Config[], packageJsonPath = ''): Config {
+export function share(shareObjects: Config, packageJsonPath = ''): Config {
 
     if (!packageJsonPath) {
         const stack = callsite();
@@ -164,4 +167,3 @@ export function share(shareObjects: Config[], packageJsonPath = ''): Config {
 
     return result;
 }
-