Wait for pending Webpack Hot Updates before evaluating JS from RSC re…

…sponses

The Webpack runtime always tries to be minimal.
Since all pages share the same chunk, the prod runtime supports all pages.
However, in dev, the webpack runtime only supports the current page.

If we navigate to a new page, the Webpack runtime may need more functionality. Previously, we eagerly evaluated the RSC payload before any Hot Update was applied. This could lead to runtime errors.

For RSC payloads specifically, we just fell back to an MPA navigation.
We could continue to rely on this fallback. It may be disorienting though since we flash the error toast. We would also need to adjust this logic since `createFromFetch` no longer throws in these cases in later React version and instead lets the nearest Error Boundary handle these cases.

packages/next/src/client/components/react-dev-overlay/app/hot-reloader-client.tsx

@@ -47,17 +47,35 @@ let __nextDevClientId = Math.round(Math.random() * 100 + Date.now())
 let reloading = false
 let startLatency: number | null = null
 
-function onBeforeFastRefresh(dispatcher: Dispatcher, hasUpdates: boolean) {
+let pendingHotUpdateWebpack = Promise.resolve()
+let resolvePendingHotUpdateWebpack: () => void = () => {}
+function setPendingHotUpdateWebpack() {
+  pendingHotUpdateWebpack = new Promise((resolve) => {
+    resolvePendingHotUpdateWebpack = () => {
+      resolve()
+    }
+  })
+}
+
+export function waitForWebpackRuntimeHotUpdate() {
+  return pendingHotUpdateWebpack
+}
+
+function handleBeforeHotUpdateWebpack(
+  dispatcher: Dispatcher,
+  hasUpdates: boolean
+) {
   if (hasUpdates) {
     dispatcher.onBeforeRefresh()
   }
 }
 
-function onFastRefresh(
+function handleSuccessfulHotUpdateWebpack(
   dispatcher: Dispatcher,
   sendMessage: (message: string) => void,
   updatedModules: ReadonlyArray<string>
 ) {
+  resolvePendingHotUpdateWebpack()
   dispatcher.onBuildOk()
   reportHmrLatency(sendMessage, updatedModules)
 
@@ -159,6 +177,7 @@ function tryApplyUpdates(
   dispatcher: Dispatcher
 ) {
   if (!isUpdateAvailable() || !canApplyUpdates()) {
+    resolvePendingHotUpdateWebpack()
     dispatcher.onBuildOk()
     reportHmrLatency(sendMessage, [])
     return
@@ -281,12 +300,16 @@ function processMessage(
     } else {
       tryApplyUpdates(
         function onBeforeHotUpdate(hasUpdates: boolean) {
-          onBeforeFastRefresh(dispatcher, hasUpdates)
+          handleBeforeHotUpdateWebpack(dispatcher, hasUpdates)
         },
         function onSuccessfulHotUpdate(webpackUpdatedModules: string[]) {
           // Only dismiss it when we're sure it's a hot update.
           // Otherwise it would flicker right before the reload.
-          onFastRefresh(dispatcher, sendMessage, webpackUpdatedModules)
+          handleSuccessfulHotUpdateWebpack(
+            dispatcher,
+            sendMessage,
+            webpackUpdatedModules
+          )
         },
         sendMessage,
         dispatcher
@@ -320,6 +343,9 @@ function processMessage(
     }
     case HMR_ACTIONS_SENT_TO_BROWSER.BUILDING: {
       startLatency = Date.now()
+      if (!process.env.TURBOPACK) {
+        setPendingHotUpdateWebpack()
+      }
       console.log('[Fast Refresh] rebuilding')
       break
     }
@@ -426,6 +452,7 @@ function processMessage(
         reloading = true
         return window.location.reload()
       }
+      resolvePendingHotUpdateWebpack()
       startTransition(() => {
         router.hmrRefresh()
         dispatcher.onRefresh()

packages/next/src/client/components/router-reducer/fetch-server-response.ts

@@ -29,6 +29,7 @@ import {
 import { callServer } from '../../app-call-server'
 import { PrefetchKind } from './router-reducer-types'
 import { hexHash } from '../../../shared/lib/hash'
+import { waitForWebpackRuntimeHotUpdate } from '../react-dev-overlay/app/hot-reloader-client'
 
 export interface FetchServerResponseOptions {
   readonly flightRouterState: FlightRouterState
@@ -180,6 +181,14 @@ export async function fetchServerResponse(
       return doMpaNavigation(responseUrl.toString())
     }
 
+    // We may navigate to a page that requires a different Webpack runtime.
+    // In prod, every page will have the same Webpack runtime.
+    // In dev, the Webpack runtime is minimal for each page.
+    // We need to ensure the Webpack runtime is updated before executing client-side JS of the new page.
+    if (process.env.NODE_ENV !== 'production') {
+      await waitForWebpackRuntimeHotUpdate()
+    }
+
     // Handle the `fetch` readable stream that can be unwrapped by `React.use`.
     const response: NavigationFlightResponse = await createFromFetch(
       Promise.resolve(res),

test/development/app-hmr/hmr.test.ts

@@ -261,6 +261,7 @@ describe(`app-dir-hmr`, () => {
         .waitForElementByCss('[data-testid="new-runtime-functionality-page"]')
 
       const logs = await browser.log()
+      // TODO: Should assert on all logs but these are cluttered with logs from our test utils (e.g. playwright tracing or webdriver)
       if (process.env.TURBOPACK) {
         // FIXME: logging "rebuilding" multiple times instead of closing it of with "done in"
         // Should just not branch here and have the same logs as Webpack.
@@ -289,7 +290,6 @@ describe(`app-dir-hmr`, () => {
           ])
         )
       } else {
-        // TODO: Should assert on all logs but these are cluttered with logs from our test utils (e.g. playwright tracing or webdriver)
         expect(logs).toEqual(
           expect.arrayContaining([
             {
@@ -302,21 +302,16 @@ describe(`app-dir-hmr`, () => {
             },
           ])
         )
-        expect(logs).toEqual(
+        expect(logs).not.toEqual(
           expect.arrayContaining([
             expect.objectContaining({
               source: 'error',
             }),
           ])
         )
       }
-      if (process.env.TURBOPACK) {
-        // No MPA navigation triggered
-        expect(await browser.eval('window.__TEST_NO_RELOAD')).toEqual(true)
-      } else {
-        // MPA navigation triggered
-        expect(await browser.eval('window.__TEST_NO_RELOAD')).toEqual(undefined)
-      }
+      // No MPA navigation triggered
+      expect(await browser.eval('window.__TEST_NO_RELOAD')).toEqual(true)
     })
   })
 })