@module-federation/utilities 3.0.4 → 3.0.5

package/README.md

@@ -0,0 +1,146 @@
+# utils
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build utils` to build the library.
+
+## Running unit tests
+
+Run `nx test utils` to execute the unit tests via [Jest](https://jestjs.io).
+
+## React utilities
+
+---
+
+`FederatedBoundary`
+
+A component wrapper that provides a fallback for safe imports if something were to fail when grabbing a module off of a remote host.
+
+This wrapper also exposes an optional property for a custom react error boundary component.
+
+Any extra props will be passed directly to the imported module.
+
+Usage looks something like this:
+
+```js
+import { FederationBoundary } from '@module-federation/utilities/src/utils/react';
+
+// defining dynamicImport and fallback outside the Component to keep the component identity
+// another alternative would be to use useMemo
+const dynamicImport = () => import('some_remote_host_name').then((m) => m.Component);
+const fallback = () => import('@npm/backup').then((m) => m.Component);
+
+const MyPage = () => {
+  return <FederationBoundary dynamicImporter={dynamicImport} fallback={fallback} customBoundary={CustomErrorBoundary} />;
+};
+```
+
+---
+
+`ImportRemote`
+
+A function which will enable dynamic imports of remotely exposed modules using the Module Federation plugin. It uses the method described in the official Webpack configuration under <a href="https://webpack.js.org/concepts/module-federation/#dynamic-remote-containers" target="_blank">Dynamic Remote Containers</a>.
+
+This function will allow you to provide a static url or an async method to retrieve a url from a configuration service.
+
+Usage looks something like this:
+
+```js
+import { importRemote } from '@module-federation/utilities';
+
+// --
+// If it's a regular js module:
+// --
+importRemote({
+  url: 'http://localhost:3001',
+  scope: 'Foo',
+  module: 'Bar',
+}).then(
+  (
+    {
+      /* list of Bar exports */
+    },
+  ) => {
+    // Use Bar exports
+  },
+);
+
+// --
+// If it's a ESM module (this is currently the default for NX):
+// --
+const Bar = lazy(() => importRemote({ url: 'http://localhost:3001', scope: 'Foo', module: 'Bar', esm: true }));
+
+return (
+  <Suspense fallback={<div>Loading Bar...</div>}>
+    <Bar />
+  </Suspense>
+);
+
+// --
+// If Bar is a React component you can use it with lazy and Suspense just like a dynamic import:
+// --
+const Bar = lazy(() => importRemote({ url: 'http://localhost:3001', scope: 'Foo', module: 'Bar' }));
+
+return (
+  <Suspense fallback={<div>Loading Bar...</div>}>
+    <Bar />
+  </Suspense>
+);
+```
+
+```js
+import { importRemote } from '@module-federation/utilities';
+
+// If it's a regular js module:
+importRemote({
+  url: () => MyAsyncMethod('remote_name'),
+  scope: 'Foo',
+  module: 'Bar',
+}).then(
+  (
+    {
+      /* list of Bar exports */
+    },
+  ) => {
+    // Use Bar exports
+  },
+);
+
+// If Bar is a React component you can use it with lazy and Suspense just like a dynamic import:
+const Bar = lazy(() =>
+  importRemote({
+    url: () => MyAsyncMethod('remote_name'),
+    scope: 'Foo',
+    module: 'Bar',
+  }),
+);
+
+return (
+  <Suspense fallback={<div>Loading Bar...</div>}>
+    <Bar />
+  </Suspense>
+);
+```
+
+```js
+// You can also combine importRemote and FederationBoundary to have a dynamic remote URL and a fallback when there is an error on the remote
+
+const dynamicImporter = () =>
+  importRemote({
+    url: 'http://localhost:3001',
+    scope: 'Foo',
+    module: 'Bar',
+  });
+const fallback = () => import('@npm/backup').then((m) => m.Component);
+
+const Bar = () => {
+  return <FederationBoundary dynamicImporter={dynamicImporter} fallback={fallback} />;
+};
+```
+
+Apart from **url**, **scope** and **module** you can also pass additional options to the **importRemote()** function:
+
+- **remoteEntryFileName**: The name of the remote entry file. Defaults to "remoteEntry.js".
+- **bustRemoteEntryCache**: Whether to add a cache busting query parameter to the remote entry file URL. Defaults to **true**. You can disable it if cachebusting is handled by the server.

package/dist/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@module-federation/utilities",
+  "version": "3.0.5",
+  "type": "commonjs",
+  "main": "./index.cjs.js",
+  "types": "./dist/index.cjs.d.ts",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "repository": "https://github.com/module-federation/universe/tree/main/packages/utilities",
+  "devDependencies": {
+    "react": "18.2.0"
+  },
+  "peerDependencies": {
+    "webpack": "^5.40.0",
+    "react-dom": "^16 || ^17 || ^18",
+    "react": "^16 || ^17 || ^18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "exports": {
+    ".": {
+      "module": "./index.esm.js",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/index.cjs.d.ts"
+      ],
+      "type": [
+        "./dist/type.cjs.d.ts"
+      ]
+    }
+  },
+  "module": "./index.esm.js"
+}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@module-federation/utilities",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "type": "commonjs",
-  "main": "./index.cjs.js",
+  "main": "./dist/index.cjs.js",
   "types": "./dist/index.cjs.d.ts",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
   "repository": "https://github.com/module-federation/universe/tree/main/packages/utilities",
   "devDependencies": {
     "react": "18.2.0"
@@ -29,11 +33,7 @@
     }
   },
   "exports": {
-    ".": {
-      "module": "./index.esm.js",
-      "import": "./index.cjs.mjs",
-      "default": "./index.cjs.js"
-    },
+    ".": "./dist/index.cjs.js",
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -45,6 +45,5 @@
         "./dist/type.cjs.d.ts"
       ]
     }
-  },
-  "module": "./index.esm.js"
+  }
 }