fix(rsbuild-plugin): support app SSR node target with custom environment

.changeset/quick-forks-wonder.md

@@ -0,0 +1,5 @@
+---
+'@module-federation/rsbuild-plugin': patch
+---
+
+Fix app-mode `target: 'node'` handling to respect custom `environment` names, improve missing-environment errors, auto-detect default environment names by caller/tooling when `environment` is omitted, and ensure selected node-target environments still receive federation plugin injection for commonjs-like SSR outputs.

apps/website-new/docs/en/guide/build-plugins/plugins-rsbuild.mdx

@@ -92,7 +92,10 @@ If you need to use the Module Federation runtime capabilities, please install [@
 export declare const pluginModuleFederation: (moduleFederationOptions: ModuleFederationOptions, rsbuildOptions?: RSBUILD_PLUGIN_OPTIONS) => RsbuildPlugin;
 
 type RSBUILD_PLUGIN_OPTIONS = {
+  target?: 'web' | 'node' | 'dual';
   ssr?: boolean;
+  ssrDir?: string;
+  environment?: string;
 }
 ```
 
@@ -109,7 +112,7 @@ Additional configuration for the Rsbuild plugin.
 
 :::tip
 
-Only supported when used as a global plugin in Rslib.
+`target: 'dual'` is only supported when used as a global plugin in Rslib/Rspress.
 
 :::
 
@@ -120,6 +123,46 @@ Used to specify the target runtime environment for the output. When set to `dual
 
 After generating SSR output with `target: 'dual'`, you can refer to [Create a Modern.js Consumer](../../../practice/frameworks/modern/index), create a consumer, and integrate the corresponding Rslib SSR producer for development.
 
+For Rsbuild app SSR, use `target: 'node'` with `environment` to apply Module Federation to a specific app environment.
+
+```ts title='rsbuild.config.ts'
+import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
+import { defineConfig } from '@rsbuild/core';
+
+export default defineConfig({
+  environments: {
+    client: {},
+    ssr: {},
+  },
+  plugins: [
+    pluginModuleFederation(
+      {
+        name: 'host',
+        remotes: {
+          remote: 'remote@http://localhost:3001/mf-manifest.json',
+        },
+      },
+      {
+        target: 'node',
+        environment: 'ssr',
+      },
+    ),
+  ],
+});
+```
+
+#### environment
+
+* Type: `string`
+* Default: auto-detected by caller/tooling:
+  * Rslib: `'mf'`
+  * Rsbuild app + `target: 'web'`: `'web'`
+  * Rsbuild app + `target: 'node'`: `'node'`
+  * Rspress + `target: 'web'`: `'web'`
+  * Rspress + `target: 'node'`: `'node'`
+
+Environment name used by `target: 'node'` to select which environment config receives Node-target federation behavior.
+
 
 #### ssr
 

apps/website-new/docs/zh/guide/build-plugins/plugins-rsbuild.mdx

@@ -92,7 +92,10 @@ export default defineConfig({
 export declare const pluginModuleFederation: (moduleFederationOptions: ModuleFederationOptions, rsbuildOptions?: RSBUILD_PLUGIN_OPTIONS) => RsbuildPlugin;
 
 type RSBUILD_PLUGIN_OPTIONS = {
+  target?: 'web' | 'node' | 'dual';
   ssr?: boolean;
+  ssrDir?: string;
+  environment?: string;
 }
 ```
 
@@ -108,7 +111,7 @@ Rsbuild 插件额外配置。
 
 :::tip
 
-仅支持 Rslib 全局插件。
+`target: 'dual'` 仅支持 Rslib/Rspress 全局插件。
 
 :::
 
@@ -119,6 +122,46 @@ Rsbuild 插件额外配置。
 
 使用 `target: 'dual'` 生成 SSR 产物后，可参考 [创建 Modern.js 消费者](../../../practice/frameworks/modern/index) 创建消费者，并接入对应的 Rslib SSR 生产者进行开发。
 
+对于 Rsbuild App 的 SSR，可使用 `target: 'node'` + `environment`，将 Module Federation 应用到指定环境。
+
+```ts title='rsbuild.config.ts'
+import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
+import { defineConfig } from '@rsbuild/core';
+
+export default defineConfig({
+  environments: {
+    client: {},
+    ssr: {},
+  },
+  plugins: [
+    pluginModuleFederation(
+      {
+        name: 'host',
+        remotes: {
+          remote: 'remote@http://localhost:3001/mf-manifest.json',
+        },
+      },
+      {
+        target: 'node',
+        environment: 'ssr',
+      },
+    ),
+  ],
+});
+```
+
+#### environment
+
+* 类型：`string`
+* 默认值：按调用方/工具自动推断：
+  * Rslib：`'mf'`
+  * Rsbuild App + `target: 'web'`：`'web'`
+  * Rsbuild App + `target: 'node'`：`'node'`
+  * Rspress + `target: 'web'`：`'web'`
+  * Rspress + `target: 'node'`：`'node'`
+
+在 `target: 'node'` 下用于指定要应用 Node Federation 行为的环境名称。
+
 
 #### ssr
 

packages/rsbuild-plugin/README.md

@@ -34,6 +34,53 @@ export default defineConfig({
 });
 ```
 
+### Rsbuild App SSR (Node target with custom environment)
+
+Use `target: 'node'` with an explicit `environment` to apply federation to a
+specific Rsbuild app environment (for example `ssr`).
+
+```ts
+import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
+import { defineConfig } from '@rsbuild/core';
+
+export default defineConfig({
+  environments: {
+    client: {},
+    ssr: {},
+  },
+  plugins: [
+    pluginModuleFederation(
+      {
+        name: 'host',
+        remotes: {
+          remote: 'remote@http://localhost:3001/mf-manifest.json',
+        },
+      },
+      {
+        target: 'node',
+        environment: 'ssr',
+      },
+    ),
+  ],
+});
+```
+
+`target: 'dual'` support remains scoped to Rslib/Rspress workflows.
+
+### Default environment detection
+
+If `environment` is omitted, the plugin will choose a default per tool:
+
+- **Rslib**: `mf`
+- **Rsbuild app**:
+  - `target: 'web'` → `web`
+  - `target: 'node'` → `node`
+- **Rspress**:
+  - `target: 'web'` → `web`
+  - `target: 'node'` → `node`
+
+You can still override with `environment` when your project uses custom names.
+
 ### Rslib Module
 
 ```js

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

@@ -30,7 +30,6 @@ import {
   RSPRESS_SSG_MD_ENV_NAME,
 } from '../constant';
 import {
-  ENV_NAME,
   patchNodeConfig,
   patchNodeMFConfig,
   patchToolsTspack,
@@ -47,7 +46,7 @@ type RSBUILD_PLUGIN_OPTIONS = {
   ssr?: boolean;
   // ssr dir, default is ssr
   ssrDir?: string;
-  // target copy environment name, default is mf
+  // target environment name. If omitted, defaults are inferred by caller/tool.
   environment?: string;
 };
 
@@ -75,6 +74,33 @@ export { RSBUILD_PLUGIN_MODULE_FEDERATION_NAME, PLUGIN_NAME, SSR_DIR };
 const LIB_FORMAT = ['umd', 'modern-module'];
 
 const DEFAULT_MF_ENVIRONMENT_NAME = 'mf';
+const DEFAULT_WEB_ENVIRONMENT_NAME = 'web';
+const DEFAULT_NODE_ENVIRONMENT_NAME = 'node';
+
+const resolveDefaultEnvironmentName = ({
+  callerName,
+  target,
+}: {
+  callerName: string;
+  target: RSBUILD_PLUGIN_OPTIONS['target'];
+}) => {
+  if (callerName === CALL_NAME_MAP.RSLIB) {
+    return DEFAULT_MF_ENVIRONMENT_NAME;
+  }
+
+  if (callerName === CALL_NAME_MAP.RSPRESS) {
+    if (target === 'node') {
+      return DEFAULT_NODE_ENVIRONMENT_NAME;
+    }
+    return DEFAULT_WEB_ENVIRONMENT_NAME;
+  }
+
+  if (target === 'node') {
+    return DEFAULT_NODE_ENVIRONMENT_NAME;
+  }
+
+  return DEFAULT_WEB_ENVIRONMENT_NAME;
+};
 
 function isStoryBook(rsbuildConfig: RsbuildConfig) {
   if (
@@ -122,7 +148,7 @@ export const pluginModuleFederation = (
       target = 'web',
       ssr = undefined,
       ssrDir = SSR_DIR,
-      environment = DEFAULT_MF_ENVIRONMENT_NAME,
+      environment: configuredEnvironment,
     } = rsbuildOptions || {};
     if (ssr) {
       throw new Error(
@@ -140,6 +166,12 @@ export const pluginModuleFederation = (
     const isRslib = callerName === CALL_NAME_MAP.RSLIB;
     const isRspress = callerName === CALL_NAME_MAP.RSPRESS;
     const isSSR = target === 'dual';
+    const environment =
+      configuredEnvironment ??
+      resolveDefaultEnvironmentName({
+        callerName,
+        target,
+      });
 
     if (isSSR && !isStoryBook(originalRsbuildConfig)) {
       if (!isRslib && !isRspress) {
@@ -255,8 +287,18 @@ export const pluginModuleFederation = (
           });
         }
       } else if (target === 'node') {
-        const mfEnv = config.environments![ENV_NAME]!;
-        patchToolsTspack(mfEnv, (config, { environment }) => {
+        const nodeTargetEnv = config.environments?.[environment];
+        if (!nodeTargetEnv) {
+          const availableEnvironments = Object.keys(config.environments || {});
+          const availableEnvironmentsLabel =
+            availableEnvironments.length > 0
+              ? availableEnvironments.join(', ')
+              : '(none)';
+          throw new Error(
+            `Can not find environment '${environment}' when using target: 'node'. Available environments: ${availableEnvironmentsLabel}.`,
+          );
+        }
+        patchToolsTspack(nodeTargetEnv, (config, { environment }) => {
           config.target = 'async-node';
         });
       }
@@ -360,7 +402,26 @@ export const pluginModuleFederation = (
         throw new Error('Can not get bundlerConfigs!');
       }
       bundlerConfigs.forEach((bundlerConfig) => {
-        if (!isMFFormat(bundlerConfig) && !isRspress) {
+        const bundlerConfigName = bundlerConfig.name || '';
+        const isNodeTargetEnvironmentConfig =
+          target === 'node' && bundlerConfigName === environment;
+        const isRspressSSGEnvironmentConfig = isRspressSSGConfig(
+          bundlerConfig.name,
+        );
+
+        if (
+          target === 'node' &&
+          !isNodeTargetEnvironmentConfig &&
+          !isRspressSSGEnvironmentConfig
+        ) {
+          return;
+        }
+
+        if (
+          !isMFFormat(bundlerConfig) &&
+          !isRspress &&
+          !isNodeTargetEnvironmentConfig
+        ) {
           return;
         } else if (isStoryBook(originalRsbuildConfig)) {
           bundlerConfig.output!.uniqueName = `${moduleFederationOptions.name} -storybook - host`;
@@ -435,7 +496,7 @@ export const pluginModuleFederation = (
             bundlerConfig.output!.chunkLoadingGlobal = `chunk_${moduleFederationOptions.name} `;
           }
 
-          if (target === 'node' && isMFFormat(bundlerConfig)) {
+          if (isNodeTargetEnvironmentConfig) {
             patchNodeConfig(bundlerConfig, moduleFederationOptions);
             patchNodeMFConfig(moduleFederationOptions);
           }