@softarc/native-federation 4.5.0-next.1 → 4.5.0

package/README.md

@@ -363,7 +363,7 @@ shared: share({
 })
 ```
 
-Finally, it's also possible to break out of the `ignoreUnusedDeps` feature for specific externals if desired, for example when sharing a whole suite of interconnected external dependencies like @angular/core. This can be handy when you want to avoid the chance of cross-version secondary entrypoints being used by the different micro frontends. E.g. mfe1 uses @angular/core v20.1.0 and mfe2 uses @angular/core/rxjs-interop v20.0.8, then you might want consistent use of v20.1.0 so rxjs-interop should be exported by mfe1. The `keepAll` prop allows you to enforce this:
+Finally, it's also possible to exempt the secondary entry points of a specific external from the `ignoreUnusedDeps` feature, for example when sharing a whole suite of interconnected external dependencies like @angular/core. This can be handy when you want to avoid the chance of cross-version secondary entrypoints being used by the different micro frontends. E.g. mfe1 uses @angular/core v20.1.0 and mfe2 uses @angular/core/rxjs-interop v20.0.8, then you might want consistent use of v20.1.0 so rxjs-interop should be exported by mfe1. The `keepAll` prop allows you to enforce this:
 
 ```typescript
 shared: share({
@@ -377,6 +377,10 @@ shared: share({
 })
 ```
 
+`keepAll` is read per **package family**, not per entry point: every entry point of @angular/core is published as long as _something_ still reaches @angular/core, but a package nothing imports at all is pruned anyway. That is what keeps the feature meaningful when `keepAll` is applied to every package at once — it exempts the secondaries from reachability, not the package itself. For a package with no secondary entry points the family is the package itself, so the flag changes nothing there. Use `ignoreUnusedDeps: false` to publish everything unconditionally.
+
+Note that mapped paths read the same flag differently: there, `keepAll` opts the mapping out of reachability entirely (see [Keeping mappings that nothing imports](#keeping-mappings-that-nothing-imports)).
+
 The API for configuring and using Native Federation is very similar to the one provided by our Module Federation plugin [@angular-architects/module-federation](https://www.npmjs.com/package/@angular-architects/module-federation). Hence, most of the articles on it are also valid for Native Federation.
 
 ### Sharing
@@ -487,7 +491,7 @@ module.exports = withNativeFederation({
 });
 ```
 
-- `keepAll` keeps the mapping even when nothing imports it. This is read exactly as it is for a shared package, so a bare `includeSecondaries: true` opts out too.
+- `keepAll` keeps the mapping even when nothing imports it, and on a mapping a bare `includeSecondaries: true` means the same thing — a mapping has no secondary entry points, so the flag can only mean "exempt from reachability". A shared package reads it differently: `true` is the default there and only means "share the secondaries", so `{ keepAll: true }` is the only spelling that affects pruning — and even then the package itself still has to be reached.
 - `resolveGlob` is additionally required for **wildcard** mappings. A wildcard is a pattern rather than an entry point, and normally only the reachability scan turns it into concrete files; `resolveGlob` expands it against the filesystem instead. Without it, a wildcard mapping is dropped with a warning.
 
 An expanded wildcard is named by the same rule the reachability scan uses, so `libs/ui/*` matching `libs/ui/button/index.ts` is shared as `@my-org/ui/button`.
@@ -496,7 +500,7 @@ Expansion only accepts **entry points**. A glob cannot tell a library's public s
 
 That restriction is not cosmetic: **only barrel imports can be shared as a mapped path.** A mapped path is advertised under its import specifier and marked external, so the specifier has to be one a browser import map can resolve, and a dot in the last segment does not resolve (see [vitejs/vite#21036](https://github.com/vitejs/vite/issues/21036)).
 
-So the rule is simply *would this end up in `remoteEntry.json`?* If it would, a non-barrel specifier fails the build:
+So the rule is simply _would this end up in `remoteEntry.json`?_ If it would, a non-barrel specifier fails the build:
 
 ```
 Invalid 'shared mappings' config. Only barrel imports can be shared as a sharedMapping:
@@ -693,7 +697,7 @@ For a zero-build integration, declare your remotes in a manifest and include the
 </script>
 
 <!-- Include the orchestrator -->
-<script src="https://unpkg.com/@softarc/native-federation-orchestrator@4.5.1/quickstart.mjs"></script>
+<script src="https://unpkg.com/@softarc/native-federation-orchestrator@4.6.0/quickstart.mjs"></script>
 ```
 
 The `mfe-loader-available` event signals that the orchestrator has fetched the

package/dist/lib/config/remove-unused-deps.js

@@ -3,9 +3,13 @@ import {
   expandWildcardMapping,
   isWildcardMapping
 } from "./expand-mappings.js";
+import { inferPackageFromSecondary } from "../utils/normalize.js";
 import { logger } from "../utils/logger.js";
 function removeUnusedDeps(usedDependencies, config, ctx) {
-  const filteredDependencies = Object.entries(config.shared).filter(([shared, meta]) => !!meta.includeSecondaries || usedDependencies.external.has(shared)).reduce((acc, [shared, meta]) => ({ ...acc, [shared]: meta }), {});
+  const usedPackages = new Set([...usedDependencies.external].map(inferPackageFromSecondary));
+  const filteredDependencies = Object.entries(config.shared).filter(
+    ([shared, meta]) => meta.includeSecondaries ? usedPackages.has(inferPackageFromSecondary(shared)) : usedDependencies.external.has(shared)
+  ).reduce((acc, [shared, meta]) => ({ ...acc, [shared]: meta }), {});
   const sharedMappings = withoutSkippedMappings(
     { ...keptMappings(config, ctx), ...usedDependencies.internal },
     config.skip

package/dist/lib/core/build/build-for-federation.js

@@ -6,9 +6,11 @@ import { logger } from "../../utils/logger.js";
 import { AbortedError } from "../../utils/errors.js";
 import { addExternalsToCache } from "../cache/federation-cache.js";
 import { planSharedBundles } from "./shared-bundle-plan.js";
+import { hintUnwatchedLinkedDeps } from "./resolve-shared-dirs.js";
 async function buildForFederation(config, fedOptions, externals, signal) {
   logger.info("Building federation artifacts");
   logger.notice("Skip packages you don't want to share in your federation config");
+  hintUnwatchedLinkedDeps(config, fedOptions);
   await executeSharedBundlePlans(planSharedBundles(config, externals), config, fedOptions, signal);
   const start = process.hrtime();
   const artifactInfo = await bundleExposedAndMappings(

package/dist/lib/core/build/resolve-shared-dirs.d.ts

@@ -8,6 +8,9 @@ export declare function resolveSharedPackageDirs(config: NormalizedFederationCon
 /** Realpath'd dirs of symlinked shared packages — the bounded watch set.
  *  Deduped, since secondaries share a package dir. Empty unless `watchLinkedDeps` is on. */
 export declare function linkedSharedDirs(config: NormalizedFederationConfig, fedOptions: NormalizedFederationOptions, io?: FileReaderPort, repo?: PackageJsonRepository): string[];
+/** Names the npm-linked shared packages a watching build leaves unwatched -- see
+ *  AGENTS.md "What to watch". Advisory only, so a resolution failure must not fail the build. */
+export declare function hintUnwatchedLinkedDeps(config: NormalizedFederationConfig, fedOptions: NormalizedFederationOptions, io?: FileReaderPort, repo?: PackageJsonRepository): void;
 /**
  * Source directories of the workspace libs in `config.sharedMappings` — the watch set
  * for mappings, derived from config alone rather than from a bundler cache.

package/dist/lib/core/build/resolve-shared-dirs.js

@@ -1,6 +1,10 @@
 import * as path from "path";
 import { nodeIo } from "../../utils/io/node-io-adapter.js";
-import { sharedPackageJsonRepository } from "../../utils/package/package-info.js";
+import { logger } from "../../utils/logger.js";
+import {
+  getPkgFolder,
+  sharedPackageJsonRepository
+} from "../../utils/io/package-json-repository.js";
 import { isOutsideNodeModules, isUnderDir, toPosix } from "../../utils/path-patterns.js";
 const folderOf = (fedOptions) => fedOptions.packageJson ? path.dirname(fedOptions.packageJson) : fedOptions.workspaceRoot;
 function resolveEntries(keys, folder, io, repo) {
@@ -28,6 +32,27 @@ function linkedSharedDirs(config, fedOptions, io = nodeIo, repo = sharedPackageJ
   const entries = resolveEntries(Object.keys(config.shared), folderOf(fedOptions), io, repo);
   return [...new Set(entries.filter((e) => e.isLinkedCheckout).map((e) => e.realDir))];
 }
+function hintUnwatchedLinkedDeps(config, fedOptions, io = nodeIo, repo = sharedPackageJsonRepository) {
+  if (!fedOptions.watch || fedOptions.watchLinkedDeps) return;
+  try {
+    const names = /* @__PURE__ */ new Map();
+    for (const entry of resolveEntries(
+      Object.keys(config.shared),
+      folderOf(fedOptions),
+      io,
+      repo
+    )) {
+      if (entry.isLinkedCheckout && !names.has(entry.realDir)) {
+        names.set(entry.realDir, getPkgFolder(entry.key));
+      }
+    }
+    if (names.size === 0) return;
+    logger.notice(
+      `Detected npm-linked shared packages: ${[...names.values()].join(", ")}. Set 'watchLinkedDeps' to true to rebuild when they change.`
+    );
+  } catch {
+  }
+}
 function sharedMappingDirs(config) {
   const dirs = Object.keys(config.sharedMappings).map((entryPoint) => toPosix(path.dirname(entryPoint))).filter(isOutsideNodeModules);
   return [...new Set(dirs)];
@@ -77,6 +102,7 @@ function affectedSharedKeys(modifiedFiles, dirs, io = nodeIo) {
 }
 export {
   affectedSharedKeys,
+  hintUnwatchedLinkedDeps,
   linkedContentSignals,
   linkedSharedDirs,
   resolveSharedPackageDirs,

package/dist/lib/core/normalize-options.js

@@ -59,7 +59,7 @@ async function normalizeFederationOptionsCore(deps, options, cache) {
     });
     logger.info("Removed unused dependencies.");
     logger.debug(
-      'This can be disabled per dependency/external using the "includeSecondaries: {keepAll: true}" property. Or in general by disabling the "ignoreUnusedDeps" feature. '
+      'Keep everything with "ignoreUnusedDeps: false", or one mapping with "includeSecondaries: {keepAll: true}". On a shared package that flag only keeps the secondaries of a package something still imports.'
     );
   } else {
     config.sharedMappings = expandOrDropWildcards(config, {

package/dist/lib/domain/config/federation-config.contract.d.ts

@@ -14,9 +14,9 @@ export type SharedMappingConfigs = Record<string, ExternalConfig>;
  * have nothing to select. `requiredVersion` and `version` stay optional because their
  * defaults are read from the mapped lib's package.json at build time.
  *
- * `includeSecondaries` collapses to a boolean exactly as it does for a shared external:
- * it means "exempt from `ignoreUnusedDeps` pruning". `resolveGlob` is lifted out of it
- * because a mapping has no secondary entry points for it to apply to.
+ * `includeSecondaries` collapses to a boolean meaning "exempt from `ignoreUnusedDeps`
+ * pruning" — stronger than on a shared external, where it only exempts the secondaries.
+ * `resolveGlob` is lifted out of it because a mapping has no secondaries to apply it to.
  */
 export interface NormalizedMappingConfig {
     singleton: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softarc/native-federation",
-  "version": "4.5.0-next.1",
+  "version": "4.5.0",
   "type": "module",
   "license": "MIT",
   "packageManager": "pnpm@11.18.0",
@@ -26,7 +26,7 @@
     "eslint": "^10.4.1",
     "globals": "^17.3.0",
     "jiti": "^2.6.1",
-    "jsdom": "^29.0.0",
+    "jsdom": "^30.0.0",
     "knip": "^6.26.0",
     "prettier": "^3.9.4",
     "tslib": "^2.3.0",