Skip to content

Commit 6d67f46

Browse files
authored
[backport] Keep the dev validation worker alive across HMR updates (#97315)
Backports #96988 ("Keep the dev validation worker alive across HMR updates") to `next-16-3`. Cache Components dev validation reported stack frames that pointed at build output whenever a module had been updated while the dev server ran. The overlay showed a raw `file:` URL, the terminal named the chunk rather than the page, and because the frame never resolved to a source position there was no code frame either, so nothing indicated which line caused the error. This affected both the static shell validation and the instant-navigation validation, since both run on the same worker. Turbopack's server HMR evaluates an updated module as a script of its own, carrying its source map inline rather than on disk, so only the isolate that ran that `eval` can resolve a frame in it. The validation worker never ran it. The worker now replays the applied updates, the cleared manifest cache entries, and the evicted paths that the dev server reports, in the same order the dev server applied them, which leaves each updated module's inline source map in the worker's own Node.js cache. Not dropping the worker on every edit also removes a worker respawn and a `loadComponents` call from each validation that follows an edit, which is paid at exactly the moment the user is waiting for the insight. The case in the test suite that covers this went from around 870ms to around 240ms. This affects Turbopack dev with Cache Components, which is on by default unless `experimental.devValidationWorker` is set to `false`. ### Verification on this branch Cherry-picked from `f70564f742` with no conflicts. All source files are byte-identical to canary. Behavioral verification is left to CI on this branch; the change carries the `dev-validation-worker-source-maps` suite, whose snapshots turn from a frame naming the chunk into resolved frames. <!-- NEXT_JS_LLM -->
1 parent 2dd7f52 commit 6d67f46

10 files changed

Lines changed: 515 additions & 35 deletions

File tree

‎bench/dev-validation/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,17 @@ prints the speedup. Options:
2828
- `--port=<n>`, `--headless=false`, `--settle-ms=<n>`.
2929
- `--json-out=<path>` — write the raw stats as JSON.
3030

31+
Set `BENCH_DEV_VALIDATION_INSIGHTS=1` to give every family's leaf page an
32+
uncached data access, so validation reports one insight per navigation. Without
33+
it the run only covers the validation renders; with it, it also covers what
34+
follows an insight — encoding the errors and printing them with a source-mapped
35+
stack and code frame — which is the part that moves when that printing changes
36+
threads. The access sits below the family's heavy subtree, so validation still
37+
does that work before it reaches it: a page that suspends before it returns
38+
leaves the subtree unrendered in the validation pass. The routes become
39+
dynamic, so the absolute numbers are not comparable with a run without the
40+
flag; the worker-versus-in-process comparison within a run is.
41+
3142
This depends on `experimental.devValidationWorker` existing, so it stacks on the
3243
PR that adds the flag. Until the worker implementation lands, both
3344
configurations run in-process and the A/B shows no delta; once it lands, the

‎bench/dev-validation/scripts/generate.mjs‎

Lines changed: 42 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,15 @@ import { fileURLToPath } from 'node:url'
2525

2626
// Bump VERSION whenever the generation logic or shape changes; the marker file
2727
// short-circuits regeneration when nothing changed.
28-
const VERSION = 'v6-3families-nested4-noinstant-48leaves-d4-b3-400symbols'
28+
// Set BENCH_DEV_VALIDATION_INSIGHTS=1 to give every family's leaf page an
29+
// uncached data access. Validation then reports one insight per navigation, so
30+
// the run also exercises the error path (encoding the errors, and printing them
31+
// with a source-mapped stack and code frame) rather than only the validation
32+
// render. Off by default, so the numbers the README describes stay comparable.
33+
const WITH_INSIGHTS = process.env.BENCH_DEV_VALIDATION_INSIGHTS === '1'
34+
const VERSION =
35+
'v6-3families-nested4-noinstant-48leaves-d4-b3-400symbols' +
36+
(WITH_INSIGHTS ? '-insights-below-tree' : '')
2937
const LEAF_COMPONENTS = 48
3038
const TREE_DEPTH = 4
3139
const TREE_BRANCH = 3
@@ -221,27 +229,56 @@ export default function Layout({ children }: { children: React.ReactNode }) {
221229
`
222230
}
223231

232+
// The uncached access that makes validation report an insight. It renders last,
233+
// below the family's heavy subtree, so validation does that work before it
234+
// reaches the access. It is not wrapped in a `<Suspense>`, which is what makes
235+
// validation report the route as blocking.
236+
const insightImport = WITH_INSIGHTS
237+
? "import { connection } from 'next/server'\n"
238+
: ''
239+
const insightComponent = WITH_INSIGHTS
240+
? `
241+
async function Insight() {
242+
await connection()
243+
return null
244+
}
245+
`
246+
: ''
247+
224248
function leafPageSource(family, depthFromApp) {
225249
if (family === 'sprite') {
226-
return `// Generated. See scripts/generate.mjs. The sprite renders in the
250+
if (!WITH_INSIGHTS) {
251+
return `// Generated. See scripts/generate.mjs. The sprite renders in the
227252
// shared layout above, so the leaf page only carries the route marker.
228253
export default function Page() {
229254
return <h1 id="route">sprite</h1>
230255
}
231256
`
257+
}
258+
return `${insightImport}// Generated. See scripts/generate.mjs. The sprite renders in the
259+
// shared layout above, so the leaf page only carries the route marker.
260+
export default function Page() {
261+
return (
262+
<>
263+
<h1 id="route">sprite</h1>
264+
<Insight />
265+
</>
266+
)
267+
}
268+
${insightComponent}`
232269
}
233-
return `import { HeavyTree } from '${up(depthFromApp)}_generated/${family}-tree'
270+
return `${insightImport}import { HeavyTree } from '${up(depthFromApp)}_generated/${family}-tree'
234271
235272
// Generated. See scripts/generate.mjs.
236273
export default function Page() {
237274
return (
238275
<section>
239276
<h1 id="route">${family}</h1>
240-
<HeavyTree seed={7} />
277+
<HeavyTree seed={7} />${WITH_INSIGHTS ? '\n <Insight />' : ''}
241278
</section>
242279
)
243280
}
244-
`
281+
${insightComponent}`
245282
}
246283

