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

[ScriptedAlchemy]

Summary

This PR makes @module-federation/rsbuild-plugin support plugin-only SSR for Rsbuild app mode when using target: 'node' with a custom environment (for example ssr) without introducing breaking behavior.

Problem

Using pluginModuleFederation(..., { target: 'node', environment: 'ssr' }) in app-mode SSR was not reliable:

• setup path hardcoded config.environments['mf']
• custom node environment names could fail with undefined env/tooling paths
• commonjs-like SSR outputs could be skipped by isMFFormat gating, which could leave mf_remote/* unresolved

Root Cause

1. Node-target setup in pluginModuleFederation used a hardcoded env key (mf) instead of the configured environment option.
2. onBeforeCreateCompiler returned early for non-MF-format configs before considering that target: 'node' needs to run for the selected environment even when output is commonjs-like.
3. Node patching was broad (target === 'node' && isMFFormat(...)) rather than constrained to the selected environment.

Changes

• Update node-target environment selection to use config.environments[environment].
• Add explicit error when target: 'node' env is missing, including available environment names.
• Keep default environment behavior ('mf') unchanged for backward compatibility.
• Adjust compiler gating to always process the selected node-target environment.
• Constrain node patching to only the selected environment.
• Keep existing target: 'dual' restrictions/behavior intact (no app-mode dual enablement in this PR).

Tests

Added /packages/rsbuild-plugin/src/cli/node-target.spec.ts covering:

• custom env support (environment: 'ssr') without requiring mf
• clear missing-environment error
• commonjs-like selected node env still receives MF plugin injection
• target: 'dual' restriction remains unchanged for non-Rslib/non-Rspress callers
• default mf environment behavior still works

Verification

• pnpm -s nx run rsbuild-plugin:test
• pnpm -s nx run rsbuild-plugin:build

Both pass.

Docs and Release Notes

• Updated packages/rsbuild-plugin/README.md with app-mode node target example.
• Updated website docs:
  • apps/website-new/docs/en/guide/build-plugins/plugins-rsbuild.mdx
  • apps/website-new/docs/zh/guide/build-plugins/plugins-rsbuild.mdx
• Added changeset:
  • .changeset/quick-forks-wonder.md

[netlify]

✅ Deploy Preview for module-federation-docs ready!

Name	Link
🔨 Latest commit	80bebe2
🔍 Latest deploy log	https://app.netlify.com/projects/module-federation-docs/deploys/69a2267d298a680007a82dfd
😎 Deploy Preview	https://deploy-preview-4427--module-federation-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[changeset-bot]

🦋 Changeset detected

Latest commit: 80bebe2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 43 packages

Name	Type
@module-federation/rsbuild-plugin	Patch
@module-federation/modern-js-v3	Patch
@module-federation/modern-js	Patch
@module-federation/rspress-plugin	Patch
remote5	Patch
remote6	Patch
shared-tree-shaking-with-server-host	Patch
shared-tree-shaking-with-server-provider	Patch
website-new	Patch
@module-federation/runtime	Patch
@module-federation/enhanced	Patch
@module-federation/rspack	Patch
@module-federation/webpack-bundler-runtime	Patch
@module-federation/sdk	Patch
@module-federation/runtime-tools	Patch
@module-federation/managers	Patch
@module-federation/manifest	Patch
@module-federation/dts-plugin	Patch
@module-federation/third-party-dts-extractor	Patch
@module-federation/devtools	Patch
@module-federation/bridge-react	Patch
@module-federation/bridge-vue3	Patch
@module-federation/bridge-shared	Patch
@module-federation/bridge-react-webpack-plugin	Patch
@module-federation/retry-plugin	Patch
@module-federation/data-prefetch	Patch
@module-federation/error-codes	Patch
@module-federation/inject-external-runtime-core-plugin	Patch
@module-federation/runtime-core	Patch
create-module-federation	Patch
@module-federation/cli	Patch
@module-federation/treeshake-server	Patch
@module-federation/treeshake-frontend	Patch
@module-federation/metro	Patch
@module-federation/metro-plugin-rnef	Patch
@module-federation/metro-plugin-rnc-cli	Patch
@module-federation/nextjs-mf	Patch
@module-federation/node	Patch
@module-federation/storybook-addon	Patch
shared-tree-shaking-no-server-host	Patch
shared-tree-shaking-no-server-provider	Patch
@module-federation/esbuild	Patch
@module-federation/utilities	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eb2b405e83

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Bundle Size Report

3 package(s) changed, 38 unchanged.

Package	Total dist	Delta	ESM gzip	Delta
rsbuild-plugin	119.9 kB	+7.6 kB (+6.8%)	91 B	no change
sdk	105.1 kB	+492 B (+0.5%)	8.2 kB	+65 B (+0.8%)
vue3-bridge	159.2 kB	+235 B (+0.1%)	23.3 kB	+13 B (+0.1%)

Total dist: 6.89 MB (+8.3 kB (+0.1%))
Total ESM gzip: 138.8 kB (+78 B (+0.1%))

[pkg-pr-new]

Open in StackBlitz

@module-federation/devtools

pnpm add https://pkg.pr.new/@module-federation/devtools@d1857c5

@module-federation/cli

pnpm add https://pkg.pr.new/@module-federation/cli@d1857c5

create-module-federation

pnpm add https://pkg.pr.new/create-module-federation@d1857c5

@module-federation/data-prefetch

pnpm add https://pkg.pr.new/@module-federation/data-prefetch@d1857c5

@module-federation/dts-plugin

pnpm add https://pkg.pr.new/@module-federation/dts-plugin@d1857c5

@module-federation/enhanced

pnpm add https://pkg.pr.new/@module-federation/enhanced@d1857c5

@module-federation/error-codes

pnpm add https://pkg.pr.new/@module-federation/error-codes@d1857c5

@module-federation/esbuild

pnpm add https://pkg.pr.new/@module-federation/esbuild@d1857c5

@module-federation/managers

pnpm add https://pkg.pr.new/@module-federation/managers@d1857c5

@module-federation/manifest

pnpm add https://pkg.pr.new/@module-federation/manifest@d1857c5

@module-federation/metro

pnpm add https://pkg.pr.new/@module-federation/metro@d1857c5

@module-federation/metro-plugin-rnc-cli

pnpm add https://pkg.pr.new/@module-federation/metro-plugin-rnc-cli@d1857c5

@module-federation/metro-plugin-rnef

pnpm add https://pkg.pr.new/@module-federation/metro-plugin-rnef@d1857c5

@module-federation/modern-js

pnpm add https://pkg.pr.new/@module-federation/modern-js@d1857c5

@module-federation/modern-js-v3

pnpm add https://pkg.pr.new/@module-federation/modern-js-v3@d1857c5

@module-federation/native-federation-tests

pnpm add https://pkg.pr.new/@module-federation/native-federation-tests@d1857c5

@module-federation/native-federation-typescript

pnpm add https://pkg.pr.new/@module-federation/native-federation-typescript@d1857c5

@module-federation/nextjs-mf

pnpm add https://pkg.pr.new/@module-federation/nextjs-mf@d1857c5

@module-federation/node

pnpm add https://pkg.pr.new/@module-federation/node@d1857c5

@module-federation/retry-plugin

pnpm add https://pkg.pr.new/@module-federation/retry-plugin@d1857c5

@module-federation/rsbuild-plugin

pnpm add https://pkg.pr.new/@module-federation/rsbuild-plugin@d1857c5

@module-federation/rspack

pnpm add https://pkg.pr.new/@module-federation/rspack@d1857c5

@module-federation/rspress-plugin

pnpm add https://pkg.pr.new/@module-federation/rspress-plugin@d1857c5

@module-federation/runtime

pnpm add https://pkg.pr.new/@module-federation/runtime@d1857c5

@module-federation/runtime-core

pnpm add https://pkg.pr.new/@module-federation/runtime-core@d1857c5

@module-federation/runtime-tools

pnpm add https://pkg.pr.new/@module-federation/runtime-tools@d1857c5

@module-federation/sdk

pnpm add https://pkg.pr.new/@module-federation/sdk@d1857c5

@module-federation/storybook-addon

pnpm add https://pkg.pr.new/@module-federation/storybook-addon@d1857c5

@module-federation/third-party-dts-extractor

pnpm add https://pkg.pr.new/@module-federation/third-party-dts-extractor@d1857c5

@module-federation/treeshake-frontend

pnpm add https://pkg.pr.new/@module-federation/treeshake-frontend@d1857c5

@module-federation/treeshake-server

pnpm add https://pkg.pr.new/@module-federation/treeshake-server@d1857c5

@module-federation/typescript

pnpm add https://pkg.pr.new/@module-federation/typescript@d1857c5

@module-federation/utilities

pnpm add https://pkg.pr.new/@module-federation/utilities@d1857c5

@module-federation/webpack-bundler-runtime

pnpm add https://pkg.pr.new/@module-federation/webpack-bundler-runtime@d1857c5

@module-federation/bridge-react

pnpm add https://pkg.pr.new/@module-federation/bridge-react@d1857c5

@module-federation/bridge-react-webpack-plugin

pnpm add https://pkg.pr.new/@module-federation/bridge-react-webpack-plugin@d1857c5

@module-federation/bridge-shared

pnpm add https://pkg.pr.new/@module-federation/bridge-shared@d1857c5

@module-federation/bridge-vue3

pnpm add https://pkg.pr.new/@module-federation/bridge-vue3@d1857c5

@module-federation/inject-external-runtime-core-plugin

pnpm add https://pkg.pr.new/@module-federation/inject-external-runtime-core-plugin@d1857c5

commit: d1857c5

[github-actions]

Android Release APK for all devices

🔗 Download link.

Note: if the download link expires, please re-run the workflow to generate a new build.

Generated at 2026-02-15T21:46:23.410Z UTC

[github-actions]

iOS Release APP for simulators

🔗 Download link.

Note: if the download link expires, please re-run the workflow to generate a new build.

Generated at 2026-02-15T21:51:57.206Z UTC

[ScriptedAlchemy]

@cursoragent review and improve implementation. Look for any changes that were scope creep vs original specification or intent of the pr

[cursor]

Findings (ordered by severity):

• High: Node-target flow was mutating shared MF options, risking node runtime/library settings leaking into later envs (and duplicating runtime plugins); I fixed this by creating per-env SSR MF configs and avoiding shared mutation (packages/rsbuild-plugin/src/cli/index.ts L457–552).
• Medium: Rspress SSG handling could trigger for any env named node/node_md even when the caller isn’t Rspress, allowing unintended node-target processing; I gated this to Rspress callers (index.ts L410–434, L511–558).
• Low / scope creep: The node-target spec includes tests for target: 'dual' restriction and rslib default env fallback, which are tangential to custom node env support (node-target.spec.ts L242–268).

Summary/notes: I kept node-target processing scoped to the selected environment and reused a cloned SSR MF config for node builds (so shared options stay clean), plus I added assertions to ensure the base MF options remain unmodified in the non-selected env test (node-target.spec.ts L190–239). Assumption: non‑Rspress callers shouldn’t receive Rspress SSG handling even if they name envs node/node_md—let me know if you want that behavior restored.

Testing & verification (commands run, in order):

• npx nx format:check (failed before install: “Could not find Nx modules”)
• pnpm run setup:codex
• npx nx format:check (pass)
• npx nx run-many --targets=build --projects=tag:type:pkg --parallel=4 --skip-nx-cache (pass)
• npx nx run-many --targets=build --projects=tag:type:pkg --parallel=4 (pass)
• npx nx affected -t test --parallel=3 --exclude='*,!tag:type:pkg' (failed under Node v22.22.0: “Module status must be unlinked”)
• source ~/.nvm/nvm.sh && nvm install 20 && nvm use 20
• npx nx affected -t test --parallel=3 --exclude='*,!tag:type:pkg' (pass)
  Skipped checks: none. Walkthrough artifacts: . Since I ran a full setup:codex and installed Node 20, consider an env setup agent at https://cursor.com/onboard with: “Install Node 20 via nvm and run pnpm run setup:codex so future agents have deps preinstalled.”