chore: Added docs for sharedMapping feature

Author: Aukevanoost

libs/native-federation/README.md

@@ -233,6 +233,34 @@ module.exports = withNativeFederation({
 
 > Our `init` schematic shown above generates this file for you.
 
+### Sharing Mapped Paths and Mapping Versions
+
+In monorepo setups, mapped paths from your `tsconfig` are shared by default. You can restrict this behavior via `sharedMappings`.
+
+If you additionally want to provide version metadata for mapped paths, enable `features.mappingVersion`.
+
+```javascript
+const { withNativeFederation, shareAll } = require('@angular-architects/native-federation/config');
+
+module.exports = withNativeFederation({
+  shared: {
+    ...shareAll({
+      singleton: true,
+      strictVersion: true,
+      requiredVersion: 'auto',
+    }),
+  },
+  sharedMappings: ['@my-org/auth-lib', '@my-org/ui/*'],
+  features: {
+    mappingVersion: true,
+  },
+});
+```
+
+If `sharedMappings` is omitted, all discovered mapped paths are shared. For more details, see [FAQ for Sharing Libraries](./docs/share-faq.md).
+
+`sharedMappings` reads mapped paths from the workspace root tsconfig file: `tsconfig.base.json` if it exists, otherwise `tsconfig.json`.
+
 ### Initializing the Host
 
 When bootstrapping the host (shell), Native Federation (`projects\shell\src\main.ts`) is initialized:

libs/native-federation/docs/share-faq.md

@@ -14,6 +14,59 @@ skip: [
 
 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.
 
+## Sharing Selected Mapped Paths with `sharedMappings`
+
+In Nx/monorepo setups, Native Federation shares all libraries from your `tsconfig` path mappings by default.
+
+If you only want to share selected mapped paths, you can use `sharedMappings` in your `federation.config.js`:
+
+```js
+module.exports = withNativeFederation({
+  shared: {
+    ...shareAll({
+      singleton: true,
+      strictVersion: true,
+      requiredVersion: 'auto',
+    }),
+  },
+  sharedMappings: ['@my-org/auth-lib', '@my-org/ui/*'],
+});
+```
+
+Notes:
+
+- `sharedMappings` is optional. If you omit it, all mapped paths are shared.
+- You can use wildcard suffixes (for example, `@my-org/ui/*`) to include multiple mapped paths.
+- `skip` still applies and can be used to exclude mapped paths even if they were selected via `sharedMappings`.
+- Mapped paths are read from the workspace root tsconfig file: `tsconfig.base.json` if present, otherwise `tsconfig.json`.
+- The workspace root is detected by searching upward from the current working directory until a `package.json` is found.
+
+## Mapping Versions via `features.mappingVersion`
+
+If your mapped paths point to libraries that have a `package.json` with a `version`, you can include this version in federation metadata by enabling `features.mappingVersion`.
+
+```js
+module.exports = withNativeFederation({
+  shared: {
+    ...shareAll({
+      singleton: true,
+      strictVersion: true,
+      requiredVersion: 'auto',
+    }),
+  },
+  sharedMappings: ['@my-org/auth-lib', '@my-org/ui/*'],
+  features: {
+    mappingVersion: true,
+  },
+});
+```
+
+Notes:
+
+- Default is `false`.
+- If enabled, Native Federation tries to read the version from the mapped library's nearest `package.json`.
+- If no `package.json` version is found for a mapping, the version remains empty.
+
 ## 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.