Commit 419ecf0e authored by Jiachi Liu's avatar Jiachi Liu

Add SSE endpoint for HMR cycle events (/_next/dev/events)

AI agents editing files during `next dev` have no way to know when
compilation finishes or whether it succeeded. They must poll separate
endpoints and correlate results manually.

Add a Server-Sent Events endpoint at `/_next/dev/events` that streams
every HMR build cycle as it happens. Each event includes compilation
status, errors, duration, and which pages changed — giving subscribers
an atomic view of each edit cycle without polling.

Gated behind `NEXT_DEV_EVENTS=1` env var. Works with both Turbopack
and webpack.

```
NEXT_DEV_EVENTS=1 next dev
curl -N http://localhost:3000/_next/dev/events
```
parent 9cb20484
/**
* SSE endpoint at /_next/dev/events
*
* Streams HMR cycle results to subscribers. Gated behind NEXT_DEV_EVENTS=1.
*
* Usage:
* curl -N http://localhost:3000/_next/dev/events
*/
import type { ServerResponse, IncomingMessage } from 'http'
import { subscribe, type HmrBuildResult } from './hmr-cycle-emitter'
export function getDevEventsMiddleware() {
return async function devEventsMiddleware(
req: IncomingMessage,
res: ServerResponse,
next: () => void
): Promise<void> {
const { pathname } = new URL(req.url || '', 'http://n')
if (
pathname !== '/_next/dev/events' ||
req.method !== 'GET' ||
process.env.NEXT_DEV_EVENTS !== '1'
) {
return next()
}
res.writeHead(200, {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache, no-transform',
Connection: 'keep-alive',
})
res.write(`data: ${JSON.stringify({ type: 'connected' })}\n\n`)
const unsubscribe = subscribe((result: HmrBuildResult) => {
const changedPages = result.changedEntries
.map((key) => {
try {
return JSON.parse(key).page as string
} catch {
return key
}
})
.filter((v, i, a) => a.indexOf(v) === i)
const event = {
type: 'hmr',
compilation: {
status: result.errors.length > 0 ? 'compile_error' : 'ok',
version: result.hash,
duration_ms: result.durationMs,
errors: result.errors,
warnings: result.warnings,
changed_pages: changedPages,
},
}
res.write(`data: ${JSON.stringify(event)}\n\n`)
})
res.on('close', () => {
unsubscribe()
})
}
}
/**
* Event emitter for HMR build cycles.
*
* The hot reloader emits `building` when compilation starts and `built` when
* it finishes (with or without errors). Between start and end, changed entry
* keys are collected so the emitted result includes which pages were affected.
*/
import type { CompilationError } from './hot-reloader-types'
export interface HmrBuildResult {
hash: string
errors: ReadonlyArray<CompilationError>
warnings: ReadonlyArray<CompilationError>
changedEntries: ReadonlyArray<string>
durationMs: number
}
type BuildListener = (result: HmrBuildResult) => void
let buildingStartTime: number | undefined
const pendingChangedEntries = new Set<string>()
const listeners = new Set<BuildListener>()
export function emitHmrBuilding(): void {
buildingStartTime = Date.now()
pendingChangedEntries.clear()
}
/**
* Record that an entry changed during the current build cycle.
* Called from sendHmr / per-entry subscription handlers.
*/
export function recordChangedEntry(entryKey: string): void {
pendingChangedEntries.add(entryKey)
}
export function emitHmrBuilt(
result: Omit<HmrBuildResult, 'durationMs' | 'changedEntries'>,
durationMs?: number
): void {
const elapsed =
durationMs ??
(buildingStartTime != null ? Date.now() - buildingStartTime : 0)
buildingStartTime = undefined
const changedEntries = Array.from(pendingChangedEntries)
pendingChangedEntries.clear()
const fullResult: HmrBuildResult = {
...result,
changedEntries,
durationMs: elapsed,
}
for (const listener of listeners) {
listener(fullResult)
}
}
/**
* Subscribe to all future HMR build results.
* Returns an unsubscribe function.
*/
export function subscribe(listener: BuildListener): () => void {
listeners.add(listener)
return () => {
listeners.delete(listener)
}
}
......@@ -128,6 +128,12 @@ import {
import { getMcpMiddleware } from '../mcp/get-mcp-middleware'
import { handleErrorStateResponse } from '../mcp/tools/get-errors'
import { handlePageMetadataResponse } from '../mcp/tools/get-page-metadata'
import {
emitHmrBuilding,
emitHmrBuilt,
recordChangedEntry,
} from './hmr-cycle-emitter'
import { getDevEventsMiddleware } from './dev-events-middleware'
import { setStackFrameResolver } from '../mcp/tools/utils/format-errors'
import { recordMcpTelemetry } from '../mcp/mcp-telemetry-tracker'
import { getFileLogger } from './browser-logs/file-logger'
......@@ -761,6 +767,8 @@ export async function createHotReloaderTurbopack(
const sendEnqueuedMessagesDebounce = debounce(sendEnqueuedMessages, 2)
const sendHmr: SendHmr = (id: string, message: HmrMessageSentToBrowser) => {
recordChangedEntry(id)
for (const client of [
...clientsWithoutHtmlRequestId,
...clientsByHtmlRequestId.values(),
......@@ -1037,6 +1045,7 @@ export async function createHotReloaderTurbopack(
},
}),
getAttachNodejsDebuggerMiddleware(),
getDevEventsMiddleware(),
...(nextConfig.experimental.mcpServer
? [
getMcpMiddleware({
......@@ -1751,6 +1760,7 @@ export async function createHotReloaderTurbopack(
for await (const updateMessage of project.updateInfoSubscribe(30)) {
switch (updateMessage.updateType) {
case 'start': {
emitHmrBuilding()
hotReloader.send({ type: HMR_MESSAGE_SENT_TO_BROWSER.BUILDING })
// Mark that HMR has started and we need to call the callback after it settles
// This ensures onBeforeDeferredEntries will be called again during HMR
......@@ -1816,6 +1826,15 @@ export async function createHotReloaderTurbopack(
})
}
emitHmrBuilt(
{
hash: String(hmrHash),
errors: [...errors.values()],
warnings: [],
},
updateMessage.value.duration
)
if (hmrEventHappened) {
const time = updateMessage.value.duration
const timeMessage =
......
......@@ -111,6 +111,12 @@ import {
matchNextPageBundleRequest,
} from './hot-reloader-shared-utils'
import { getMcpMiddleware } from '../mcp/get-mcp-middleware'
import {
emitHmrBuilding,
emitHmrBuilt,
recordChangedEntry,
} from './hmr-cycle-emitter'
import { getDevEventsMiddleware } from './dev-events-middleware'
import { setStackFrameResolver } from '../mcp/tools/utils/format-errors'
import { recordMcpTelemetry } from '../mcp/mcp-telemetry-tracker'
import { getFileLogger } from './browser-logs/file-logger'
......@@ -1555,6 +1561,51 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
this.refreshServerComponents(stats.hash)
}
// Record changed entries for the HMR cycle emitter
for (const page of changedClientPages) {
recordChangedEntry(page)
}
for (const page of changedServerPages) {
recordChangedEntry(page)
}
for (const page of changedEdgeServerPages) {
recordChangedEntry(page)
}
for (const page of changedServerComponentPages) {
recordChangedEntry(page)
}
// Emit HMR cycle result for the SSE events endpoint.
// This fires after ALL compilers (client, server, edge) are done.
const allStats = stats.stats.flatMap((s) => {
const json = s.toJson({
all: false,
hash: true,
errors: true,
warnings: true,
})
return json
})
const errors = allStats.flatMap((s) =>
(s.errors || []).map((e: any) => ({
message: typeof e === 'string' ? e : e.message,
details: typeof e === 'string' ? undefined : e.details,
moduleName: typeof e === 'string' ? undefined : e.moduleName,
}))
)
const warnings = allStats.flatMap((s) =>
(s.warnings || []).map((w: any) => ({
message: typeof w === 'string' ? w : w.message,
details: typeof w === 'string' ? undefined : w.details,
moduleName: typeof w === 'string' ? undefined : w.moduleName,
}))
)
emitHmrBuilt({
hash: stats.hash,
errors,
warnings,
})
changedClientPages.clear()
changedServerPages.clear()
changedEdgeServerPages.clear()
......@@ -1621,6 +1672,13 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
initialDevToolsConfig
)
// Emit HMR building signal when any compiler starts.
// This pairs with emitHmrBuilt in the multiCompiler.hooks.done above.
this.multiCompiler.compilers[0].hooks.invalid.tap(
'NextjsHmrCycleEmitter',
() => emitHmrBuilding()
)
let booted = false
this.watcher = await new Promise((resolve) => {
......@@ -1687,6 +1745,7 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
},
}),
getAttachNodejsDebuggerMiddleware(),
getDevEventsMiddleware(),
...(this.config.experimental.mcpServer
? [
getMcpMiddleware({
......
// This file is intentionally empty.
// The dev_cycle MCP tool has been replaced by the SSE events endpoint
// at /_next/mcp/events. See get-mcp-middleware.ts for the implementation.
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Page() {
return <h1>Hello World</h1>
}
import path from 'path'
import { nextTestSetup } from 'e2e-utils'
import { retry } from 'next-test-utils'
import http from 'http'
describe('mcp-server /_next/dev/events SSE', () => {
const { next, skipped } = nextTestSetup({
files: path.join(__dirname, 'fixtures', 'hmr-cycle-app'),
skipDeployment: true,
env: {
NEXT_DEV_EVENTS: '1',
},
})
if (skipped) {
return
}
/** Subscribe to the SSE stream. Returns collected events + a close function. */
function subscribeEvents(): {
events: any[]
close: () => void
waitForEvent: (
predicate: (e: any) => boolean,
timeoutMs?: number
) => Promise<any>
} {
const events: any[] = []
let waitResolve: ((e: any) => void) | null = null
let waitPredicate: ((e: any) => boolean) | null = null
const url = new URL('/_next/dev/events', next.url)
const req = http.get(url, (res) => {
let buffer = ''
res.on('data', (chunk: Buffer) => {
buffer += chunk.toString()
// Parse SSE messages
const parts = buffer.split('\n\n')
buffer = parts.pop()! // keep incomplete last part
for (const part of parts) {
const match = part.match(/^data: (.+)$/m)
if (match) {
const event = JSON.parse(match[1])
events.push(event)
if (waitResolve && waitPredicate && waitPredicate(event)) {
waitResolve(event)
waitResolve = null
waitPredicate = null
}
}
}
})
})
return {
events,
close: () => req.destroy(),
waitForEvent: (predicate, timeoutMs = 30000) =>
new Promise((resolve, reject) => {
// Check already-received events
const found = events.find(predicate)
if (found) return resolve(found)
waitPredicate = predicate
waitResolve = resolve
setTimeout(() => {
waitResolve = null
reject(new Error('Timeout waiting for SSE event'))
}, timeoutMs)
}),
}
}
function log(line: string) {
console.log(line)
}
function logEvent(label: string, snippet: string, event: any) {
const c = event.compilation
log(`── ${label} ${'─'.repeat(Math.max(0, 52 - label.length))}`)
log(` write app/page.tsx`)
log(` ${snippet}`)
const tag = c.status === 'ok' ? 'ok' : 'FAIL'
log(` compile ${tag} ${c.duration_ms}ms v${c.version}`)
if (c.changed_pages?.length > 0) {
log(` changed ${c.changed_pages.join(', ')}`)
}
if (c.errors.length > 0) {
for (const e of c.errors.slice(0, 2)) {
log(` error ${e.message.split('\n')[0].slice(0, 60)}`)
}
}
log('')
}
it('build error → fix → recovery', async () => {
// Warm up
await retry(async () => {
const res = await next.fetch('/')
expect(res.status).toBe(200)
})
await new Promise((r) => setTimeout(r, 1000))
const sub = subscribeEvents()
// Wait for connected event
await sub.waitForEvent((e) => e.type === 'connected')
log('')
log('=== Build Error Recovery (SSE) ===')
log('')
// v1: working
await next.patchFile(
'app/page.tsx',
`export default function Page() {\n return <h1>working</h1>\n}`
)
const e1 = await sub.waitForEvent(
(e) => e.type === 'hmr' && e.compilation.status === 'ok'
)
logEvent('v1 working', '<h1>working</h1>', e1)
expect(e1.compilation.status).toBe('ok')
// v2: break it
await next.patchFile(
'app/page.tsx',
`import { x } from 'pkg-not-found'\nexport default function Page() {\n return <h1>{x}</h1>\n}`
)
const e2 = await sub.waitForEvent(
(e) =>
e.type === 'hmr' && e.compilation.version !== e1.compilation.version
)
logEvent('v2 break (missing import)', "import from 'pkg-not-found'", e2)
expect(e2.compilation.status).toBe('compile_error')
expect(e2.compilation.errors.length).toBeGreaterThan(0)
// v3: fix
await next.patchFile(
'app/page.tsx',
`export default function Page() {\n return <h1>fixed</h1>\n}`
)
const e3 = await sub.waitForEvent(
(e) =>
e.type === 'hmr' &&
e.compilation.version !== e2.compilation.version &&
e.compilation.status === 'ok'
)
logEvent('v3 fix', '<h1>fixed</h1>', e3)
expect(e3.compilation.status).toBe('ok')
sub.close()
})
it('runtime error → fix → recovery', async () => {
await retry(async () => {
const res = await next.fetch('/')
expect(res.status).toBe(200)
})
const sub = subscribeEvents()
await sub.waitForEvent((e) => e.type === 'connected')
log('')
log('=== Runtime Error Recovery (SSE) ===')
log('')
// v1: working
await next.patchFile(
'app/page.tsx',
`export default function Page() {\n return <h1>working</h1>\n}`
)
const e1 = await sub.waitForEvent((e) => e.type === 'hmr')
logEvent('v1 working', '<h1>working</h1>', e1)
// v2: runtime throw
await next.patchFile(
'app/page.tsx',
`export default function Page() {\n throw new Error('boom')\n}`
)
const e2 = await sub.waitForEvent(
(e) =>
e.type === 'hmr' && e.compilation.version !== e1.compilation.version
)
logEvent('v2 break (throw in render)', "throw new Error('boom')", e2)
// Compiles fine — it's valid JS
expect(e2.compilation.status).toBe('ok')
// But verify the page returns 500
const pageRes = await next.fetch('/')
expect(pageRes.status).toBe(500)
log(` page FAIL 500`)
log('')
// v3: fix
await next.patchFile(
'app/page.tsx',
`export default function Page() {\n return <h1>fixed</h1>\n}`
)
const e3 = await sub.waitForEvent(
(e) =>
e.type === 'hmr' && e.compilation.version !== e2.compilation.version
)
logEvent('v3 fix', '<h1>fixed</h1>', e3)
const fixedRes = await next.fetch('/')
expect(fixedRes.status).toBe(200)
log(` page 200`)
log('')
sub.close()
})
})
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