docs(buildChunkGraph): explain why blocksWithNestedBlocks gates the skip (#21025)

alexander-akait · web-flow · commit 12cb8251190c · 2026-05-23T17:16:56.000+03:00
* docs(buildChunkGraph): explain why blocksWithNestedBlocks gates the skip

The previous `// TODO is this needed?` left the rationale ambiguous.
Skipping a block disconnects it from its chunk group, which orphans any
nested block's chunk group from this block's chunk group parent, so the
check must stay.

* test(chunks): cover the blocksWithNestedBlocks skip guard

Pins down the case where buildChunkGraph's connectChunkGroups would
otherwise skip a block whose modules are already in the entry chunk.
Without the `!blocksWithNestedBlocks.has(block)` guard, the outer
require.ensure's chunk group is left without a parent and gets cleaned
up together with the nested chunk group, so the inner sync require
fails at runtime. With the guard the test passes; removing the guard
makes the test time out waiting for the inner callback.
diff --git a/lib/buildChunkGraph.js b/lib/buildChunkGraph.js
@@ -1290,7 +1290,8 @@ const connectChunkGroups = (
 		// connections and modules can only create one version
 		// TODO maybe decide this per runtime
 		if (
-			// TODO is this needed?
+			// Blocks with nested blocks must stay connected — skipping orphans the
+			// nested block's chunk group from this block's chunk group parent.
 			!blocksWithNestedBlocks.has(block) &&
 			connections.every(({ chunkGroup, originChunkGroupInfo }) =>
 				areModulesAvailable(
diff --git a/test/cases/chunks/nested-blocks-with-available-parent-modules/a.js b/test/cases/chunks/nested-blocks-with-available-parent-modules/a.js
@@ -0,0 +1 @@
+module.exports = 1;
diff --git a/test/cases/chunks/nested-blocks-with-available-parent-modules/b.js b/test/cases/chunks/nested-blocks-with-available-parent-modules/b.js
@@ -0,0 +1 @@
+module.exports = 42;
diff --git a/test/cases/chunks/nested-blocks-with-available-parent-modules/index.js b/test/cases/chunks/nested-blocks-with-available-parent-modules/index.js
@@ -0,0 +1,18 @@
+// `./a` is pulled into the entry chunk by the synchronous require, so the
+// outer `require.ensure(["./a"], ...)` would otherwise be a candidate for the
+// "all dependencies already available" skip in buildChunkGraph's
+// `connectChunkGroups`. The `blocksWithNestedBlocks` guard prevents that skip
+// here — without it, the outer block's chunk group never gets a parent and
+// gets cleaned up together with the nested chunk group that contains `./b`,
+// so the inner require would fail at runtime.
+require("./a");
+
+it("should keep nested async chunks reachable when the outer block's modules are already in the entry chunk", (done) => {
+	require.ensure(["./a"], () => {
+		require.ensure([], () => {
+			const b = require("./b");
+			expect(b).toBe(42);
+			done();
+		});
+	});
+});
