feat(runtime): add optional unloadRemote API for deterministic teardown

.changeset/lucky-fishes-smell.md

@@ -0,0 +1,7 @@
+---
+'@module-federation/enhanced': patch
+'@module-federation/rsbuild-plugin': patch
+'@module-federation/runtime-tools': patch
+---
+
+Update enhanced and tooling integrations to consume the new optional runtime unload entrypoints.

.changeset/soft-carpets-develop.md

@@ -0,0 +1,15 @@
+---
+'@module-federation/runtime': minor
+'@module-federation/runtime-core': minor
+'@module-federation/webpack-bundler-runtime': minor
+---
+
+feat(runtime): move remote unload APIs to optional `@module-federation/runtime/unload` entry
+
+- Removes `unloadRemote` from baseline `ModuleFederation` and `@module-federation/runtime` root exports to reduce default payload.
+- Adds optional `@module-federation/runtime/unload` entrypoint with:
+  - `unloadRemote(nameOrAlias)` for the active runtime instance.
+  - `unloadRemoteFromInstance(instance, nameOrAlias)` for explicit instance control.
+- Keeps deterministic unload behavior when using the optional entrypoint, including:
+  - runtime bookkeeping cleanup (`moduleCache`, manifest/snapshot markers, preloaded map entries, id-to-remote mappings),
+  - webpack bundler module cache cleanup (`__webpack_require__.c`/`m`) and remote load marker reset.

.github/workflows/devtools.yml

@@ -42,6 +42,9 @@ jobs:
           cache: 'pnpm'
           cache-dependency-path: '**/pnpm-lock.yaml'
 
+      - name: Remove cached node_modules
+        run: rm -rf node_modules .nx
+
       - name: Set Playwright cache status
         run: |
           if [ -d "$HOME/.cache/ms-playwright" ] || [ -d "$HOME/.cache/Cypress" ]; then
@@ -54,13 +57,15 @@ jobs:
         uses: nrwl/nx-set-shas@v4
 
       - name: Install Dependencies
-        run: pnpm install --frozen-lockfile && find . -maxdepth 6 -type d \( -name ".cache" -o -name ".modern-js" \) -exec rm -rf {} +
+        run: pnpm install --frozen-lockfile
 
       - name: Install Cypress
         run: npx cypress install
 
       - name: Run Affected Build
-        run: npx nx run-many --targets=build --projects=tag:type:pkg
+        run: |
+          npx nx run-many --targets=build --projects=tag:type:pkg --parallel=4 --skip-nx-cache
+          npx nx run-many --targets=build --projects=tag:type:pkg --parallel=4
 
       - name: Configuration xvfb
         shell: bash

apps/website-new/docs/en/guide/runtime/runtime-api.mdx

