Skip to content
Projects
Groups
Snippets
Help
Loading...
Sign in
Toggle navigation
N
next.js
Project
Project
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
Alex
next.js
Commits
adb87bfa
Commit
adb87bfa
authored
Feb 28, 2026
by
Will Binns-Smith
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
wip
parent
d49212c8
Hide whitespace changes
Inline
Side-by-side
Showing
8 changed files
with
231 additions
and
2 deletions
+231
-2
hot-reloader-turbopack.ts
packages/next/src/server/dev/hot-reloader-turbopack.ts
+27
-1
require-cache.ts
packages/next/src/server/dev/require-cache.ts
+141
-0
page.tsx
test/development/app-dir/server-hmr/app/external/page.tsx
+11
-0
hmr-file-external.js
test/development/app-dir/server-hmr/lib/hmr-file-external.js
+1
-0
next.config.js
test/development/app-dir/server-hmr/next.config.js
+3
-1
index.js
...ent/app-dir/server-hmr/node_modules/hmr-external/index.js
+1
-0
package.json
...app-dir/server-hmr/node_modules/hmr-external/package.json
+5
-0
server-hmr.test.ts
test/development/app-dir/server-hmr/server-hmr.test.ts
+42
-0
No files found.
packages/next/src/server/dev/hot-reloader-turbopack.ts
View file @
adb87bfa
...
@@ -37,7 +37,7 @@ import {
...
@@ -37,7 +37,7 @@ import {
}
from
'./middleware-turbopack'
}
from
'./middleware-turbopack'
import
{
PageNotFoundError
}
from
'../../shared/lib/utils'
import
{
PageNotFoundError
}
from
'../../shared/lib/utils'
import
{
debounce
}
from
'../utils'
import
{
debounce
}
from
'../utils'
import
{
deleteCache
}
from
'./require-cache'
import
{
deleteCache
,
ExternalWatcher
}
from
'./require-cache'
import
{
import
{
clearAllModuleContexts
,
clearAllModuleContexts
,
clearModuleContext
,
clearModuleContext
,
...
@@ -358,6 +358,19 @@ export async function createHotReloaderTurbopack(
...
@@ -358,6 +358,19 @@ export async function createHotReloaderTurbopack(
const
fileLogger
=
getFileLogger
()
const
fileLogger
=
getFileLogger
()
fileLogger
.
initialize
(
distDir
,
mcpServerEnabled
)
fileLogger
.
initialize
(
distDir
,
mcpServerEnabled
)
// Watch external (non-distDir) modules loaded by Turbopack chunks so that
// changes to serverExternalPackages modules are reflected on the next request
// without needing a recompile.
const
externalWatcher
=
new
ExternalWatcher
(
distDir
)
externalWatcher
.
onExternalChanged
=
()
=>
{
if
(
process
.
env
.
NEXT_HMR_EXTERNAL_DEBUG
)
{
console
.
log
(
'[ExternalWatcher] external changed — clearing chunk cache'
)
}
if
(
typeof
__next__clear_chunk_cache__
===
'function'
)
{
__next__clear_chunk_cache__
()
}
}
const
encryptionKey
=
await
generateEncryptionKeyBase64
({
const
encryptionKey
=
await
generateEncryptionKeyBase64
({
isBuild
:
false
,
isBuild
:
false
,
distDir
,
distDir
,
...
@@ -629,6 +642,11 @@ export async function createHotReloaderTurbopack(
...
@@ -629,6 +642,11 @@ export async function createHotReloaderTurbopack(
// Reset the fetch patch so patchFetch() can re-wrap on the next request.
// Reset the fetch patch so patchFetch() can re-wrap on the next request.
if
(
serverPaths
.
length
>
0
)
{
if
(
serverPaths
.
length
>
0
)
{
resetFetch
()
resetFetch
()
// Discover any external (non-distDir) modules that Turbopack chunks have
// loaded via require() and start watching them for changes. When a watched
// file changes on disk it is immediately evicted from require.cache so the
// next request picks up the fresh version — without needing a recompile.
externalWatcher
.
scan
()
}
}
// Clear Turbopack's chunk-loading cache so chunks are re-required from disk on
// Clear Turbopack's chunk-loading cache so chunks are re-required from disk on
...
@@ -1545,6 +1563,12 @@ export async function createHotReloaderTurbopack(
...
@@ -1545,6 +1563,12 @@ export async function createHotReloaderTurbopack(
if
(
inputPage
===
'/src/instrumentation'
)
return
if
(
inputPage
===
'/src/instrumentation'
)
return
}
}
// Scan for any external modules that were loaded by Turbopack chunks
// during previous requests and start watching them. This is cheap (just
// iterating require.cache) and ensures we catch externals that were first
// loaded after the last chunk write.
externalWatcher
.
scan
()
return
hotReloaderSpan
return
hotReloaderSpan
.
traceChild
(
'ensure-page'
,
{
.
traceChild
(
'ensure-page'
,
{
inputPage
,
inputPage
,
...
@@ -1705,6 +1729,8 @@ export async function createHotReloaderTurbopack(
...
@@ -1705,6 +1729,8 @@ export async function createHotReloaderTurbopack(
})
})
},
},
close
()
{
close
()
{
externalWatcher
.
dispose
()
// Report MCP telemetry if MCP server is enabled
// Report MCP telemetry if MCP server is enabled
recordMcpTelemetry
(
opts
.
telemetry
)
recordMcpTelemetry
(
opts
.
telemetry
)
...
...
packages/next/src/server/dev/require-cache.ts
View file @
adb87bfa
import
{
statSync
}
from
'fs'
import
isError
from
'../../lib/is-error'
import
isError
from
'../../lib/is-error'
import
{
realpathSync
}
from
'../../lib/realpath'
import
{
realpathSync
}
from
'../../lib/realpath'
import
{
clearManifestCache
}
from
'../load-manifest.external'
import
{
clearManifestCache
}
from
'../load-manifest.external'
import
Watchpack
from
'next/dist/compiled/watchpack'
function
deleteFromRequireCache
(
filePath
:
string
)
{
function
deleteFromRequireCache
(
filePath
:
string
)
{
try
{
try
{
...
@@ -33,3 +35,142 @@ export function deleteCache(filePath: string) {
...
@@ -33,3 +35,142 @@ export function deleteCache(filePath: string) {
deleteFromRequireCache
(
filePath
)
deleteFromRequireCache
(
filePath
)
}
}
/**
* Watches external (non-distDir) modules that are loaded as children of
* Turbopack output chunks, evicting them from require.cache when they change.
*
* Turbopack doesn't watch node_modules, so changes to serverExternalPackages
* modules never trigger a recompile. This watcher fills that gap: after each
* chunk write we scan distDir chunks for non-distDir children (externals) and
* start watching any we haven't seen before. When a watched file changes on
* disk we immediately evict it from require.cache so the next request picks up
* the fresh version.
*
* Evicting the external alone is not enough: Turbopack's devModuleCache (a
* closure variable in [turbopack]_runtime.js) caches instantiated modules and
* is not cleared by clearChunkCache(). To force re-instantiation we also evict
* the runtime chunk and all page chunks that reference it. This causes the
* runtime to be re-required on the next request with a fresh devModuleCache,
* so page modules are re-instantiated and pick up the new external.
*
* We evict ONLY the runtime chunk itself (not its children) to avoid evicting
* async storage externals (work-async-storage.external.js etc.) which are
* children of the runtime's SSR chunks and must remain in require.cache.
*/
export
class
ExternalWatcher
{
// Watchpack handles fs.watch lifecycle, error recovery, and platform quirks.
private
wp
=
new
Watchpack
({
aggregateTimeout
:
200
})
private
watched
=
new
Set
<
string
>
()
/**
* Called whenever an external module is evicted from require.cache due to a
* detected change. The hot reloader uses this to also clear Turbopack's chunk
* cache so the runtime chunk re-executes and picks up the fresh external.
*/
onExternalChanged
:
(()
=>
void
)
|
undefined
constructor
(
private
distDir
:
string
)
{
this
.
wp
.
on
(
'aggregated'
,
(
changes
:
Set
<
string
>
)
=>
{
for
(
const
filePath
of
changes
)
{
if
(
this
.
watched
.
has
(
filePath
))
{
this
.
evictExternal
(
filePath
)
}
}
})
}
/**
* Scan all currently-loaded distDir chunks for non-distDir children.
* Newly-discovered externals are added to the Watchpack watch list.
* Already-watched externals are checked for mtime changes that occurred
* before the watcher fired (stale-at-discovery race).
*/
scan
()
{
const
newFiles
:
string
[]
=
[]
for
(
const
[
filePath
,
mod
]
of
Object
.
entries
(
require
.
cache
))
{
if
(
!
filePath
.
startsWith
(
this
.
distDir
)
||
!
mod
)
continue
for
(
const
child
of
mod
.
children
)
{
if
(
child
.
filename
.
startsWith
(
this
.
distDir
))
continue
if
(
this
.
watched
.
has
(
child
.
filename
))
continue
this
.
watched
.
add
(
child
.
filename
)
newFiles
.
push
(
child
.
filename
)
}
}
if
(
newFiles
.
length
===
0
)
return
// Re-watch with the updated file list. Watchpack diffs internally so
// existing watchers are preserved; only new files get new watchers.
// startTime: Date.now() means only future changes fire the aggregated event.
this
.
wp
.
watch
({
files
:
[...
this
.
watched
],
startTime
:
Date
.
now
()
})
// Stale-at-discovery check: if a file was modified after the distDir chunk
// that loaded it was written (i.e. between first render and this scan),
// Watchpack won't fire for it. Evict it immediately.
for
(
const
filePath
of
newFiles
)
{
const
mod
=
require
.
cache
[
filePath
]
if
(
!
mod
)
continue
const
parentMod
=
Object
.
values
(
require
.
cache
).
find
(
(
m
)
=>
m
?.
filename
.
startsWith
(
this
.
distDir
)
&&
m
.
children
.
includes
(
mod
)
)
if
(
!
parentMod
)
continue
try
{
const
extStat
=
statSync
(
filePath
,
{
throwIfNoEntry
:
false
})
const
parentStat
=
statSync
(
parentMod
.
filename
,
{
throwIfNoEntry
:
false
,
})
if
(
extStat
&&
parentStat
&&
extStat
.
mtimeMs
>
parentStat
.
mtimeMs
)
{
this
.
evictExternal
(
filePath
)
}
}
catch
{
// Ignore stat errors.
}
}
}
private
evictExternal
(
filePath
:
string
)
{
// Evict the external itself.
deleteFromRequireCache
(
filePath
)
// Find the Turbopack runtime chunk directly by filename pattern — it's the
// single distDir chunk whose name contains "[turbopack]_runtime". Evicting
// it (but NOT its children) forces a fresh devModuleCache on the next
// request. The runtime's children (SSR chunks + async storage externals)
// remain in require.cache so in-flight requests keep their storage context.
// Pass 1: find the Turbopack runtime chunk by filename pattern.
let
runtimeChunk
:
NodeJS
.
Module
|
undefined
for
(
const
[
path
,
mod
]
of
Object
.
entries
(
require
.
cache
))
{
if
(
mod
&&
path
.
startsWith
(
this
.
distDir
)
&&
path
.
includes
(
'[turbopack]_runtime'
)
)
{
runtimeChunk
=
mod
break
}
}
// Pass 2: find all page chunks that have the runtime as a direct child.
const
pageChunks
:
NodeJS
.
Module
[]
=
[]
if
(
runtimeChunk
)
{
for
(
const
[
path
,
mod
]
of
Object
.
entries
(
require
.
cache
))
{
if
(
mod
&&
path
.
startsWith
(
this
.
distDir
)
&&
mod
.
children
.
includes
(
runtimeChunk
)
)
{
pageChunks
.
push
(
mod
)
}
}
}
if
(
runtimeChunk
)
deleteFromRequireCache
(
runtimeChunk
.
filename
)
for
(
const
pageChunk
of
pageChunks
)
{
deleteFromRequireCache
(
pageChunk
.
filename
)
}
this
.
onExternalChanged
?.()
}
dispose
()
{
this
.
wp
.
close
()
this
.
watched
.
clear
()
}
}
test/development/app-dir/server-hmr/app/external/page.tsx
0 → 100644
View file @
adb87bfa
import
{
value
}
from
'hmr-external'
import
{
fileValue
}
from
'../../lib/hmr-file-external'
export
default
function
ExternalPage
()
{
return
(
<>
<
p
id=
"value"
>
{
value
}
</
p
>
<
p
id=
"file-value"
>
{
fileValue
}
</
p
>
</>
)
}
test/development/app-dir/server-hmr/lib/hmr-file-external.js
0 → 100644
View file @
adb87bfa
module
.
exports
=
{
fileValue
:
'file-external-value: 0'
}
test/development/app-dir/server-hmr/next.config.js
View file @
adb87bfa
/**
/**
* @type {import('next').NextConfig}
* @type {import('next').NextConfig}
*/
*/
const
nextConfig
=
{}
const
nextConfig
=
{
serverExternalPackages
:
[
'hmr-external'
,
'./lib/hmr-file-external'
],
}
module
.
exports
=
nextConfig
module
.
exports
=
nextConfig
test/development/app-dir/server-hmr/node_modules/hmr-external/index.js
0 → 100644
View file @
adb87bfa
module
.
exports
=
{
value
:
'external-value: 0'
}
test/development/app-dir/server-hmr/node_modules/hmr-external/package.json
0 → 100644
View file @
adb87bfa
{
"name"
:
"hmr-external"
,
"version"
:
"0.0.1"
,
"main"
:
"index.js"
}
test/development/app-dir/server-hmr/server-hmr.test.ts
View file @
adb87bfa
...
@@ -156,6 +156,48 @@ describe('server-hmr', () => {
...
@@ -156,6 +156,48 @@ describe('server-hmr', () => {
)
)
})
})
describe
(
'external package hmr'
,
()
=>
{
itTurbopackDev
(
'reflects changes to a node_modules serverExternalPackages module on the next request'
,
async
()
=>
{
const
initial
=
await
next
.
render$
(
'/external'
)
expect
(
initial
(
'#value'
).
text
()).
toBe
(
'external-value: 0'
)
// Patch the external package directly — it lives outside Turbopack's
// module graph so server HMR cannot patch it in-place. The runtime must
// fall back to clearing require.cache so the updated file is re-required
// on the next request.
await
next
.
patchFile
(
'node_modules/hmr-external/index.js'
,
(
content
)
=>
content
.
replace
(
'external-value: 0'
,
'external-value: 1'
)
)
await
retry
(
async
()
=>
{
const
updated
=
await
next
.
render$
(
'/external'
)
expect
(
updated
(
'#value'
).
text
()).
toBe
(
'external-value: 1'
)
})
}
)
itTurbopackDev
(
'reflects changes to a non-node_modules serverExternalPackages file on the next request'
,
async
()
=>
{
const
initial
=
await
next
.
render$
(
'/external'
)
expect
(
initial
(
'#file-value'
).
text
()).
toBe
(
'file-external-value: 0'
)
// Patch the external file directly — it lives outside Turbopack's
// module graph so server HMR cannot patch it in-place.
await
next
.
patchFile
(
'lib/hmr-file-external.js'
,
(
content
)
=>
content
.
replace
(
'file-external-value: 0'
,
'file-external-value: 1'
)
)
await
retry
(
async
()
=>
{
const
updated
=
await
next
.
render$
(
'/external'
)
expect
(
updated
(
'#file-value'
).
text
()).
toBe
(
'file-external-value: 1'
)
})
}
)
})
describe
(
'route handler hmr'
,
()
=>
{
describe
(
'route handler hmr'
,
()
=>
{
function
getText
(
res
:
Response
)
{
function
getText
(
res
:
Response
)
{
return
res
.
ok
return
res
.
ok
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment