@rollipop/plugin-module-federation 1.0.0-alpha.32 → 1.0.0-alpha.34

package/README.md

@@ -1,6 +1,6 @@
 # @rollipop/plugin-module-federation
 
-Module Federation for Rollipop. Wires `@module-federation/runtime` into the host bundle and emits a self-contained IIFE for each remote, with shared dependencies resolved through a host-owned global registry.
+Module Federation for Rollipop. Wires `@module-federation/runtime` into the host bundle and registers each remote's container on `globalThis`, with shared dependencies resolved through a host-owned global registry.
 
 ## Status
 
@@ -19,13 +19,17 @@ Module Federation for Rollipop. Wires `@module-federation/runtime` into the host
 
 A single Rollipop config takes one role. Defining both `remotes` and `exposes` throws.
 
-| Role   | Has       | Bundle output                                                                |
-| ------ | --------- | ---------------------------------------------------------------------------- |
-| Host   | `remotes` | Normal Rollipop bundle. `import('<remote>/<expose>')` is rewritten at build. |
-| Remote | `exposes` | IIFE that registers a federation container on `globalThis`.                  |
+| Role   | Has       | Bundle output                                                 |
+| ------ | --------- | ------------------------------------------------------------- |
+| Host   | `remotes` | Normal Rollipop bundle that consumes remotes at runtime.      |
+| Remote | `exposes` | IIFE for static builds; Rollipop format with HMR when served. |
 
 ## Host
 
+The script loader below uses the native `ScriptManager` supplied by the
+[`module-federation` example](../../examples/module-federation/mf-script-loader.ts).
+Provide a loader for your own app's native implementation.
+
 ```ts
 // rollipop.host.config.ts
 import { federation } from '@rollipop/plugin-module-federation';
@@ -47,6 +51,7 @@ export default defineConfig({
         // Register a `ModuleFederationScriptLoader` on `globalThis.__rollipop_script_loader__`.
         // Typically delegates to a native TurboModule that does fetch + JSI evaluate.
         implement: `
