@angular-architects/native-federation 18.1.2 → 18.2.0

package/.eslintrc.json

@@ -0,0 +1,25 @@
+{
+  "extends": ["../../.eslintrc.base.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": "warn"
+      }
+    }
+  ]
+}

package/README.md

@@ -26,6 +26,7 @@ We will at least provide a new version of this package per Angular major. If nec
 - Use version 17.1.x for Angular 17.1+
 - Use version 18.x for Angular 18+
 - Use version 18.1.x for Angular 18.1+
+- Use version 18.2.x for Angular 18.2+
 
 ## Migration from Module Federation
 

package/docs/migrate.md

@@ -0,0 +1,173 @@
+# Migration Guide: Module Federation to Native Federation for Angular
+
+## Motivation
+
+Since Angular 17, the CLI ships with an esbuild-based builder that is remarkable faster than the original webpack-based solution. This new builder is used for newly generated projects and beginning with Angular 18 ng updates also migrates existing projects.
+
+Native Federation for Angular is a thin wrapper around the esbuild builder that allows to use the proven mental model of Module Federation.
+
+## Prerequisites
+
+- Update your solution to the newest Angular and CLI version
+- Update your solution to the newest version of `@angular-architects/module-federation` (!)
+- Have a look to our [FAQs about sharing packages with Native Federation](share-faq.md)
+
+In general, you need Native Federation for Angular 18.1 and Module Federation 18.x.
+
+## Migration for Angular CLI projects
+
+1. Remove Module Federation from your poject(s):
+
+   ```
+   ng g @angular-architects/module-federation:remove --project xyz
+   ```
+
+2. Update your workspace to the new esbuild-based build system:
+
+   ```
+   ng update @angular/cli --name use-application-builder
+   ```
+
+3. Initialize Native Federation for your projects:
+
+   ```
+   ng add @angular-architects/native-federation --project xyz --type remote --port 4201
+   ```
+
+   **Remarks:** Use type `remote` or type `dynamic-host`.
+
+4. Adjust your `federation.config.js` generated for Native Federation. You can mostly copy over the settings from your `webpack.config.js` used for Module Federation before.
+
+5. Update your EcmaScript imports in your source code. Make sure, you import from `@angular-architects/native-federation` instead of from `@angular-architects/module-federation`. Please also note that the signature of `loadRemoteModule` has been simplified:
+
+   ```typescript
+   // Before
+   import { loadRemoteModule } from '@angular-architects/module-federation';
+
+   [...]
+
+   export const APP_ROUTES: Routes = [
+       [...]
+       {
+       path: 'booking',
+       loadChildren: () =>
+           loadRemoteModule({
+           type: 'module',
+           remoteEntry: 'http://localhost:4201/remoteEntry.js',
+           exposedModule: './routes'
+           })
+           .then(m => m.MFE1_ROUTES)
+       },
+       [...]
+   ];
+   ```
+
+   ```typescript
+   // After
+   import { loadRemoteModule } from '@angular-architects/native-federation';
+
+   [...]
+
+   export const APP_ROUTES: Routes = [
+       [...]
+       {
+           path: 'flights',
+           loadComponent: () => loadRemoteModule('mfe1', './Component')
+               .then((m) => m.AppComponent),
+       },
+       [...]
+   ];
+   ```
+
+   Please also note that loadRemoteModule now always points to a logical name that is resolved via the shell's federation manifest (`src/assets/federation.manifest.json` or `public/federation.manifest.json`):
+
+   ```json
+   {
+     "mfe1": "http://localhost:4201/remoteEntry.json"
+   }
+   ```
+
+   Please also note that the remoteEntry is now a `.json` file.
+
+6. If everything works, delete your `webpack.config.js`
+
+## Migration for Nx projects
+
+1. Remove Module Federation from your poject(s):
+
+   ```
+   nx g @angular-architects/module-federation:remove --project xyz
+   ```
+
+2. Initialize Native Federation for your projects:
+
+   ```
+   npm i @angular-architects/native-federation
+
+   nx g @angular-architects/native-federation:init --project xyz --type remote --port 4201
+   ```
+
+   **Remarks:** Use type `remote` or type `dynamic-host`.
+
+3. Adjust your `federation.config.js` generated for Native Federation. You can mostly copy over the settings from your `webpack.config.js` used for Module Federation before.
+
+4. Update your EcmaScript imports in your source code. Make sure, you import from `@angular-architects/native-federation` instead of from `@angular-architects/module-federation`. Please also note that the signature of `loadRemoteModule` has been simplified:
+
+   ```typescript
+   // Before
+   import { loadRemoteModule } from '@angular-architects/module-federation';
+
+   [...]
+
+   export const APP_ROUTES: Routes = [
+       [...]
+       {
+       path: 'booking',
+       loadChildren: () =>
+           loadRemoteModule({
+           type: 'module',
+           remoteEntry: 'http://localhost:4201/remoteEntry.js',
+           exposedModule: './routes'
+           })
+           .then(m => m.MFE1_ROUTES)
+       },
+       [...]
+   ];
+   ```
+
+   ```typescript
+   // After
+   import { loadRemoteModule } from '@angular-architects/native-federation';
+
+   [...]
+
+   export const APP_ROUTES: Routes = [
+       [...]
+       {
+           path: 'flights',
+           loadComponent: () => loadRemoteModule('mfe1', './Component')
+               .then((m) => m.AppComponent),
+       },
+       [...]
+   ];
+   ```
+
+   Please also note that loadRemoteModule now always points to a logical name that is resolved via the shell's federation manifest (`src/assets/federation.manifest.json` or `public/federation.manifest.json`):
+
+   ```json
+   {
+     "mfe1": "http://localhost:4201/remoteEntry.json"
+   }
+   ```
+
+   Please also note that the remoteEntry is now a `.json` file.
+
+5. If everything works, delete your `webpack.config.js`
+
+## Module Federation Toolkit
+
+For Module Federation, we offered a simple toolkit helping with Multi Version/ Multi Framework scenarios. However, this toolkit was quite simple and can be implemented with just a few lines of code. To give you more flexibility, instead of providing a respective package for Native Federation, [here](https://www.angulararchitects.io/blog/micro-frontends-with-modern-angular-part-2-multi-version-and-multi-framework-solutions-with-angular-elements-and-web-components/) we describe how to implement such a functionality by yourself.
+
+## Issues
+
+We have tested this guide with several projects. However, each project is different. If you run into issues, feel free to let us know.

package/docs/share-faq.md

@@ -0,0 +1,57 @@
+# FAQ for Sharing Libraries
+
+## Information for Nx Users
+
+When using Nx, it's usual to subdivide an application into several libs. Libs that are only used by one application should not be shared via federation.
+
+As by default, all packages found in your `package.json` but also all libs in your workspace are shared, you should add such libraries to your skip list:
+
+```
+skip: [
+    '@my-scope/my-lib',
+]
+```
+
+This speeds up your build and the initial page load. Also, it gives you automatic page reloads within your application when changing the source code.
+
+## Using Multiple Framework Versions
+
+After compiling an Angular application, the compilation is accessing Angular's private API. As private APIs do not align with semver, there is no guarantee that your compiled application works with a different version of Angular. Even having a different minor or patch version at runtime can lead to issues.
+
+Hence, when using several versions or frameworks, you need to bootstrap each remote separately. Often, the individual Micro Frontends are abstracted, e.g., by using Web Components. Please find [more details about this here](https://www.angulararchitects.io/blog/micro-frontends-with-modern-angular-part-2-multi-version-and-multi-framework-solutions-with-angular-elements-and-web-components/).
+
+## Sharing "Old-Style" Packages
+
+To be useful in the long run, Native Federation fully leverages browser-native technologies like ESM and import maps. For this reason, old-style packages not following these standards can lead to challenges. In these cases, you might need to adjust your imports.
+
+A good example of such a classical package is `lodash`. When we looked into it the last time, it was still `commonjs` and not ESM-based. As `commonjs` can not be converted to ESM in all cases, we needed to adjust the imports as follows:
+
+```typescript
+// Works:
+import _ from 'lodash';
+
+// Does not work:
+// import * as _ from 'lodash';
+```
+
+Another solution is to find an ESM version of `lodash`.
+
+The **good message** is: Angular's Package format implemented by ng build for libraries addresses ESM. Hence, Angular-based libraries really work well with Native Federation.
+
+## ShareAll
+
+The shareAll helper used by default in the federatio.config.js makes your life far easier as it shares all dependencies found in your `package.json`. To optimize your build times and initial page loads, you can opt-out of sharing specific libraries by adding them to the above-mentioned `skip` list.
+
+While this is an option in most cases, you **need to** skip Node.js libraries as they cannot be compiled for usage within the browser. Examples of such libraries are `@angular/ssr` or `express`.
+
+## Hint: Skip and RegExp
+
+The skip list can contain a RegExp for excluding several entry points starting with the same name. This is especially interesting when using packages that come with several entry points, e.g. my-package/a and my-package/b. To skip all these entry points provided by my-package, you could use:
+
+```typescript
+skip: [
+  'this-package', // string-based entry
+  'that-package', // another string-based one
+  /^my-package/, // RegExp
+];
+```

package/docs/update18.md

@@ -0,0 +1,19 @@
+# Update to Native Federation for Angular 18
+
+The package `@angular-architects/native-federation` version 18 was successfully tested with Angular 18.
+
+## Option 1
+
+Just use `ng update`:
+
+```
+ng update @angular-architects/native-federation
+```
+
+## Option 2
+
+Use npm install:
+
+```
+npm i @angular-architects/native-federation@^18
+```

package/jest.config.ts

@@ -0,0 +1,11 @@
+/* eslint-disable */
+export default {
+  displayName: 'native-federation',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/native-federation',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-architects/native-federation",
-  "version": "18.1.2",
+  "version": "18.2.0",
   "main": "src/index.js",
   "generators": "./collection.json",
   "builders": "./builders.json",
@@ -29,7 +29,5 @@
     "npmlog": "^6.0.2",
     "process": "0.11.10"
   },
-  "peerDependencies": {},
-  "type": "commonjs",
-  "types": "./src/index.d.ts"
-}
+  "peerDependencies": {}
+}

