add migration guide

Author: manfredsteyer

libs/native-federation/docs/migrate.md

@@ -0,0 +1,21 @@
+# 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)
+
+## Migration for Angular CLI projects
+
+## Migration for Nx projects
+
+## Issues
+
+We have tested this guide with several projects. However, e

libs/native-federation/docs/update18.md

@@ -27,7 +27,7 @@ Make sure you have the following `postinstall` script in your `package.json`:
 },
 ```
 
-**Remarks:** This script is just a temporary solution. It won't be necessary in future versions.
+**Remarks:** This script is just a temporary solution. It won't be necessary in future versions. 
 
 Run the `postinstall` script once manually for initialization:
 

libs/native-federation/src/schematics/init/schematic.ts

@@ -29,6 +29,7 @@ type NormalizedOptions = {
   projectRoot: string;
   projectSourceRoot: string;
   manifestPath: string;
+  manifestRelPath: string;
   projectConfig: any;
   main: string;
   port: number;
@@ -65,14 +66,15 @@ export default function config(options: MfSchematicSchema): Rule {
     const workspaceFileName = getWorkspaceFileName(tree);
     const workspace = JSON.parse(tree.read(workspaceFileName).toString('utf8'));
 
-    const normalized = normalizeOptions(options, workspace);
+    const normalized = normalizeOptions(options, workspace, tree);
 
     const {
       polyfills,
       projectName,
       projectRoot,
       projectSourceRoot,
       manifestPath,
+      manifestRelPath,
       main,
     } = normalized;
 
@@ -90,11 +92,11 @@ export default function config(options: MfSchematicSchema): Rule {
 
     const generateRule = !exists
       ? await generateFederationConfig(
-          remoteMap,
-          projectRoot,
-          projectSourceRoot,
-          options
-        )
+        remoteMap,
+        projectRoot,
+        projectSourceRoot,
+        options
+      )
       : noop;
 
     updateWorkspaceConfig(tree, normalized, workspace, workspaceFileName);
@@ -112,11 +114,11 @@ export default function config(options: MfSchematicSchema): Rule {
 
     context.addTask(new NodePackageInstallTask());
 
-    return chain([generateRule, makeMainAsync(main, options, remoteMap)]);
+    return chain([generateRule, makeMainAsync(main, options, remoteMap, manifestRelPath)]);
   };
 }
 
-export function patchAngularBuild(tree) {
+export function patchAngularBuild(tree: Tree) {
   const packagePath = 'node_modules/@angular/build/package.json';
   const privatePath = 'node_modules/@angular/build/private.js';
 
@@ -125,17 +127,26 @@ export function patchAngularBuild(tree) {
   }
 
   const packageJson = JSON.parse(
-    tree.read(packagePath)
+    tree.read(packagePath).toString('utf8')
   );
   patchAngularBuildPackageJson(packageJson);
   tree.overwrite(
     packagePath,
     JSON.stringify(packageJson, null, 2)
   );
-  tree.overwrite(
-    privatePath,
-    privateEntrySrc
-  );
+
+  if (!tree.exists(privatePath)) {
+    tree.create(
+      privatePath,
+      privateEntrySrc
+    );
+  }
+  else {
+    tree.overwrite(
+      privatePath,
+      privateEntrySrc
+    );
+  }
 
 }
 
@@ -164,18 +175,14 @@ function updateWorkspaceConfig(
     delete originalBuild.configurations?.development?.vendorChunk;
   }
 
-  // if (originalBuild.options.browser) {
-  //   const browser = originalBuild.options.browser;
-  //   delete originalBuild.options.browser;
-  //   originalBuild.options.main = browser;
-  // }
-
   if (originalBuild.options.main) {
     const main = originalBuild.options.main;
     delete originalBuild.options.main;
     originalBuild.options.browser = main;
   }
 
+  delete originalBuild.options.commonChunk;
+
   projectConfig.architect.esbuild = originalBuild;
 
   projectConfig.architect.build = {
@@ -197,6 +204,8 @@ function updateWorkspaceConfig(
   serve.options ??= {};
   serve.options.port = port;
 
+  delete serve.options.commonChunk;
+
   const serveProd = projectConfig.architect.serve.configurations?.production;
   if (serveProd) {
     serveProd.buildTarget = `${projectName}:esbuild:production`;
@@ -237,7 +246,8 @@ function updateWorkspaceConfig(
 
 function normalizeOptions(
   options: MfSchematicSchema,
-  workspace: any
+  workspace: any,
+  tree: Tree
 ): NormalizedOptions {
   if (!options.project) {
     options.project = workspace.defaultProject;
@@ -271,10 +281,22 @@ function normalizeOptions(
     '/'
   );
 
-  const manifestPath = path
-    .join(projectRoot, 'public/federation.manifest.json')
+  const publicPath = path.join(projectRoot, 'public').replace(/\\/g, '/');
+
+  let manifestPath = path
+    .join(publicPath, 'federation.manifest.json')
     .replace(/\\/g, '/');
 
+  let manifestRelPath = 'public/federation.manifest.json';
+
+  if (!tree.exists(publicPath)) {
+    manifestPath = path
+      .join(projectRoot, 'src/assets/federation.manifest.json')
+      .replace(/\\/g, '/');
+
+    manifestRelPath = 'assets/federation.manifest.json';
+  }
+
   const main =
     projectConfig.architect.build.options.main ||
     projectConfig.architect.build.options.browser;
@@ -283,13 +305,20 @@ function normalizeOptions(
     projectConfig.architect.build.options.polyfills = [];
   }
 
+  if (typeof projectConfig.architect.build.options.polyfills === 'string') {
+    projectConfig.architect.build.options.polyfills = [
+      projectConfig.architect.build.options.polyfills
+    ]
+  }
+
   const polyfills = projectConfig.architect.build.options.polyfills;
   return {
     polyfills,
     projectName,
     projectRoot,
     projectSourceRoot,
     manifestPath,
+    manifestRelPath,
     projectConfig,
     main,
     port: +(options.port || 4200),
@@ -353,7 +382,8 @@ function generateRemoteMap(workspace: any, projectName: string) {
 function makeMainAsync(
   main: string,
   options: MfSchematicSchema,
-  remoteMap: unknown
+  remoteMap: unknown,
+  manifestRelPath: string,
 ): Rule {
   return async function (tree) {
     const mainPath = path.dirname(main);
@@ -371,7 +401,7 @@ function makeMainAsync(
     if (options.type === 'dynamic-host') {
       newMainContent = `import { initFederation } from '@angular-architects/native-federation';
 
-initFederation('federation.manifest.json')
+initFederation('${manifestRelPath}')
   .catch(err => console.error(err))
   .then(_ => import('./bootstrap'))
   .catch(err => console.error(err));