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:vercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com> Co-authored-by:
Tobias Koppers <1365881+sokra@users.noreply.github.com> Co-authored-by:
Luke Sandberg <210140+lukesandberg@users.noreply.github.com>
Showing
Please
register
or
sign in
to comment