Turbopack HMR: Reload the page when server session changes (#68630)

It’s possible to the following scenario to occur:

- Browser loads a page and establishes HMR connection
- User quits the server, makes changes, and restarts the server
- The browser reloads, the user makes more changes, and the two reach an
inconsistent state

To avoid this, reload the browser when the server changes. This already
happened with webpack, so implement it for Turbopack.

Test Plan: `TURBOPACK=1 pnpm test-dev
test/development/basic/hmr.test.ts`

---------

Co-authored-by: Tobias Koppers <[email protected]>

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

@@ -418,6 +418,9 @@ function processMessage(
     case HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED: {
       processTurbopackMessage({
         type: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED,
+        data: {
+          sessionId: obj.data.sessionId,
+        },
       })
       break
     }

packages/next/src/client/components/react-dev-overlay/pages/hot-reloader-client.ts

@@ -335,6 +335,7 @@ function processMessage(obj: HMR_ACTION_TYPES) {
       for (const listener of turbopackMessageListeners) {
         listener({
           type: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED,
+          data: obj.data,
         })
       }
       break

packages/next/src/client/components/react-dev-overlay/pages/websocket.ts

@@ -1,4 +1,7 @@
-import type { HMR_ACTION_TYPES } from '../../../../server/dev/hot-reloader-types'
+import {
+  HMR_ACTIONS_SENT_TO_BROWSER,
+  type HMR_ACTION_TYPES,
+} from '../../../../server/dev/hot-reloader-types'
 import { getSocketUrl } from '../internal/helpers/get-socket-url'
 
 let source: WebSocket
@@ -17,6 +20,8 @@ export function sendMessage(data: string) {
 }
 
 let reconnections = 0
+let reloading = false
+let serverSessionId: number | null = null
 
 export function connectHMR(options: { path: string; assetPrefix: string }) {
   function init() {
@@ -28,8 +33,36 @@ export function connectHMR(options: { path: string; assetPrefix: string }) {
     }
 
     function handleMessage(event: MessageEvent<string>) {
+      // While the page is reloading, don't respond to any more messages.
+      // On reconnect, the server may send an empty list of changes if it was restarted.
+      if (reloading) {
+        return
+      }
+
       // Coerce into HMR_ACTION_TYPES as that is the format.
       const msg: HMR_ACTION_TYPES = JSON.parse(event.data)
+
+      if (
+        'action' in msg &&
+        msg.action === HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED
+      ) {
+        if (
+          serverSessionId !== null &&
+          serverSessionId !== msg.data.sessionId
+        ) {
+          // Either the server's session id has changed and it's a new server, or
+          // it's been too long since we disconnected and we should reload the page.
+          // There could be 1) unhandled server errors and/or 2) stale content.
+          // Perform a hard reload of the page.
+          window.location.reload()
+
+          reloading = true
+          return
+        }
+
+        serverSessionId = msg.data.sessionId
+      }
+
       for (const eventCallback of eventCallbacks) {
         eventCallback(msg)
       }
@@ -43,6 +76,7 @@ export function connectHMR(options: { path: string; assetPrefix: string }) {
       reconnections++
       // After 25 reconnects we'll want to reload the page as it indicates the dev server is no longer running.
       if (reconnections > 25) {
+        reloading = true
         window.location.reload()
         return
       }

packages/next/src/server/dev/hot-reloader-turbopack.ts

@@ -90,6 +90,8 @@ const isTestMode = !!(
   process.env.DEBUG
 )
 
+const sessionId = Math.floor(Number.MAX_SAFE_INTEGER * Math.random())
+
 export async function createHotReloaderTurbopack(
   opts: SetupOpts,
   serverFields: ServerFields,
@@ -667,6 +669,7 @@ export async function createHotReloaderTurbopack(
 
         const turbopackConnected: TurbopackConnectedAction = {
           action: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED,
+          data: { sessionId },
         }
         sendToClient(client, turbopackConnected)
 

packages/next/src/server/dev/hot-reloader-types.ts

@@ -104,6 +104,7 @@ interface DevPagesManifestUpdateAction {
 
 export interface TurbopackConnectedAction {
   action: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED
+  data: { sessionId: number }
 }
 
 export interface AppIsrManifestAction {
@@ -130,7 +131,10 @@ export type HMR_ACTION_TYPES =
 
 export type TurbopackMsgToBrowser =
   | { type: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_MESSAGE; data: any }
-  | { type: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED }
+  | {
+      type: HMR_ACTIONS_SENT_TO_BROWSER.TURBOPACK_CONNECTED
+      data: { sessionId: number }
+    }
 
 export interface NextJsHotReloaderInterface {
   turbopackProject?: Project

test/development/basic/hmr.test.ts

@@ -1206,4 +1206,29 @@ describe.each([
       await next.patchFile(pageName, originalContent)
     }
   })
+
+  it('should reload the page when the server restarts', async () => {
+    const browser = await webdriver(next.url, basePath + '/hmr/about', {
+      headless: false,
+    })
+    await check(() => getBrowserBodyText(browser), /This is the about page/)
+
+    await next.destroy()
+
+    let reloadPromise = new Promise((resolve) => {
+      browser.on('request', (req) => {
+        if (req.url().endsWith('/hmr/about')) {
+          resolve(req.url())
+        }
+      })
+    })
+
+    next = await createNext({
+      files: join(__dirname, 'hmr'),
+      nextConfig,
+      forcedPort: next.appPort,
+    })
+
+    await reloadPromise
+  })
 })