@module-federation/vite 1.20.9 → 1.21.0

package/README.md

@@ -351,20 +351,29 @@ federation({
 `provideExternalRuntime` injects a local runtime plugin that publishes `runtime-core` on `globalThis._FEDERATION_RUNTIME_CORE`. `externalRuntime` rewrites imports of `@module-federation/runtime-core` to read that global. Using `provideExternalRuntime` together with `exposes` throws — only pure consumers may provide the runtime.
 The `externalRuntime` rewrite applies to the browser remote graph; SSR remote entries continue to resolve `@module-federation/runtime-core` from Node so they do not depend on the browser global.
 
-## ⚠️ `codeSplitting` settings are controlled by the plugin
+## ⚠️ `codeSplitting` is managed by the plugin
 
-Do not set either `build.rollupOptions.output.codeSplitting` or
-`build.rolldownOptions.output.codeSplitting` to `false` with this plugin — it will be **automatically ignored**.
+Do not set `build.rollupOptions.output.codeSplitting` or
+`build.rolldownOptions.output.codeSplitting` to `false` — it will be **ignored** (with a warning).
+Module Federation requires chunk splitting so `loadShare` and `runtimeInitStatus` stay isolated for correct bootstrap order.
 
-`codeSplitting.groups` is also ignored because grouping shared-runtime chunks can break MF init order.
-Module Federation needs `loadShare` and `runtimeInitStatus` isolated into separate chunks for correct bootstrap behavior.
+### `codeSplitting.groups` (Vite 8+ / Rolldown)
 
-## ⚠️ `manualChunks` is not supported
+User groups are now **preserved**. The plugin installs its own federation groups at the highest priority and appends your groups below them, so your groups can only claim modules the federation groups didn't.
 
-Do not use `build.rollupOptions.output.manualChunks` or
-`build.rolldownOptions.output.manualChunks` with this plugin — it will be **automatically ignored**.
-The plugin manages the runtime chunk graph itself, and forcing custom chunk grouping can break Module Federation bootstrap order.
-The plugin injects the splits it needs so `runtimeInitStatus` and `loadShare` stay isolated.
+- No warning is emitted just for keeping your groups.
+- If one of your existing groups sets a `priority` high enough to outrank the federation groups, it is **clamped** below them and the plugin warns once. This prevents those groups from capturing a `runtimeInit`/`loadShare` wrapper or the preload helper.
+
+## ⚠️ `manualChunks` behavior depends on your Vite version
+
+| Setting | Vite 5–7 (Rollup) | Vite 8+ (Rolldown) |
+| --- | --- | --- |
+| `manualChunks` (function) | **Composed as a fallback** — federation modules are claimed first, everything else falls through to your function | **Ignored** (warns) — move grouping to `codeSplitting.groups` |
+| `manualChunks` (object) | **Ignored** (warns) — use the function form to compose | **Ignored** (warns) — move grouping to `codeSplitting.groups` |
+
+On Vite 5–7, Rollup doesn't support `codeSplitting`, so the plugin isolates `runtimeInitStatus`, `loadShare`, and the preload helper via `manualChunks`. A user-provided **function** is called for any module the plugin doesn't claim; the **object** form isn't composed by the plugin and is ignored.
+
+On Vite 8+, chunking is managed through `codeSplitting.groups` (see above), so `manualChunks` is removed — express your grouping as `codeSplitting.groups` instead, where user groups are preserved below the federation groups.
 
 ### So far so good 🎉
 

package/lib/index.js

@@ -9280,8 +9280,11 @@ function getRuntimeCapabilityConfigurationWarnings(options) {
 //#endregion
 //#region src/index.ts
 const patchedManualChunks = /* @__PURE__ */ new WeakSet();
+const federationGroups = /* @__PURE__ */ new WeakSet();
 const PRELOAD_HELPER_CHUNK = "vite-preload-helper";
 const PRELOAD_HELPER_TEST = /\0?vite\/preload-helper/;
+const MF_GROUP_PRIORITY = 1e6;
+const USER_GROUP_MAX_PRIORITY = MF_GROUP_PRIORITY - 1;
 function normalizeVinextRscPreloadHints(code) {
 	return code.replace(/(:HL\[[^\]\n]*?,)"stylesheet"/g, "$1\"style\"").replace(/(:HL\[[^\]\n]*?,)\\"stylesheet\\"/g, "$1\\\"style\\\"");
 }
@@ -10025,33 +10028,33 @@ function federation(mfUserOptions) {
 					};
 				}
 				let warnedAboutCodeSplitting = false;
-				let warnedAboutCodeSplittingGroups = false;
 				const ensureCodeSplitting = (output) => {
-					if (output?.codeSplitting === false) {
-						delete output.codeSplitting;
-						if (warnedAboutCodeSplitting) return;
-						warnedAboutCodeSplitting = true;
-						mfWarn("Ignoring `output.codeSplitting = false` because module federation requires chunk splitting.");
-						return;
+					if (output?.codeSplitting !== false) return;
+					delete output.codeSplitting;
+					if (warnedAboutCodeSplitting) return;
+					warnedAboutCodeSplitting = true;
+					mfWarn("Ignoring `output.codeSplitting = false` because module federation requires chunk splitting.");
+				};
+				const isFederationGroup = (group) => typeof group === "object" && group !== null && federationGroups.has(group);
+				let warnedAboutGroupPriority = false;
+				const clampUserGroup = (group) => {
+					const candidate = group;
+					if (typeof candidate?.priority !== "number") return group;
+					if (candidate.priority <= USER_GROUP_MAX_PRIORITY) return group;
+					if (!warnedAboutGroupPriority) {
+						warnedAboutGroupPriority = true;
+						mfWarn(`Clamping \`output.codeSplitting.groups\` priority to ${USER_GROUP_MAX_PRIORITY} — module federation groups must keep the highest priority so shared dependency init wrappers stay isolated in their own chunks.`);
 					}
-					if (!output?.codeSplitting || typeof output.codeSplitting !== "object") return;
-					if (!("groups" in output.codeSplitting)) return;
-					const groups = output.codeSplitting.groups;
-					if (Array.isArray(groups) && groups.some((group) => typeof group?.name === "function" && patchedManualChunks.has(group.name))) return;
-					delete output.codeSplitting.groups;
-					if (Object.keys(output.codeSplitting).length === 0) delete output.codeSplitting;
-					if (warnedAboutCodeSplittingGroups) return;
-					warnedAboutCodeSplittingGroups = true;
-					mfWarn("Ignoring `output.codeSplitting.groups` because it conflicts with module federation. Grouping shared dependency init wrappers with their dependent modules can break runtime init order and cause standalone remotes to fail before mount.");
+					return {
+						...candidate,
+						priority: USER_GROUP_MAX_PRIORITY
+					};
 				};
 				let warnedAboutManualChunks = false;
+				let warnedAboutObjectManualChunks = false;
 				const applyManualChunks = (output, useCodeSplitting) => {
 					ensureCodeSplitting(output);
 					const isPatchedByPlugin = typeof output.manualChunks === "function" && patchedManualChunks.has(output.manualChunks);
-					if (output.manualChunks && !isPatchedByPlugin && !warnedAboutManualChunks) {
-						warnedAboutManualChunks = true;
-						mfWarn("Ignoring `output.manualChunks` because it conflicts with module federation. Module federation transforms shared dependency imports with async init wrappers, and grouping these transformed modules into a single chunk creates circular async dependencies that cause the application to silently hang.");
-					}
 					const mfChunkName = function(id) {
 						if (id.includes(runtimeInitId) || id.includes("__mf_v__runtimeInit__mf_v__")) return "runtimeInit";
 						if (id.includes("__loadShare__")) {
@@ -10062,19 +10065,44 @@ function federation(mfUserOptions) {
 					};
 					patchedManualChunks.add(mfChunkName);
 					if (!useCodeSplitting) {
-						const mfManualChunks = function(id) {
+						if (isPatchedByPlugin) return;
+						const userManualChunks = output.manualChunks;
+						if (userManualChunks && typeof userManualChunks !== "function" && !warnedAboutObjectManualChunks) {
+							warnedAboutObjectManualChunks = true;
+							mfWarn("Ignoring the object form of `output.manualChunks` because module federation cannot safely compose with it. Use the function form instead: federation modules are claimed first and your function runs for everything else.");
+						}
+						const mfManualChunks = function(id, ...rest) {
 							if (PRELOAD_HELPER_TEST.test(id)) return PRELOAD_HELPER_CHUNK;
-							return mfChunkName(id) ?? void 0;
+							const mfChunk = mfChunkName(id);
+							if (mfChunk) return mfChunk;
+							if (typeof userManualChunks === "function") return userManualChunks(id, ...rest) ?? void 0;
 						};
 						patchedManualChunks.add(mfManualChunks);
 						output.manualChunks = mfManualChunks;
 						return;
 					}
-					const groups = [{
+					if (output.manualChunks && !isPatchedByPlugin && !warnedAboutManualChunks) {
+						warnedAboutManualChunks = true;
+						mfWarn("Ignoring `output.manualChunks` for the Rolldown build because module federation manages chunking with `output.codeSplitting.groups`. Move your grouping there — user groups are kept below the federation groups.");
+					}
+					const existingGroups = output.codeSplitting && typeof output.codeSplitting === "object" ? output.codeSplitting.groups : void 0;
+					const userGroups = Array.isArray(existingGroups) ? existingGroups.filter((group) => !isFederationGroup(group)).map(clampUserGroup) : [];
+					const mfPreloadGroup = {
 						name: PRELOAD_HELPER_CHUNK,
 						test: PRELOAD_HELPER_TEST,
-						priority: 100
-					}, { name: mfChunkName }];
+						priority: 1000001
+					};
+					const mfNameGroup = {
+						name: mfChunkName,
+						priority: MF_GROUP_PRIORITY
+					};
+					federationGroups.add(mfPreloadGroup);
+					federationGroups.add(mfNameGroup);
+					const groups = [
+						mfPreloadGroup,
+						mfNameGroup,
+						...userGroups
+					];
 					output.codeSplitting = {
 						...output.codeSplitting || {},
 						groups

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@module-federation/vite",
-  "version": "1.20.9",
+  "version": "1.21.0",
   "description": "Vite plugin for Module Federation",
   "type": "module",
   "main": "./lib/index.js",