@angular-architects/native-federation 1.0.0-beta.1 → 16.1.0

package/README.md

@@ -1,85 +1,100 @@
-# Native Federation
+# Native Federation for Angular
 
-Native Federation is a "browser-native" implementation of the successful mental model behind wepback Module Federation for building Micro Frontends.
+Native Federation is a "browser-native" implementation of the successful mental model behind webpack Module Federation for building Micro Frontends (Plugins, etc.).
 
-## Features
+## Features 🔥
 
 - ✅ Mental Model of Module Federation
 - ✅ Future Proof: Independent of build tools like webpack
 - ✅ Embraces Import Maps - an emerging web standard
 - ✅ Easy to configure: We use the same API and Schematics as for our Module Federation plugin
-- ✅ Blazing Fast: The reference implementation not only uses the fast esbuild; it also caches already built shared dependencies (like Angular itself).
+- ✅ Blazing Fast: The reference implementation not only uses the fast esbuild; it also caches already built shared dependencies.
 
-## Today and Tomorrow
+## Prerequisite
 
-### Bundler
+Angular & Angular CLI 16.1 or higher
 
-The current version uses **esbuild**. Future versions will allow to easily **switch out the build tool**.
+This package was successfully tested with Angular CLI projects and with Nx projects.
 
-### Frameworks
+## Versions
 
-**Angular** is a first-class citizen: The package ships with **Schematics** for the Angular CLI and a **builder** (that delegates to the experimental esbuild builder the CLI team is current working on). Future versions will also make it easy to use the implementation **with other frameworks**.
-
-### Design
-
-This is possible, because by design, most of the implementation runs outside of the bundler und independently of CLI mechanisms. Hence, we will expose 2-3 helper functions everyone can call in their build process regardless of the framework or build tool used.
-
-## Current Limitations
-
-This is a first experimental version. The results look very promising, however it's not intended to be used in production. Feel free to try it out and to provide feedback!
-
-Limitations:
-
-- 🔷 As we use a fork of the experimental esbuild builder the CLI team is current working on, there is currently **only a builder for ng build**. ng serve or ng test are currently not supported. This support will be added with a future version. Also, as the forked esbuile builder is still experimental, you cannot expect to get all the features you are used to. This will also change over time.
-- 🔷 Libraries are currently only shared if two or more remotes (Micro Frontends) request the very same version. This is also what works best with Angular. In a future version, we will add optional "version negotiation" for the sake of feature parity with Module Federation. This allows Native Federation to decide for a "higher compatible version" (e. g. a higher minor version provided by another Micro Frontend) at runtime.
+We will at least provide a new version of this package per Angular major. If necessary, we will also provide packages to adapt to Angular minors. To make the relationship between Angular versions and versions of this package easy for all of us, **we follow Angular's version numbers**. E. g., `@angular-architects/native-federation` 16.1 is intended for Angular 16.1 and upwards.
 
 ## Credits
 
 Big thanks to:
 