package/post-build.js

@@ -0,0 +1,10 @@
+const fs = require('fs');
+const path = require('path');
+
+const index = fs.readFileSync(path.join(__dirname, 'src/index.ts'), {
+  encoding: 'utf-8',
+});
+fs.writeFileSync(
+  path.join(__dirname, '../../dist/libs/native-federation/src/index.js'),
+  index
+);

package/project.json

@@ -0,0 +1,80 @@
+{
+  "name": "native-federation",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/native-federation/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/native-federation",
+        "main": "libs/native-federation/src/index.ts",
+        "tsConfig": "libs/native-federation/tsconfig.lib.json",
+        "assets": [
+          "libs/native-federation/*.md",
+          "libs/native-federation/LICENSE",
+          {
+            "input": "./libs/native-federation/src",
+            "glob": "**/!(*.ts)",
+            "output": "./src"
+          },
+          {
+            "input": "./libs/native-federation/src",
+            "glob": "**/*.d.ts",
+            "output": "./src"
+          },
+          {
+            "input": "./libs/native-federation",
+            "glob": "generators.json",
+            "output": "."
+          },
+          {
+            "input": "./libs/native-federation",
+            "glob": "builders.json",
+            "output": "."
+          },
+          {
+            "input": "./libs/native-federation",
+            "glob": "migration-collection.json",
+            "output": "."
+          },
+          {
+            "input": "./libs/native-federation",
+            "glob": "executors.json",
+            "output": "."
+          },
+          {
+            "input": "./libs/native-federation",
+            "glob": "collection.json",
+            "output": "."
+          }
+        ]
+      }
+    },
+    "post-build": {
+      "dependsOn": ["build"],
+      "executor": "nx:run-commands",
+      "outputs": ["{options.outputPath}/src/index.js"],
+      "options": {
+        "cwd": "libs/native-federation",
+        "command": "node post-build.js"
+      }
+    },
+    "publish": {
+      "dependsOn": ["build", "post-build"],
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "node tools/scripts/publish.mjs native-federation npm {args.ver} {args.tag}"
+      }
+    },
+    "publish-local": {
+      "dependsOn": ["build", "post-build"],
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "node tools/scripts/publish.mjs native-federation verdaccio {args.ver}"
+      }
+    }
+  },
+  "tags": ["org:angular-architects", "scope:nf"]
+}