+          const NativeScriptManager = globalThis.nativeModuleProxy.ScriptManager;
           globalThis.__rollipop_script_loader__ = {
             async loadScript({ scriptId, url }) {
               await NativeScriptManager.loadScript(scriptId, { url });
@@ -62,12 +67,29 @@ export default defineConfig({
 In your app, consume the remote with dynamic import:
 
 ```ts
+import * as React from 'react';
+
 const RemoteNavigator = React.lazy(() =>
   import('remote_app/RemoteNavigator').then((m) => ({ default: m.default ?? m })),
 );
 ```
 
-The plugin rewrites the `import()` call into a `loadRemote` invocation against the federation runtime — no native `import()` evaluation happens at runtime.
+The imported module's default export is a React component proxy. Rendering it loads the remote
+through the federation runtime and suspends while the request is pending, so render it inside a
+React `Suspense` boundary. The bundled code does not use native `import()` to fetch the remote.
+
+Failed remote loads are thrown to the nearest React Error Boundary. From its retry action,
+reload the remote before resetting the boundary:
+
+```ts
+import { retryRemote } from '@rollipop/plugin-module-federation/runtime';
+
+await retryRemote('remote_app/RemoteNavigator');
+resetErrorBoundary();
+```
+
+Concurrent loads share one request. If a retry fails, the promise rejects and the boundary
+can keep showing its fallback until the user retries again.
 
 ## Remote
 
@@ -93,7 +115,11 @@ export default defineConfig({
 });
 ```
 
-The bundle is emitted as IIFE. Each shared dep import (e.g. `import RN from 'react-native'`) is replaced with a stub that reads from the host's `globalThis.__rollipop_shared__` registry and throws if the dep is not registered. Rollipop's prelude and polyfills are skipped because the host has already initialized the React Native runtime.
+Static builds emit an IIFE; the dev server uses Rollipop's format so each remote has its own HMR
+runtime. Each shared dependency import (e.g. `import RN from 'react-native'`) is replaced with a
+stub that reads from the host's `globalThis.__rollipop_shared__` registry and throws if the
+dependency is not registered. Rollipop's prelude and polyfills are skipped because the host has
+already initialized the React Native runtime.
 
 ## Script loader contract
 
@@ -109,11 +135,13 @@ The host registers an implementation on `globalThis.__rollipop_script_loader__`.
 
 ## Globals exposed at runtime
 
-| Global                       | Owner  | Purpose                                                                 |
-| ---------------------------- | ------ | ----------------------------------------------------------------------- |
-| `__rollipop_script_loader__` | user   | `ModuleFederationScriptLoader` implementation.                          |
-| `__rollipop_shared__`        | host   | Shared dependency registry. Lazily populated; missing keys throw.       |
-| `__rollipop_load_remote__`   | plugin | `(id: string) => Promise<unknown>` — wraps the federation `loadRemote`. |
+| Global                                 | Owner  | Purpose                                                                              |
+| -------------------------------------- | ------ | ------------------------------------------------------------------------------------ |
+| `__rollipop_script_loader__`           | user   | `ModuleFederationScriptLoader` implementation.                                       |
+| `__rollipop_shared__`                  | host   | Shared dependency registry populated during host initialization; missing keys throw. |
+| `__rollipop_module_federation_cache__` | plugin | Internal cache of loaded modules, pending requests, and load errors.                 |
+
+Use `retryRemote` from `@rollipop/plugin-module-federation/runtime` to retry a failed request.
 
 ## Constraints
 
@@ -121,7 +149,8 @@ The host registers an implementation on `globalThis.__rollipop_script_loader__`.
   current-implementation limitation, not an inherent Module Federation rule.
   Split a host and a remote into two configs and run them as separate Rollipop
   processes. See [Status](#status).
-- React Native does not support native `import()`. Static imports of remote modules are intentionally not supported — use dynamic `import('<remote>/<expose>')`.
+- Remote imports expose a default React component proxy. Dynamic `import('<remote>/<expose>')`
+  returns that proxy, rather than the remote module's namespace directly.
 - Subpath imports of shared deps (`react/jsx-dev-runtime`, etc.) are bundled into the remote and consume the parent shared instance through `__rollipop_shared__`.
 
 See `examples/module-federation` for a working RN 0.84 host + remote setup with a Pure C++/Obj-C++ TurboModule script loader.

package/dist/index.js

@@ -22,8 +22,9 @@ const Q = "\\u0027";
 //#endregion
 //#region src/virtual/host-init.ts
 function generateHostInitCode(config) {
-	const remotesArray = Object.values(config.remotes).map((remote) => ({
+	const remotesArray = Object.entries(config.remotes).map(([alias, remote]) => ({
 		name: remote.name,
+		alias: alias === remote.name ? void 0 : alias,
 		entry: remote.entry,
 		type: remote.type,
 		entryGlobalName: remote.entryGlobalName
@@ -66,6 +67,7 @@ function generateHostInitCode(config) {
       const cache = {
         modules: Object.create(null),
         pending: Object.create(null),
+        errors: Object.create(null),
         load(id) {
           if (this.modules[id] !== undefined) {
             return Promise.resolve(this.modules[id]);
@@ -73,12 +75,20 @@ function generateHostInitCode(config) {
           if (this.pending[id]) {
             return this.pending[id];
           }
+          delete this.errors[id];
           const fetcher = instance.loadRemote(id);
-          this.pending[id] = fetcher.then((mod) => {
-            this.modules[id] = mod;
-            delete this.pending[id];
-            return mod;
-          });
+          this.pending[id] = fetcher.then(
+            (mod) => {
+              this.modules[id] = mod;
+              delete this.pending[id];
+              return mod;
+            },
+            (error) => {
+              this.errors[id] = error;
+              delete this.pending[id];
+              throw error;
+            },
+          );
           return this.pending[id];
         },
       };
@@ -258,6 +268,9 @@ function generateRemoteProxyCode({ remoteId }) {
       if (__cache.modules[__id] !== undefined) {
         return __cache.modules[__id];
       }
+      if (__id in __cache.errors) {
+        throw __cache.errors[__id];
+      }
       throw __cache.load(__id);
     }
 

package/dist/runtime.d.ts

@@ -12,5 +12,10 @@ export interface RemoteEntryExports {
 }
 declare global {
   var __rollipop_script_loader__: ModuleFederationScriptLoader | undefined;
+  var __rollipop_module_federation_cache__: {
+    load(id: string): Promise<unknown>;
+  } | undefined;
 }
+/** Retry a failed remote load before resetting the component's Error Boundary. */
+export declare function retryRemote(id: string): Promise<unknown>;
 //#endregion

package/dist/runtime.js

@@ -1 +1,9 @@
-export {};
+//#region src/runtime.ts
+/** Retry a failed remote load before resetting the component's Error Boundary. */
+async function retryRemote(id) {
+	const cache = globalThis.__rollipop_module_federation_cache__;
+	if (cache == null) throw new Error("[rollipop:module-federation] The host runtime is not initialized.");
+	return cache.load(id);
+}
+//#endregion
+export { retryRemote };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rollipop/plugin-module-federation",
-  "version": "1.0.0-alpha.32",
+  "version": "1.0.0-alpha.34",
   "homepage": "https://github.com/rollipop-dev/rollipop#readme",
   "bugs": {
     "url": "https://github.com/rollipop-dev/rollipop/issues"
@@ -44,13 +44,13 @@
     "@types/react": "19.2.14",
     "@vitest/coverage-v8": "4.1.11",
     "react": "19.2.3",
-    "rollipop": "1.0.0-alpha.32",
+    "rollipop": "1.0.0-alpha.34",
     "typescript": "7.0.2",
     "vite-plus": "0.3.3",
     "vitest": "4.1.11"
   },
   "peerDependencies": {
-    "rollipop": "1.0.0-alpha.32"
+    "rollipop": "1.0.0-alpha.34"
   },
   "installConfig": {
     "hoistingLimits": "none"