-- [Zack Jackson](https://twitter.com/ScriptedAlchemy) for originally coming up with the great idea of Module Federation and its successful mental model
+- [Zack [Jackson](https://twitter.com/ScriptedAlchemy) for initially coming up with the great idea of Module Federation and its successful mental model
 - [Tobias Koppers](https://twitter.com/wSokra) for helping to make Module Federation a first class citizen of webpack
-- [Florian Rappl](https://twitter.com/FlorianRappl) for an good discussion about these topics during a speakers dinner in Nuremberg
+- [Florian [Rappl](https://twitter.com/FlorianRappl) for a good discussion about these topics during a speakers dinner in Nuremberg
 - [The Nx Team](https://twitter.com/NxDevTools), esp. [Colum Ferry](https://twitter.com/FerryColum), who seamlessly integrated webpack Module Federation into Nx and hence helped to spread the word about it (Nx + Module Federation === ❤️)
 - [Michael Egger-Zikes](https://twitter.com/MikeZks) for contributing to our Module Federation efforts and brining in valuable feedback
-- The Angular CLI-Team, esp. [Alan Agius](https://twitter.com/AlanAgius4) and [Charles Lyding](https://twitter.com/charleslyding), for working on the experimental esbuild builder for Angular
+- The Angular CLI-Team, esp. [Alan Agius](https://twitter.com/AlanAgius4) and [Charles Lyding](https://twitter.com/charleslyding), for their fantastic work on the esbuild builder for Angular
 
-## Example
+## Example 🛠️
 
 We migrated our webpack Module Federation example to Native Federation:
 
 ![Example](https://raw.githubusercontent.com/angular-architects/module-federation-plugin/main/libs/native-federation/example.png)
 
-Please find the example [here (branch: ng-solution)](https://github.com/manfredsteyer/module-federation-plugin-example/tree/nf-solution):
+Please find the example [here (branch: nf-standalone-solution)](https://github.com/manfredsteyer/module-federation-plugin-example/tree/nf-standalone-solution):
 
 ```
-git clone https://github.com/manfredsteyer/module-federation-plugin-example.git --branch nf-solution
+git clone https://github.com/manfredsteyer/module-federation-plugin-example.git --branch nf-standalone-solution
 
 cd module-federation-plugin-example
 
 npm i
-npm run build
-npm start
 ```
 
-Then, open http://localhost:3000 in your browser.
+Start the Micro Frontend:
 
-Please note, that the current **experimental** version does **not** support `ng serve`. Hence, you need to build it and serve it from the `dist` folder (this is what npm run build && npm run start in the above shown example do).
+```
+ng serve mfe1 -o
+```
 
-## About the Mental Model
+Wait until the Micro Frontend is started.
 
-The underlying mental model allows for runtime integration: Loading a part of a separately built and deployed application into your's. This is needed for Micro Frontend architectures but also for plugin-based solutions.
+Open another console and start the shell:
+
+```
+ng serve shell -o
+```
+
+The example loads a Micro Frontends into a shell:
+
+![Microfrontend Loaded into Shell](https://github.com/angular-architects/module-federation-plugin/raw/main/libs/mf/tutorial/result.png)
+
+## Relationship to @angular-architects/module-federation
+
+This package, `@angular-architects/native-federation`, uses the same API as `@angular-architects/module-federation`. To switch over, just make sure you import everything from the former package. Don't mix these packages.
+
+## About the Mental Model 🧠
+
+The underlying mental model allows for runtime integration: Loading a part of a separately built and deployed application into yours. This is needed for Micro Frontend architectures but also for plugin-based solutions.
 
 For this, the mental model introduces several concepts:
 
 - **Remote:** The remote is a separately built and deployed application. It can **expose EcmaScript** modules that can be loaded into other applications.
-- **Host:** The host loads one or several remotes on demand. For your framework's perspective, this looks like traditional lazy loading. The big difference is that the host doesn't know the remotes at compilation time.
-- **Shared Dependencies:** If a several remotes and the host use the same library, you might not want to download it several times. Instead, you might want to just download it once and share it at runtime. For this use case, the mental model allows for defining such shared dependencies.
-- **Version Mismatch:** If two or more applications use a different version of the same shared library, we need to prevent a version mismatch. To deal with it, the mental model defines several strategies, like falling back to another version that fits the application, using a different compatible one (according to semantic versioning) or throwing an error.
+- **Host:** The host loads one or several remotes on demand. From your framework's perspective, this looks like traditional lazy loading. The big difference is that the host doesn't know the remotes at compilation time.
+- **Shared Dependencies**:\*\* If several remotes and the host use the same library, you might not want to download it several times. Instead, you might want to download it once and share it at runtime. For this use case, the mental model allows for defining such shared dependencies.
+- **Version Mismatch:** If two or more applications use a different version of the same shared library, we need to prevent a version mismatch. The mental model defines several strategies to deal with it, like falling back to another version that fits the application, using a different compatible one (according to semantic versioning), or throwing an error.
 
-## Usage
+## Usage/ Tutorial 🧪
 
-> You can checkout the [nf-starter branch](https://github.com/manfredsteyer/module-federation-plugin-example/tree/nf-solution) to try out Native Federation.
+You can checkout the [nf-standalone-starter branch](https://github.com/manfredsteyer/module-federation-plugin-example/tree/nf-standalone-starter) to try out Native Federation:
+
+```
+git clone https://github.com/manfredsteyer/module-federation-plugin-example.git --branch nf-standalone-starter
+
+cd module-federation-plugin-example
+
+npm i
+```
+
+This repository consists of two Angular applications: a `shell` and a Micro Frontend called `mfe1`. During this tutorial, you will load `mfe1` into the `shell`:
+
+![Microfrontend Loaded into Shell](https://github.com/angular-architects/module-federation-plugin/raw/main/libs/mf/tutorial/result.png)
 
 ### Adding Native Federation
 
@@ -87,31 +102,27 @@ For this, the mental model introduces several concepts:
 npm i @angular-architects/native-federation -D
 ```
 
-Making an application a host:
+Making an application a remote (Micro Frontend):
 
 ```
-ng g @angular-architects/native-federation:init --project shell --type host
+ng g @angular-architects/native-federation:init --project mfe1 --port 4201 --type remote
 ```
 
-A dynamic host is a host reading the configuration data at runtime from a `.json` file:
+Making an application a host (shell):
 
 ```
-ng g @angular-architects/native-federation:init --project shell --type dynamic-host
+ng g @angular-architects/native-federation:init --project shell --port 4200 --type dynamic-host
 ```
 
-Making an application a remote:
+A dynamic host reads the configuration data at runtime from a `.json` file.
 
-```
-ng g @angular-architects/native-federation:init --project mfe1 --type remote
-```
+> The schematics called here automate most steps of this tutorial, esp. adding configuration files and bootstrapping Native Federation. Hence, the following sections primarily discuss these changes. You just need to add a lazy route (see below) and make sure the correct ports are configured in the federation manifest (see below too).
 
 ### Configuring the Host
 
-The host configuration looks like what you know from our Module Federation plugin:
+The host configuration (`projects/shell/federation.config.js`) looks like what you know from our Module Federation plugin:
 
 ```javascript
-// projects/shell/federation.config.js
-
 const {
   withNativeFederation,
   shareAll,
@@ -125,16 +136,24 @@ module.exports = withNativeFederation({
       requiredVersion: 'auto',
     }),
   },
+
+  skip: [
+    'rxjs/ajax',
+    'rxjs/fetch',
+    'rxjs/testing',
+    'rxjs/webSocket',
+    // Add further packages you don't need at runtime
+  ],
 });
 ```
 
+> Our `init` schematic shown above generates this file for you.
+
 ### Configuring the Remote
 
-Also the remote configuration looks familiar:
+Also, the remote configuration (`projects/mfe1/federation.config.js`) looks familiar:
 
 ```javascript
-// projects/mfe1/federation.config.js
-
 const {
   withNativeFederation,
   shareAll,
@@ -144,7 +163,7 @@ module.exports = withNativeFederation({
   name: 'mfe1',
 
   exposes: {
-    './Module': './projects/mfe1/src/app/flights/flights.module.ts',
+    './Component': './projects/mfe1/src/app/app.component.ts',
   },
 
   shared: {
@@ -154,37 +173,24 @@ module.exports = withNativeFederation({
       requiredVersion: 'auto',
     }),
   },
-});
-```
-
-### Initializing the Host
-
-Call `initFederation` before bootstrapping your `main.ts`:
 
-```typescript
-// projects/shell/src/main.ts
-
-import { initFederation } from '@angular-architects/native-federation';
-
-initFederation({
-  mfe1: 'http://localhost:3001/remoteEntry.json',
-})
-  .catch((err) => console.error(err))
-  .then((_) => import('./bootstrap'))
-  .catch((err) => console.error(err));
+  skip: [
+    'rxjs/ajax',
+    'rxjs/fetch',
+    'rxjs/testing',
+    'rxjs/webSocket',
+    // Add further packages you don't need at runtime
+  ],
+});
 ```
 
-> Our `init` schematic shown above generates all of this if you pass `--type host`.
+> Our `init` schematic shown above generates this file for you.
 
-You can directly pass a mapping between remote names and their `remoteEntry.json`. The `remoteEntry.json` contains the necessary metadata. It is generated when compiling the remote.
-
-Please note that in Native Federation, the remote entry is just a `.json` file while its a `.js` file in Module Federation.
+### Initializing the Host
 
-However, you don't need to hardcode this mapping. Feel free to point to the file name of a federation manifest:
+When bootstrapping the host (shell), Native Federation (`projects\shell\src\main.ts`) is initialized:
 
 ```typescript
-// projects/shell/src/main.ts
-
 import { initFederation } from '@angular-architects/native-federation';
 
 initFederation('/assets/federation.manifest.json')
@@ -193,23 +199,27 @@ initFederation('/assets/federation.manifest.json')
   .catch((err) => console.error(err));
 ```
 
-This manifest can be exchanged when deploying the solution. Hence, you can adopt the solution to the current environment.
+> This file is generated by the schematic described above.
 
-> Our `init` schematic shown above generates this variation if you pass `--type dynamic-host`.
+The function points to a federation manifest. This manifest lists the individual remotes. It can be exchanged when deploying the solution. Hence, you can adapt the build to the respective environment.
 
-Credits: The Nx team originally came up with the idea for the manifest.
+**Credits:** The Nx team originally came up with the idea for the manifest.
 
-This is what the (also generated) federation manifest looks like:
+This is what the (also generated) federation manifest (`projects\shell\src\assets\federation.manifest.json`) looks like:
 
 ```json
 {
-  "mfe1": "http://localhost:3001/remoteEntry.json"
+  "mfe1": "http://localhost:4201/remoteEntry.json"
 }
 ```
 
+Native Federation generates the `remoteEntry.json`. It contains metadata about the individual remote.
+
+If you follow this tutorial, **ensure** this entry points to port `4201` (!).
+
 ### Initializing the Remote
 
-Also, the remote needs to be initialized. If a remote doesn't load further remotes, you don't need to pass any mappings to `initFederation`:
+When bootstrapping your remote (`projects\mfe1\src\main.ts`), Native Federation is initialized too:
 
 ```typescript
 import { initFederation } from '@angular-architects/native-federation';
@@ -220,92 +230,95 @@ initFederation()
   .catch((err) => console.error(err));
 ```
 
+> Our `init` schematic shown above also generates this file.
+
+After the initialization, it loads the file `bootstrap.ts` starting your Angular application.
+
 ### Loading a Remote
 
-Use the helper function `loadRemoteModule` to load a configured remote:
+For loading a component (or any other building block) exposed by a remote into the host, use Native Federation's `loadRemoteModule` function together with lazy loading (`projects\shell\src\app\app.routes.ts`):
 
 ```typescript
+import { Routes } from '@angular/router';
+import { HomeComponent } from './home/home.component';
+import { NotFoundComponent } from './not-found/not-found.component';
+
+// Add this import:
 import { loadRemoteModule } from '@angular-architects/native-federation';
-[...]
 
 export const APP_ROUTES: Routes = [
-    [...]
+  {
+    path: '',
+    component: HomeComponent,
+    pathMatch: 'full',
+  },
 
-    {
-      path: 'flights',
-      loadChildren: () => loadRemoteModule({
-          remoteName: 'mfe1',
-          exposedModule: './Module'
-        }).then(m => m.FlightsModule)
-    },
+  // Add this route:
+  {
+    path: 'flights',
+    loadComponent: () =>
+      loadRemoteModule('mfe1', './Component').then((m) => m.AppComponent),
+  },
 
-    [...]
-}
+  {
+    path: '**',
+    component: NotFoundComponent,
+  },
+
+  // DO NOT insert routes after this one.
+  // { path:'**', ...} needs to be the LAST one.
+];
 ```
 
-This can be used with and without routing; with `NgModule`s but also with **standalone** building blocks. Just use it instead of dynamic imports.
+### Starting your example
 
-For the sake of compatibility with our Module Federation API, you can also use the `remoteEntry` to identify the remote in question:
+Start the remote:
 
-```typescript
-import { loadRemoteModule } from '@angular-architects/native-federation';
-[...]
+```
+ng serve mfe1 -o
+```
+
+Once the remote is started, start the shell:
 
-export const APP_ROUTES: Routes = [
-    [...]
-
-    {
-      path: 'flights',
-      loadChildren: () => loadRemoteModule({
-          // Alternative: You can also use the remoteEntry i/o the remoteName:
-          remoteEntry: 'http://localhost:3001/remoteEntry.json',
-          exposedModule: './Module'
-        }).then(m => m.FlightsModule)
-    },
-
-    [...]
-}
+```
+ng serve shell -o
 ```
 
-However, we prefer the first option where just the `remoteName` is passed.
+Now, by clicking at the 2nd menu item, you can load the remote directly into the host.
 
-### Polyfill
+## FAQ
 
-This library uses Import Maps. As of today, not all browsers support this emerging browser feature, we need a polyfill. We recommend the polyfill `es-module-shims` which has been developed for production use cases. Our schematics install it via npm and add it to your `polyfills.ts`.
+### When to use this package?
 
-Also, the schematics add the following to your `index.html`:
+If you like the idea of webpack Module Federation but want to switch over to Angular's new esbuild builder (currently in developer preview), you can use this package.
 
-```html
-<script type="esms-options">
-  {
-      "shimMode": true
-  }
-</script>
+### I get an error when preparing shared packages. What to do?
 
-<script type="module" src="polyfills.js"></script>
+Native Federation needs to prepare all your shared packages so that it can load them on demand as EcmaScript modules. This only happens once for development and once for production builds. The result of this is cached.
 
-<script type="module-shim" src="main.js"></script>
-```
+If the preparation of one of these packages fails, you get an error like this one:
 
-The script with the type `esms-options` configures the polyfill. This library was built for shim mode. In this mode, the polyfill provides some additional features beyond the proposal for Import Maps. These features, for instance, allow for dynamically creating an import map after loading the first EcmaScript module. Native Federation uses this possibility.
+![error when preparing shared packages](https://github.com/angular-architects/module-federation-plugin/blob/main/error.png?raw=true)
 
-To make the polyfill to load your EcmaScript modules (bundles) in shim mode, assign the type `module-shim`. However, please just use module for the polyfill bundle itself to prevent an hen/egg-issue.
+For this, there are several reasons:
 
-## FAQ
+- Perhaps you try to share a package intended for NodeJS/ a package that cannot be converted to EcmaScript modules. This happens if you use `shareAll` in the `federation.config.js` and when the package in question is part of your dependencies in `package.json`. If you don't need (to share) this package at runtime, move it to `devDependencies` or add it to the `skip` section of your `federation.config.js`.
 
-### Should we Already use Native Federation in Production?
+- Perhaps your shared packages contain some code esbuild cannot transfer to EcmaScript modules. This should not be the case for packages, built with the Angular CLI or Nx and the underlying package ng-packagr. If this happens, please let us know about the package causing troubles.
 
-For production, we would stick with Module Federation for the time being. Native Federation, however, shows that you don't need to fear that you are left alone, once you (or the community) wants to move over to other build tools.
+### How to speed up package preparation during the build process
 
-We will evolve Native Federation but also our Module Federation support and keep you posted.
+The already prepared packages are cached in `node_modules/.cache`. Make sure, this folder is reused across subsequent build process runs.
 
 ### How does Native Federation Work under the Covers?
 
-We use Import Maps at runtime. As they are currently not supported in every browser, our `init` schematic installs the `es-module-shims` polyfill. In addition to Import Maps, we use some code at build time and at runtime to provide the Mental Model of Module Federation.
+We use Import Maps at runtime. In addition to Import Maps, we use some code at build time and at runtime to provide the Mental Model of Module Federation.
+
+## Documentation 📰
 
-## More: Blog Articles
+Please have a look at this [article series](https://www.angulararchitects.io/en/aktuelles/the-microfrontend-revolution-part-2-module-federation-with-angular/).
 
-Find out more about our work including Micro Frontends and Module Federation but also about alternatives to these approaches in our [blog](https://www.angulararchitects.io/en/aktuelles/the-microfrontend-revolution-part-2-module-federation-with-angular/).
+Even though these articles were written for Module Federation, thanks to the same API, they also apply to Native Federation.
 
 ## More: Angular Architecture Workshop (100% online, interactive)
 

package/builders.json

@@ -4,7 +4,7 @@
     "build": {
       "implementation": "./src/builders/build/builder",
       "schema": "./src/builders/build/schema.json",
-      "description": "build builder"
+      "description": "native federation builder"
     }
   }
 }

package/config.d.ts

@@ -1 +1 @@
-export * from './src/config';
+export * from './src/config';

package/config.js

@@ -1,5 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./src/config"), exports);
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./src/config"), exports);
 //# sourceMappingURL=config.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-architects/native-federation",
-  "version": "1.0.0-beta.1",
+  "version": "16.1.0",
   "main": "src/index.js",
   "generators": "./collection.json",
   "builders": "./builders.json",
@@ -15,23 +15,19 @@
     "url": "https://github.com/angular-architects/module-federation-plugin"
   },
   "dependencies": {
-    "@angular-architects/build-angular": "^14.2.0-next.0",
-    "@rollup/plugin-commonjs": "^22.0.2",
-    "@rollup/plugin-node-resolve": "^13.3.0",
-    "@rollup/plugin-replace": "^4.0.0",
-    "rollup": "^2.79.0",
-    "rollup-plugin-node-externals": "^4.1.1",
-    "esbuild": "^0.15.5",
     "@babel/core": "^7.19.0",
-    "@softarc/native-federation": "1.0.0",
-    "@softarc/native-federation-runtime": "1.0.0",
-    "@rollup/plugin-json": "^4.1.0",
-    "cross-spawn": "^7.0.3",
-    "rollup-plugin-terser": "^7.0.2",
-    "npmlog": "^6.0.2"
+    "@softarc/native-federation": "1.1.2",
+    "@softarc/native-federation-runtime": "1.1.2",
+    "@types/browser-sync": "^2.26.3",
+    "browser-sync": "^2.29.3",
+    "esbuild": "^0.18.12",
+    "mrmime": "^1.0.1",
+    "npmlog": "^6.0.2",
+    "process": "0.11.10",
+    "vite": "4.3.9"
   },
   "peerDependencies": {
-    "@angular/compiler-cli": "*"
+    "rxjs": ">=7.0.0"
   },
-  "typings": "./src/index.d.ts"
+  "types": "./src/index.d.ts"
 }

package/src/builders/build/builder.d.ts

@@ -1,5 +1,5 @@
-import { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
-import { Schema } from '@angular-architects/build-angular/src/builders/browser-esbuild/schema';
-export declare function runBuilder(options: Schema, context: BuilderContext): Promise<BuilderOutput>;
-declare const _default: import("@angular-devkit/architect/src/internal").Builder<Schema & import("@angular-devkit/core").JsonObject>;
-export default _default;
+import { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import { NfBuilderSchema } from './schema';
+export declare function runBuilder(nfOptions: NfBuilderSchema, context: BuilderContext): Promise<BuilderOutput>;
+declare const _default: import("@angular-devkit/architect/src/internal").Builder<NfBuilderSchema & import("@angular-devkit/core").JsonObject>;
+export default _default;