@@ -671,6 +671,47 @@ loadShare('react', {
   </Tab>
 </Tabs>
 
+## unloadRemote
+
+- Type: `unloadRemote(nameOrAlias: string): boolean`
+- Removes a registered remote and clears runtime state for that remote in the current host instance.
+- Returns `true` when the remote exists and is removed, otherwise `false`.
+
+Use this API when you need deterministic teardown before switching remote entries, re-registering remotes, or cleaning up host state in long-lived sessions.
+
+<Tabs>
+  <Tab label="Build Plugin(Use build plugin)">
+  ```tsx
+    import { unloadRemote } from '@module-federation/enhanced/runtime';
+
+    // Remove by remote name
+    unloadRemote('remote');
+
+    // Remove by alias
+    unloadRemote('app1');
+  ```
+  </Tab>
+  <Tab label="Pure Runtime(Not use build plugin)">
+  ```ts
+    import { createInstance } from '@module-federation/enhanced/runtime';
+
+    const mf = createInstance({
+      name: 'mf_host',
+      remotes: [
+        {
+          name: 'remote',
+          alias: 'app1',
+          entry: 'http://localhost:2001/mf-manifest.json',
+        },
+      ],
+    });
+
+    mf.unloadRemote('remote');
+    mf.unloadRemote('app1');
+  ```
+  </Tab>
+</Tabs>
+
 ## preloadRemote
 
 <Collapse>

apps/website-new/docs/zh/guide/runtime/runtime-api.mdx

@@ -672,6 +672,47 @@ loadShare('react', {
   </Tab>
 </Tabs>
 
+## unloadRemote
+
+- Type: `unloadRemote(nameOrAlias: string): boolean`
+- 从当前 host 实例中移除已注册的 remote，并清理该 remote 对应的运行时状态。
+- 当 remote 存在并移除成功时返回 `true`，否则返回 `false`。
+
+当你需要在切换 remote 地址、重新注册 remote，或在长生命周期应用中做确定性清理时，可以使用该 API。
+
+<Tabs>
+  <Tab label="Build Plugin（使用构建插件）">
+  ```tsx
+    import { unloadRemote } from '@module-federation/enhanced/runtime';
+
+    // 按 remote name 移除
+    unloadRemote('remote');
+
+    // 按 alias 移除
+    unloadRemote('app1');
+  ```
+  </Tab>
+  <Tab label="Pure Runtime（未使用构建插件）">
+  ```ts
+    import { createInstance } from '@module-federation/enhanced/runtime';
+
+    const mf = createInstance({
+      name: 'mf_host',
+      remotes: [
+        {
+          name: 'remote',
+          alias: 'app1',
+          entry: 'http://localhost:2001/mf-manifest.json',
+        },
+      ],
+    });
+
+    mf.unloadRemote('remote');
+    mf.unloadRemote('app1');
+  ```
+  </Tab>
+</Tabs>
+
 ## preloadRemote
 
 <Collapse>

packages/enhanced/src/rspack.ts

@@ -4,4 +4,5 @@ export {
   TreeShakingSharedPlugin,
   PLUGIN_NAME,
 } from '@module-federation/rspack/plugin';
+export { parseOptions } from './lib/container/options';
 export { createModuleFederationConfig } from '@module-federation/sdk';

packages/rsbuild-plugin/src/cli/index.ts

@@ -1,8 +1,8 @@
-import { parseOptions } from '@module-federation/enhanced';
 import {
   ModuleFederationPlugin,
   TreeShakingSharedPlugin,
   PLUGIN_NAME,
+  parseOptions,
 } from '@module-federation/enhanced/rspack';
 import { isRequiredVersion, getManifestFileName } from '@module-federation/sdk';
 import pkgJson from '../../package.json';

packages/runtime-core/src/core.ts

@@ -353,6 +353,10 @@ export class ModuleFederation {
     return this.remoteHandler.registerRemotes(remotes, options);
   }
 
+  unloadRemote(nameOrAlias: string): boolean {
+    return this.remoteHandler.unloadRemote(nameOrAlias);
+  }
+
   registerShared(shared: UserOptions['shared']) {
     this.sharedHandler.registerShared(this.options, {
       ...this.options,

packages/runtime-core/src/remote/index.ts

@@ -72,6 +72,16 @@ export class RemoteHandler {
       remote: Remote;
       origin: ModuleFederation;
     }>('registerRemote'),
+    afterRemoveRemote: new SyncHook<
+      [
+        {
+          remote: Remote;
+          origin: ModuleFederation;
+          loaded: boolean;
+        },
+      ],
+      void
+    >('afterRemoveRemote'),
     beforeRequest: new AsyncWaterfallHook<{
       id: string;
       options: Options;
@@ -194,6 +204,17 @@ export class RemoteHandler {
     }
   }
 
+  unloadRemote(nameOrAlias: string): boolean {
+    const remote = this.host.options.remotes.find(
+      (item) => item.name === nameOrAlias || item.alias === nameOrAlias,
+    );
+    if (!remote) {
+      return false;
+    }
+    this.removeRemote(remote);
+    return true;
+  }
+
   // eslint-disable-next-line max-lines-per-function
   // eslint-disable-next-line @typescript-eslint/member-ordering
   async loadRemote<T>(
@@ -472,8 +493,16 @@ export class RemoteHandler {
         host.options.remotes.splice(remoteIndex, 1);
       }
       const loadedModule = host.moduleCache.get(remote.name);
+      const remoteInfo = loadedModule
+        ? loadedModule.remoteInfo
+        : getRemoteInfo(remote);
+
+      if (remoteInfo.entry) {
+        host.snapshotHandler.manifestCache.delete(remoteInfo.entry);
+      }
+
+      // Only clean global/share state when this host actually loaded the remote.
       if (loadedModule) {
-        const remoteInfo = loadedModule.remoteInfo;
         const key = remoteInfo.entryGlobalName as keyof typeof CurrentGlobal;
 
         if (CurrentGlobal[key]) {
@@ -486,16 +515,12 @@ export class RemoteHandler {
             CurrentGlobal[key] = undefined;
           }
         }
-        const remoteEntryUniqueKey = getRemoteEntryUniqueKey(
-          loadedModule.remoteInfo,
-        );
+        const remoteEntryUniqueKey = getRemoteEntryUniqueKey(remoteInfo);
 
         if (globalLoading[remoteEntryUniqueKey]) {
           delete globalLoading[remoteEntryUniqueKey];
         }
 
-        host.snapshotHandler.manifestCache.delete(remoteInfo.entry);
-
         // delete unloaded shared and instance
         let remoteInsId = remoteInfo.buildVersion
           ? composeKeyWithSeparator(remoteInfo.name, remoteInfo.buildVersion)
@@ -574,27 +599,51 @@ export class RemoteHandler {
           );
           CurrentGlobal.__FEDERATION__.__INSTANCES__.splice(remoteInsIndex, 1);
         }
+      }
 
-        const { hostGlobalSnapshot } = getGlobalRemoteInfo(remote, host);
-        if (hostGlobalSnapshot) {
-          const remoteKey =
-            hostGlobalSnapshot &&
-            'remotesInfo' in hostGlobalSnapshot &&
-            hostGlobalSnapshot.remotesInfo &&
-            getInfoWithoutType(hostGlobalSnapshot.remotesInfo, remote.name).key;
-          if (remoteKey) {
-            delete hostGlobalSnapshot.remotesInfo[remoteKey];
-            if (
-              //eslint-disable-next-line no-extra-boolean-cast
-              Boolean(Global.__FEDERATION__.__MANIFEST_LOADING__[remoteKey])
-            ) {
-              delete Global.__FEDERATION__.__MANIFEST_LOADING__[remoteKey];
-            }
-          }
+      host.moduleCache.delete(remote.name);
+      Object.keys(this.idToRemoteMap).forEach((id) => {
+        if (this.idToRemoteMap[id]?.name === remote.name) {
+          delete this.idToRemoteMap[id];
+        }
+      });
+
+      const remotePrefixes = [remote.name, remote.alias].filter(
+        Boolean,
+      ) as string[];
+      const preloadedMap = Global.__FEDERATION__.__PRELOADED_MAP__;
+      Array.from(preloadedMap.keys()).forEach((key) => {
+        if (
+          remotePrefixes.some(
+            (prefix) => key === prefix || key.startsWith(`${prefix}/`),
+          )
+        ) {
+          preloadedMap.delete(key);
         }
+      });
 
-        host.moduleCache.delete(remote.name);
+      const { hostGlobalSnapshot } = getGlobalRemoteInfo(remote, host);
+      if (hostGlobalSnapshot) {
+        const remoteKey =
+          hostGlobalSnapshot &&
+          'remotesInfo' in hostGlobalSnapshot &&
+          hostGlobalSnapshot.remotesInfo &&
+          getInfoWithoutType(hostGlobalSnapshot.remotesInfo, remote.name).key;
+        if (remoteKey) {
+          delete hostGlobalSnapshot.remotesInfo[remoteKey];
+          if (
+            //eslint-disable-next-line no-extra-boolean-cast
+            Boolean(Global.__FEDERATION__.__MANIFEST_LOADING__[remoteKey])
+          ) {
+            delete Global.__FEDERATION__.__MANIFEST_LOADING__[remoteKey];
+          }
+        }
       }
+      this.hooks.lifecycle.afterRemoveRemote.emit({
+        remote,
+        origin: host,
+        loaded: Boolean(loadedModule),
+      });
     } catch (err) {
       logger.log('removeRemote fail: ', err);
     }

packages/runtime-tools/src/webpack-bundler-runtime.ts

@@ -1,8 +1,2 @@
-import webpackBundlerRuntime from '@module-federation/webpack-bundler-runtime';
-
-const normalizedWebpackBundlerRuntime =
-  // Support both CJS module.exports payload and transpiled default payload.
-  (webpackBundlerRuntime as { default?: unknown }).default ??
-  webpackBundlerRuntime;
-
-export default normalizedWebpackBundlerRuntime;
+export { default } from '@module-federation/webpack-bundler-runtime';
+export * from '@module-federation/webpack-bundler-runtime';