Unverified Commit 193f030e authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

Defer app router HMR refresh until the router is initialized (#100113)

### What?

In dev, an app-router HMR refresh that arrives before the app router has
initialized is no longer dropped. It now runs once the router mounts.
Several early requests are coalesced into the newest one.

### Why?

`client/app-index.tsx` opens the HMR WebSocket before the initial RSC
payload resolves and before `hydrateRoot`. `dispatch` is only set when
`useActionQueue` renders. If an `ADDED_PAGE` / `REMOVED_PAGE` /
`SERVER_COMPONENT_CHANGES` / `STATIC_PARAMS_CHANGED` message arrives in
that window, `hmrRefresh()` throws `Internal Next.js error: Router
action dispatched before initialization.` and the refresh is lost. The
page then keeps showing stale content until a manual reload.

This shows up as the second failure mode of
`test/e2e/app-dir/not-found/basic` › "should render the 404 page when
the file is removed, and restore the page when re-added". The page is
removed, the browser full-reloads to the 404, and the "page re-added"
refresh arrives during hydration. The page stays on "Root Not Found" and
the restore assertion times out.

### How?

The race is resolved in `use-action-queue.ts`, where `dispatch` is
initialized:

- `dispatchAppRouterAction`: in dev, an `ACTION_HMR_REFRESH` that
arrives while `dispatch` is still `null` is stored as the pending HMR
refresh instead of throwing. A later early refresh replaces it. Its
`AbortSignal` belongs to the newest generation, since `hmrRefresh`
already aborts superseded ones.
- Once `dispatch` exists, a new HMR refresh clears any older pending one
before dispatching. `dispatch` is assigned during render, before the
mount effect runs, so this stops a stale (already aborted) refresh from
being replayed after a newer one.
- `useActionQueue` dispatches the pending refresh from a dev-only mount
effect, inside `startTransition`. It never dispatches during render.
- Every other action still throws `Router action dispatched before
initialization`. Production is unchanged; everything is behind the
existing `NODE_ENV` checks.
- `hot-reloader-app.tsx` is unchanged from canary. The earlier
`deferred-hmr-refresh.ts` helper, its `HotReload` effect and its
callback invariant are gone.

### Verification

Full test file, `pnpm test-dev-webpack`, CI env
(`NEXT_TEST_REACT_VERSION=18.3.1`,
`__NEXT_EXPERIMENTAL_STRICT_ROUTE_TYPES=true`):

| | Runs | `before initialization` errors | Failures |
|---|---|---|---|
| with only #100112 | 10 | 2 | 2 (both at the restore step) |
| with #100112 + this PR | 10 | 0 | 0 |

- `pnpm test-dev-turbo` passed 3/3 with both PRs, and `pnpm
test-start-webpack` passed.

New integration test
`test/development/app-dir/hmr-refresh-before-hydration`:
- It holds the page before the router initializes by stalling the chunk
of a user `app/global-error.tsx`, matched by a marker string in the
chunk's source so it works with both bundlers' chunk names.
- The initial Flight payload references the global error component as a
*value*, which blocks the payload until that chunk loads.
- A client component rendered as an element wouldn't work, because
element references are lazy.
  - The main runtime still loads and opens the real HMR socket.
- The test edits the server page twice, waits until the browser has
received both `serverComponentChanges` messages, then releases the
chunk. It asserts that the latest content appears without a full reload,
and that the router-before-initialization error doesn't show up.

| | webpack dev | Turbopack dev |
|---|---|---|
| without the fix | fails: `before` stays, and the router error is
thrown for each change | same |
| with the fix (`NEXT_TEST_MAX_RETRIES=0`) | 5/5 pass | 5/5 pass |

After the move into `use-action-queue.ts`:
- The integration test passed 5/5 again on both bundlers.
- Disabling the deferral makes it fail again on webpack.
- The full not-found file passed 3/3 with #100112 applied, in the CI
env.
- A local harness (not committed) checked the ordering where a newer
refresh arrives after render but before the mount effect: removing the
clear makes exactly that case fail.

This PR is independent of #100112, which fixes the other root cause of
the same flake (a webpack dev manifest read while the file is
half-written).

<!-- NEXT_JS_LLM -->


<!-- fleet e9d6c475-aeff-42d9-a058-210b6631f951 -->

---------
Co-authored-by: 's avatarvercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by: 's avatarTobias Koppers <1365881+sokra@users.noreply.github.com>
Co-authored-by: 's avatarLuke Sandberg <210140+lukesandberg@users.noreply.github.com>
parent 164c41c2
import type { Dispatch } from 'react' import type { Dispatch } from 'react'
import React, { use, useMemo, useOptimistic } from 'react' import React, {
startTransition,
use,
useEffect,
useMemo,
useOptimistic,
} from 'react'
import { isThenable } from '../../shared/lib/is-thenable' import { isThenable } from '../../shared/lib/is-thenable'
import type { AppRouterActionQueue } from './app-router-instance' import type { AppRouterActionQueue } from './app-router-instance'
import { import {
ACTION_HMR_REFRESH,
ACTION_REFRESH, ACTION_REFRESH,
type AppRouterState, type AppRouterState,
type HmrRefreshAction,
type ReducerActions, type ReducerActions,
type ReducerState, type ReducerState,
} from './router-reducer/router-reducer-types' } from './router-reducer/router-reducer-types'
...@@ -30,7 +38,28 @@ export function refreshOnInstantNavigationUnlock() { ...@@ -30,7 +38,28 @@ export function refreshOnInstantNavigationUnlock() {
} }
} }
// Development only. The HMR WebSocket is opened before the App Router hydrates
// (see `client/app-index.tsx`), so a server change can be reported before
// `dispatch` is initialized. Keep the newest such refresh and dispatch it once
// the router has mounted, instead of losing it and showing stale content. One
// refresh fetches the latest server state, and `hmrRefresh` aborts superseded
// generations, so only the newest one is needed.
let pendingHmrRefresh: HmrRefreshAction | null = null
export function dispatchAppRouterAction(action: ReducerActions) { export function dispatchAppRouterAction(action: ReducerActions) {
if (
process.env.NODE_ENV !== 'production' &&
action.type === ACTION_HMR_REFRESH
) {
if (dispatch === null) {
pendingHmrRefresh = action
return
}
// `dispatch` is assigned during render, before the mount effect below
// flushes an early refresh. A newer refresh supersedes that one.
pendingHmrRefresh = null
}
if (dispatch === null) { if (dispatch === null) {
throw new Error( throw new Error(
'Internal Next.js error: Router action dispatched before initialization.' 'Internal Next.js error: Router action dispatched before initialization.'
...@@ -89,6 +118,16 @@ export function useActionQueue( ...@@ -89,6 +118,16 @@ export function useActionQueue(
// eslint-disable-next-line react-hooks/rules-of-hooks // eslint-disable-next-line react-hooks/rules-of-hooks
const appDevRenderingIndicator = useAppDevRenderingIndicator() const appDevRenderingIndicator = useAppDevRenderingIndicator()
// Dispatch an HMR refresh that arrived before `dispatch` was initialized.
// eslint-disable-next-line react-hooks/rules-of-hooks
useEffect(() => {
const action = pendingHmrRefresh
pendingHmrRefresh = null
if (action !== null) {
startTransition(() => dispatchAppRouterAction(action))
}
}, [])
nextDispatch = (action: ReducerActions) => { nextDispatch = (action: ReducerActions) => {
appDevRenderingIndicator(() => { appDevRenderingIndicator(() => {
actionQueue.dispatch(action, setState) actionQueue.dispatch(action, setState)
......
'use client'
// The test stalls the script chunk that contains this marker. The initial
// Flight payload references this component as a value (the global error
// component), which blocks the payload from resolving until the chunk has
// loaded, so the App Router can't initialize until the test releases it.
// Must match `GATE_MARKER` in the test.
const GATE_MARKER = '__hmr_refresh_before_hydration_gate__'
export default function GlobalError() {
return (
<html>
<body>
<p data-marker={GATE_MARKER}>global error</p>
</body>
</html>
)
}
import type { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Page() {
return <p id="content">before</p>
}
import { nextTestSetup } from 'e2e-utils'
import { retry } from 'next-test-utils'
import type * as Playwright from 'playwright'
// Must match the marker rendered by `app/global-error.tsx`.
const GATE_MARKER = '__hmr_refresh_before_hydration_gate__'
// The HMR WebSocket connects before the App Router is initialized (see
// `client/app-index.tsx`). A server component change reported in that window
// must still be applied once the router is up, instead of being dropped.
//
// To hold the page in that window deterministically, the test stalls the
// script chunk of `app/global-error.tsx`. The initial Flight payload
// references the global error component as a value, which blocks the payload
// until its chunk loads, so the App Router can't render (and install its
// dispatch) until the chunk is released. (A client component rendered as an
// element wouldn't do: element references are lazy and don't block the
// payload.) The main app runtime, which opens the WebSocket, is not stalled.
describe('hmr-refresh-before-hydration', () => {
const { next } = nextTestSetup({
files: __dirname,
})
// Records the HMR socket's state and text messages so the test can tell
// when the server's change notification has reached the browser. Kept as a
// source string so it runs in the page exactly as written (not transpiled).
const observeHmrSocket = `
(() => {
const NativeWebSocket = window.WebSocket
window.__hmrOpen = false
window.__hmrMessages = []
window.WebSocket = class extends NativeWebSocket {
constructor(url, protocols) {
super(url, protocols)
if (String(url).includes('/_next/hmr')) {
this.addEventListener('open', () => {
window.__hmrOpen = true
})
this.addEventListener('message', (event) => {
if (typeof event.data === 'string') {
window.__hmrMessages.push(event.data)
}
})
}
}
}
})()
`
async function stallGatedChunk(page: Playwright.Page) {
let release!: () => void
const released = new Promise<void>((resolve) => {
release = resolve
})
const state = { stalled: false }
const handler = async (route: Playwright.Route) => {
if (route.request().resourceType() !== 'script') {
return route.continue()
}
const response = await route.fetch()
const body = await response.text()
if (body.includes(GATE_MARKER)) {
state.stalled = true
await released
}
await route.fulfill({ response, body })
}
await page.route('**/_next/static/**', handler)
return {
state,
release,
async dispose() {
release()
await page.unroute('**/_next/static/**', handler)
},
}
}
function countServerComponentChanges(page: Playwright.Page) {
return page.evaluate(
() =>
(window as any).__hmrMessages.filter((data: string) =>
data.includes('"serverComponentChanges"')
).length as number
)
}
it('applies server component changes reported before the router is initialized', async () => {
let page: Playwright.Page | undefined
let gate: Awaited<ReturnType<typeof stallGatedChunk>> | undefined
const consoleMessages: string[] = []
const originalPage = await next.readFile('app/page.tsx')
try {
const browser = await next.browser('/', {
waitUntil: 'commit',
waitHydration: false,
async beforePageLoad(p: Playwright.Page) {
page = p
page.on('console', (msg) => consoleMessages.push(msg.text()))
page.on('pageerror', (err) => consoleMessages.push(String(err)))
await page.addInitScript({ content: observeHmrSocket })
gate = await stallGatedChunk(page)
},
})
const p = page!
const g = gate!
await p.waitForFunction(() => (window as any).__hmrOpen === true)
await retry(() => expect(g.state.stalled).toBe(true))
// Detects a full reload, which would also show the new content.
await p.evaluate(() => {
;(window as any).__stayed = true
})
// Report two changes while the router is still blocked, so the early
// refresh requests have to be coalesced.
for (const [index, text] of ['after-1', 'after-2'].entries()) {
await next.patchFile('app/page.tsx', (content) =>
content!.replace(/>[^<]*</, `>${text}<`)
)
await retry(async () => {
expect(await countServerComponentChanges(p)).toBeGreaterThan(index)
}, 10_000)
}
g.release()
await retry(async () => {
expect(await browser.elementByCss('#content').text()).toBe('after-2')
}, 10_000)
expect(await browser.eval('window.__stayed')).toBe(true)
expect(consoleMessages).not.toContainEqual(
expect.stringContaining(
'Router action dispatched before initialization'
)
)
expect(consoleMessages).not.toContainEqual(
expect.stringContaining('deferred HMR refresh')
)
} finally {
await gate?.dispose()
await next.patchFile('app/page.tsx', originalPage)
}
})
})
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment