feat(nf): add shareAngularLocales helper

Author: manfredsteyer

libs/native-federation-core/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@softarc/native-federation",
-  "version": "2.0.25",
+  "version": "2.0.26",
   "type": "commonjs",
   "license": "MIT",
   "dependencies": {
     "json5": "^2.2.0",
     "npmlog": "^6.0.2",
-    "@softarc/native-federation-runtime": "2.0.25"
+    "@softarc/native-federation-runtime": "2.0.26"
   }
 }

libs/native-federation-core/src/build.ts

@@ -1,6 +1,9 @@
 export { DEFAULT_SKIP_LIST } from './lib/core/default-skip-list';
 
-export { NormalizedFederationConfig } from './lib/config/federation-config';
+export {
+  NormalizedFederationConfig,
+  SharedConfig,
+} from './lib/config/federation-config';
 export { FederationOptions } from './lib/core/federation-options';
 export { setBuildAdapter } from './lib/core/build-adapter';
 export { writeImportMap } from './lib/core/write-import-map';

libs/native-federation-esbuild/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softarc/native-federation-esbuild",
-  "version": "2.0.25",
+  "version": "2.0.26",
   "type": "commonjs",
   "dependencies": {
     "@rollup/plugin-commonjs": "^22.0.2",

libs/native-federation-node/package.json

@@ -1,4 +1,4 @@
 {
   "name": "@softarc/native-federation-node",
-  "version": "2.0.25"
+  "version": "2.0.26"
 }

libs/native-federation-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softarc/native-federation-runtime",
-  "version": "2.0.25",
+  "version": "2.0.26",
   "dependencies": {
     "tslib": "^2.3.0"
   },

libs/native-federation/README.md

@@ -334,6 +334,38 @@ ng serve shell -o
 
 Now, by clicking at the 2nd menu item, you can load the remote directly into the host.
 
+## Advanced Use Cases
+
+### SSR and Hydration
+
+We support Angular's SSR and (Incremental) Hydration. Please find [more information here](https://www.angulararchitects.io/blog/ssr-and-hydration-with-native-federation-for-angular/).
+
+### Native Federation and Module Federation
+
+We support combining Native Federation with Module Federation. Please find [more information here](https://www.angulararchitects.io/blog/combining-native-federation-and-module-federation/).
+
+### Angular I18N
+
+Since version 19.0.13, Native Federation for Angular supports Angular I18N. Here are some things to keep in mind:
+
+- Make sure, you also add I18N support to your shell (e.g., `ng add @angular/localize --project shell`)
+- Configure I18N in your `angular.json`. Don’t use command line parameters (as the Native Federation Builder does not forward them to the ApplicationBuilder by design)
+- In production, make sure your `federation.manifest.json` points to the right language versions of your remotes
+
+### Angular Localization
+
+To just build the localization files you need for federation, you can use the `shareAngularLocales` introduced with version 19.0.14:
+
+```js
+module.exports = withNativeFederation({
+  [...],
+  shared: {
+    ...shareAll({ singleton: true, strictVersion: true, requiredVersion: 'auto' }),
+    ...shareAngularLocales(['en', 'de', 'fr']),
+  }
+});
+```
+
 ## FAQ
 
 ### When to use this package?

libs/native-federation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-architects/native-federation",
-  "version": "19.0.13",
+  "version": "19.0.15",
   "main": "src/index.js",
   "generators": "./collection.json",
   "builders": "./builders.json",
@@ -20,8 +20,8 @@
   },
   "dependencies": {
     "@babel/core": "^7.19.0",
-    "@softarc/native-federation": "2.0.25",
-    "@softarc/native-federation-runtime": "2.0.25",
+    "@softarc/native-federation": "2.0.26",
+    "@softarc/native-federation-runtime": "2.0.26",
     "@types/browser-sync": "^2.29.0",
     "@chialab/esbuild-plugin-commonjs": "^0.18.0",
     "browser-sync": "^3.0.2",

libs/native-federation/src/builders/build/builder.ts

@@ -44,8 +44,11 @@ import { createSharedMappingsPlugin } from '../../utils/shared-mappings-plugin';
 // import { NextHandleFunction } from 'vite';
 import { PluginBuild } from 'esbuild';
 import { FederationInfo } from '@softarc/native-federation-runtime';
-import { getI18nConfig, translateFederationArtefacts } from '../../utils/i18n';
-import { createOrUpdateGithubRelease } from 'nx/src/command-line/release/utils/github';
+import {
+  getI18nConfig,
+  I18nConfig,
+  translateFederationArtefacts,
+} from '../../utils/i18n';
 
 function _buildApplication(options, context, pluginsOrExtensions) {
   let extensions;
@@ -147,12 +150,20 @@ export async function* runBuilder(
 
   const i18n = await getI18nConfig(context);
 
+  const localeFilter = getLocaleFilter(options, runServer);
+
   const browserOutputPath = path.join(
     outputOptions.base,
     outputOptions.browser,
-    i18n?.sourceLocale || ''
+    options.localize ? i18n?.sourceLocale || '' : ''
   );
 
+  const differentDevServerOutputPath =
+    Array.isArray(localeFilter) && localeFilter.length === 1;
+  const devServerOutputPath = !differentDevServerOutputPath
+    ? browserOutputPath
+    : path.join(outputOptions.base, outputOptions.browser, options.localize[0]);
+
   const fedOptions: FederationOptions = {
     workspaceRoot: context.workspaceRoot,
     outputPath: browserOutputPath,
@@ -192,7 +203,7 @@ export async function* runBuilder(
 
       const fileName = path.join(
         fedOptions.workspaceRoot,
-        fedOptions.outputPath,
+        devServerOutputPath,
         url
       );
 
@@ -246,8 +257,13 @@ export async function* runBuilder(
   }
 
   const hasLocales = i18n?.locales && Object.keys(i18n.locales).length > 0;
-  if (!runServer && hasLocales) {
-    translateFederationArtefacts(i18n, outputOptions.base, federationResult);
+  if (hasLocales && localeFilter) {
+    translateFederationArtefacts(
+      i18n,
+      localeFilter,
+      outputOptions.base,
+      federationResult
+    );
   }
 
   options.deleteOutputPath = false;
@@ -306,7 +322,21 @@ export async function* runBuilder(
     if (!first && (nfOptions.dev || watch)) {
       setTimeout(async () => {
         try {
-          await buildForFederation(config, fedOptions, externals);
+          federationResult = await buildForFederation(
+            config,
+            fedOptions,
+            externals
+          );
+
+          if (hasLocales && localeFilter) {
+            translateFederationArtefacts(
+              i18n,
+              localeFilter,
+              outputOptions.base,
+              federationResult
+            );
+          }
+
           logger.info('Done!');
         } catch {
           logger.error('Not successful!');
@@ -327,6 +357,22 @@ export async function* runBuilder(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default createBuilder(runBuilder) as any;
 
+function getLocaleFilter(
+  options: ApplicationBuilderOptions,
+  runServer: boolean
+) {
+  let localize = options.localize || false;
+
+  if (runServer && Array.isArray(localize) && localize.length > 1) {
+    localize = false;
+  }
+
+  if (runServer && localize === true) {
+    localize = false;
+  }
+  return localize;
+}
+
 function removeBaseHref(req: any, baseHref?: string) {
   let url = req.url;
 

libs/native-federation/src/config.ts

@@ -5,3 +5,5 @@ export {
   shareAll,
   DEFAULT_SKIP_LIST,
 } from '@softarc/native-federation/build';
+
+export { shareAngularLocales } from './utils/angular-locales';

libs/native-federation/src/utils/angular-esbuild-adapter.ts

@@ -432,7 +432,7 @@ function setNgServerMode(): void {
       if (!content.includes(lineToAdd)) {
         content = lineToAdd + '\n' + content;
         fs.writeFileSync(fileToPatch, content);
-      } 
+      }
     }
   } catch (e) {
     console.error(

libs/native-federation/src/utils/angular-locales.ts

@@ -0,0 +1,23 @@
+import { share, SharedConfig } from '@softarc/native-federation/build';
+
+export function shareAngularLocales(
+  keys,
+  config: SharedConfig = {
+    singleton: true,
+    strictVersion: true,
+    requiredVersion: 'auto',
+  }
+) {
+  return keys.reduce((acc, key) => {
+    acc[`@angular/common/locales/${key}`] = {
+      ...config,
+      packageInfo: config.packageInfo || {
+        ...config.packageInfo,
+        entryPoint:
+          config.packageInfo?.entryPoint ||
+          `node_modules/@angular/common/locales/${key}.mjs`,
+      },
+    };
+    return share(acc);
+  }, {});
+}

libs/native-federation/src/utils/i18n.ts

@@ -27,21 +27,29 @@ export async function getI18nConfig(
 
 export async function translateFederationArtefacts(
   i18n: I18nConfig,
+  localize: boolean | string[],
   outputPath: string,
   federationResult: FederationInfo
 ) {
+  const neededLocales = Array.isArray(localize)
+    ? localize
+    : Object.keys(i18n.locales);
+
+  const locales = Object.keys(i18n.locales).filter((locale) =>
+    neededLocales.includes(locale)
+  );
+
+  if (locales.length === 0) {
+    return;
+  }
 
   logger.info('Writing Translations');
 
-  const translationFiles =
-    '"' +
-    Object.values(i18n.locales || {})
-      .map((value) => JSON.stringify(value))
-      .join(' ')
-      .replace(/"/g, '') +
-    '"';
+  const translationFiles = locales
+    .map((loc) => i18n.locales[loc])
+    .map((value) => JSON.stringify(value))
+    .join(' ');
 
-  const locales = Object.keys(i18n.locales);
   const targetLocales = locales.join(' ');
 
   const sourceLocale = i18n.sourceLocale;
@@ -57,11 +65,7 @@ export async function translateFederationArtefacts(
   // to improve performance
   const sourcePattern = '{' + federationFiles.join(',') + '}';
 
-  const sourceLocalePath = path.join(
-    outputPath,
-    'browser',
-    sourceLocale,
-  );
+  const sourceLocalePath = path.join(outputPath, 'browser', sourceLocale);
 
   const cmd = `node node_modules/.bin/localize-translate -r ${sourceLocalePath} -s "${sourcePattern}" -t ${translationFiles} -o ${translationOutPath} --target-locales ${targetLocales} -l ${sourceLocale}`;
 
@@ -74,26 +78,35 @@ export async function translateFederationArtefacts(
 }
 
 function execCommand(cmd: string, defaultSuccessInfo: string) {
-    try {
-        const output = execSync(cmd);
-        logger.info(output.toString() || defaultSuccessInfo);
-    } catch (error) {
-        logger.error(error.message);
-    }
+  try {
+    const output = execSync(cmd);
+    logger.info(output.toString() || defaultSuccessInfo);
+  } catch (error) {
+    logger.error(error.message);
+  }
 }
 
-function copyRemoteEntry(locales: string[], outputPath: string, sourceLocalePath: string) {
-    const remoteEntry = path.join(sourceLocalePath, 'remoteEntry.json');
-
-    for (const locale of locales) {
-        const localePath = path.join(outputPath, 'browser', locale, 'remoteEntry.json');
-        fs.copyFileSync(remoteEntry, localePath);
-    }
+function copyRemoteEntry(
+  locales: string[],
+  outputPath: string,
+  sourceLocalePath: string
+) {
+  const remoteEntry = path.join(sourceLocalePath, 'remoteEntry.json');
+
+  for (const locale of locales) {
+    const localePath = path.join(
+      outputPath,
+      'browser',
+      locale,
+      'remoteEntry.json'
+    );
+    fs.copyFileSync(remoteEntry, localePath);
+  }
 }
 
 function ensureDistFolders(locales: string[], outputPath: string) {
-    for (const locale of locales) {
-        const localePath = path.join(outputPath, 'browser', locale);
-        fs.mkdirSync(localePath, { recursive: true })
-    }
+  for (const locale of locales) {
+    const localePath = path.join(outputPath, 'browser', locale);
+    fs.mkdirSync(localePath, { recursive: true });
+  }
 }