247284
for (const family of FAMILIES) {

‎packages/next/src/server/dev/dev-validation-worker-pool.ts‎

Lines changed: 108 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
import type { NextConfigComplete } from '../config-shared'
2-
import type { runDevValidation } from './dev-validation-worker'
2+
import type { NodeJsPartialHmrUpdate } from '../../build/swc/types'
3+
import type {
4+
applyHmrUpdate,
5+
invalidateCaches,
6+
runDevValidation,
7+
} from './dev-validation-worker'
38
import type {
49
DevValidationSnapshot,
510
DevValidationWorkerMessage,
@@ -21,6 +26,52 @@ interface InstallOptions {
2126

2227
type ValidationPool = { [key: string]: any } & {
2328
runDevValidation: typeof runDevValidation
29+
applyHmrUpdate: typeof applyHmrUpdate
30+
invalidateCaches: typeof invalidateCaches
31+
}
32+
33+
/**
34+
* One change the dev server made to its own module state — the modules it has
35+
* loaded, and the manifest caches that describe them.
36+
*
37+
* The worker holds the same state, seeded from the same build output, and
38+
* replays every change the dev server reports, so its state is the dev server's
39+
* state by construction.
40+
*/
41+
type DevModuleStateChange =
42+
| { type: 'apply'; update: NodeJsPartialHmrUpdate }
43+
| { type: 'invalidate'; filePaths: string[]; evictModules: boolean }
44+
45+
/**
46+
* Replays a change the dev server made to its own module state in the
47+
* validation worker. Installed alongside the worker, so it is absent when no
48+
* worker runs (`experimental.devValidationWorker: false`, or Webpack).
49+
*/
50+
let mirrorModuleState: ((change: DevModuleStateChange) => void) | undefined
51+
52+
/**
53+
* Drops the validation worker. Called when the dev server cannot repair its own
54+
* module state in place and re-evaluates every module from disk, which the
55+
* worker matches by starting over: the next validation spawns a worker that
56+
* loads the current build output.
57+
*
58+
* A worker dropped on its own, by a failed replay or a crash, is the one case
59+
* where the two can diverge. The dev server keeps the modules it evaluated from
60+
* earlier updates, and a worker spawned afterwards has no way to obtain those
61+
* scripts, so frames naming them stay unresolved until those modules change
62+
* again. The validation itself is unaffected, because the worker loads the
63+
* current code from disk.
64+
*/
65+
let dropWorker: (() => void) | undefined
66+
67+
export function mirrorModuleStateToDevValidationWorker(
68+
change: DevModuleStateChange
69+
): void {
70+
mirrorModuleState?.(change)
71+
}
72+
73+
export function dropDevValidationWorker(): void {
74+
dropWorker?.()
2475
}
2576

2677
/**
@@ -43,9 +94,46 @@ export function installDevValidationWorker(options: InstallOptions): void {
4394
//
4495
// TODO(dev-validation-worker): raise `numWorkers` if concurrent navigations
4596
// across independent requests (e.g. multiple tabs) show a validation-latency
46-
// tail.
97+
// tail. Raising it means `mirrorChange` has to reach every worker instead of
98+
// whichever one the pool hands the call to, and the ordering it relies on
99+
// holds per worker rather than across them.
47100
let pool: ValidationPool | undefined
48101

102+
const mirrorChange = (change: DevModuleStateChange): void => {
103+
const current = pool
104+
if (!current) {
105+
// No worker to keep current, and nothing to replay into a later one: the
106+
// compilation that produced this change also wrote the updated chunk to
107+
// disk, so a worker spawning after it reads the current code through
108+
// `loadComponents`. Evaluating the update is what an isolate that is
109+
// already running needs, not what a new one does.
110+
return
111+
}
112+
113+
// The worker runs one call at a time, in the order the calls were made
114+
// (see `numWorkers` below), so this is replayed before any validation
115+
// requested after it, and never in the middle of one. That ordering is by
116+
// call time, which is why the call is made here, as the change arrives,
117+
// rather than deferred onto a queue of our own. A validation already
118+
// queued runs first, which is what its render needs: it was produced
119+
// before this change. The dev server does not hold its own updates back
120+
// for a validation running in process either.
121+
const replayed =
122+
change.type === 'invalidate'
123+
? current.invalidateCaches(change.filePaths, change.evictModules)
124+
: current.applyHmrUpdate(change.update).then(async (outcome) => {
125+
if (outcome === 'failed') {
126+
await tearDownPool()
127+
}
128+
})
129+
130+
void replayed.catch(async () => {
131+
// A replay that failed leaves the worker's state unknown, so it is
132+
// dropped rather than trusted.
133+
await tearDownPool()
134+
})
135+
}
136+
49137
const getPool = (): ValidationPool => {
50138
if (pool) {
51139
return pool
@@ -84,7 +172,11 @@ export function installDevValidationWorker(options: InstallOptions): void {
84172
// the module's exports. This worker's top-level imports (`require-hook`,
85173
// `node-environment`) run runtime setup meant only for the isolated
86174
// worker thread, so they must not be evaluated in the parent.
87-
exposedMethods: ['runDevValidation'],
175+
exposedMethods: [
176+
'runDevValidation',
177+
'applyHmrUpdate',
178+
'invalidateCaches',
179+
],
88180
forkOptions: {
89181
env: {
90182
...process.env,
@@ -169,13 +261,20 @@ export function installDevValidationWorker(options: InstallOptions): void {
169261
}
170262
}
171263

172-
// The dev server can't reach into the worker to clear its `require.cache` or
173-
// manifest caches, so we drop the worker whenever the parent's caches are
174-
// invalidated (HMR, route recompile). The next validation lazy-spawns a fresh
175-
// worker with empty caches.
176-
onCacheInvalidation(() => {
177-
void tearDownPool()
264+
// The dev server just cleared these paths from its own `require.cache` and
265+
// manifest caches. The worker clears them from its copies.
266+
onCacheInvalidation((filePaths) => {
267+
mirrorChange({
268+
type: 'invalidate',
269+
filePaths,
270+
evictModules: true,
271+
})
178272
})
179273

274+
mirrorModuleState = mirrorChange
275+
dropWorker = () => {
276+
void tearDownPool()
277+
}
278+
180279
setDevValidationWorker(runValidation)
181280
}

‎packages/next/src/server/dev/dev-validation-worker.ts‎

Lines changed: 74 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import type {
33
DevValidationWorkerMessage,
44
DevValidationWorkerResult,
55
} from '../app-render/dev-validation-worker-globals'
6+
import type { NodeJsPartialHmrUpdate } from '../../build/swc/types'
67

78
import '../require-hook'
89
import '../node-environment'
@@ -19,6 +20,8 @@ import {
1920
import { setHttpClientAndAgentOptions } from '../setup-http-agent-env'
2021
import { serializeValidationErrorsToFlight } from '../app-render/dev-validation-error-delivery'
2122
import { formatValidationEvent } from '../app-render/dev-validation-events'
23+
import { clearManifestCache } from '../load-manifest.external'
24+
import { deleteCache } from './require-cache'
2225
import {
2326
getServerActionsManifest,
2427
setManifestsSingleton,
@@ -38,11 +41,12 @@ import type { ModernSourceMapPayload } from '../lib/source-maps'
3841
* `loadComponents` pulled in. Frames arriving in the transported payload can
3942
* point at any chunk the main render touched.
4043
*
41-
* This only helps Turbopack, which writes a `.map` beside every chunk. Webpack
42-
* keeps its dev source maps in the compiler rather than on disk, so its frames
43-
* from chunks this thread never evaluated stay unresolved, and its module URLs
44-
* (`webpack-internal://…`) are declined below for the same reason. Frames from
45-
* dependencies that are not bundled never reach this point, because
44+
* Reading from disk covers the chunks, because the worker only runs under
45+
* Turbopack (see `next-dev-server.ts`), which writes a `.map` beside every one
46+
* of them. A module the server updated in place has no chunk of its own and is
47+
* covered instead by this thread applying the same update (see
48+
* `applyHmrUpdate`), which leaves its inline map in Node.js' cache here. Frames
49+
* from dependencies that are not bundled never reach this point, because
4650
* `filterStackFrameDEV` drops `node_modules` and `node:` frames; bundled
4751
* dependencies appear as chunks inside `distDir` like any other code.
4852
*/
@@ -71,7 +75,7 @@ function createDiskSourceMapLookup(
7175
}
7276

7377
if (!isAbsolute(chunkPath)) {
74-
// Not an emitted chunk, e.g. `webpack-internal://` or `<anonymous>`.
78+
// Not an emitted chunk, e.g. `<anonymous>`.
7579
return undefined
7680
}
7781

@@ -228,6 +232,70 @@ async function registerAdditionalClientReferenceManifests(
228232
)
229233
}
230234

235+
declare const __turbopack_server_hmr_apply__:
236+
| ((update: NodeJsPartialHmrUpdate) => void)
237+
| undefined
238+
239+
/**
240+
* What this thread did with a forwarded HMR update.
241+
*
242+
* `no-runtime` is not a failure: no runtime the update routes to had been
243+
* loaded here, so there was nothing to patch, and whatever loads that route
244+
* later reads the updated chunk from disk.
245+
*/
246+
export type HmrApplyOutcome = 'applied' | 'no-runtime' | 'failed'
247+
248+
/**
249+
* Applies a server HMR update to this thread's module registry, mirroring the
250+
* apply the dev server performed on its own.
251+
*
252+
* Turbopack's Node.js runtime registers the apply machinery per isolate (see
253+
* `dev-nodejs.ts`), and `loadComponents` evaluates that runtime here, so this
254+
* thread patches the same modules the dev server does. The apply also leaves
255+
* the updated module's inline source map in this thread's Node.js cache, which
256+
* is what makes a stack frame in that module source-mappable here.
257+
*/
258+
export async function applyHmrUpdate(
259+
update: NodeJsPartialHmrUpdate
260+
): Promise<HmrApplyOutcome> {
261+
if (typeof __turbopack_server_hmr_apply__ !== 'function') {
262+
return 'no-runtime'
263+
}
264+
265+
try {
266+
__turbopack_server_hmr_apply__(update)
267+
} catch {
268+
// The dev server responds to the same failure by re-evaluating every
269+
// module from disk. This thread cannot be repaired in place either, so the
270+
// caller drops it.
271+
return 'failed'
272+
}
273+
274+
return 'applied'
275+
}
276+
277+
/**
278+
* Clears the same caches the dev server cleared, for the same paths.
279+
*
280+
* `evictModules` follows the dev server's own split: an applied update patches
281+
* modules in place and clears only the manifest cache for the updated chunks,
282+
* while a recompile evicts `require.cache` as well. This thread follows both,
283+
* so its module state stays the dev server's module state.
284+
*/
285+
export async function invalidateCaches(
286+
filePaths: string[],
287+
evictModules: boolean
288+
): Promise<void> {
289+
if (evictModules) {
290+
deleteCache(filePaths)
291+
return
292+
}
293+
294+
for (const filePath of filePaths) {
295+
clearManifestCache(filePath)
296+
}
297+
}
298+
231299
/**
232300
* Runs the dev instant/static-shell validation passes off the main thread.
233301
* Reloads the route's compiled module, then delegates the whole validation to

0 commit comments

Comments
 (0)