Add OSC 9;4 terminal progress bar to next build

Emit an OSC 9;4 progress sequence during `next build` so supporting
terminals ConEmu, Ghostty, foot, Rio, Windows Terminal, and more) render
a taskbar/tab progress bar for the build. Terminals without support ignore
the sequence, so it is safe to emit on any TTY.

The result is a progress bar rendered while the build proceeds.

The build has no single unit of total work, so it is modeled as weighted
stages that each own a band of the 0-100% range. Counted stages
(collect-page-data, static generation) fill their band from real counts;
uncounted stages (compile, type-check) ease toward the band end over time
so the bar keeps moving, then snap on completion.

Enabled only on an interactive TTY outside CI; opt out with
NEXT_DISABLE_BUILD_PROGRESS. Cleared on completion, failure, and
interrupt (SIGINT/SIGTERM) via the existing CLI process.exit path.
parent 1ecd8f1b
...@@ -122,6 +122,7 @@ import { generateBuildId } from './generate-build-id' ...@@ -122,6 +122,7 @@ import { generateBuildId } from './generate-build-id'
import { isWriteable } from './is-writeable' import { isWriteable } from './is-writeable'
import * as Log from './output/log' import * as Log from './output/log'
import createSpinner from './spinner' import createSpinner from './spinner'
import { createBuildProgressBar } from './progress-bar'
import { trace, flushAllTraces, setGlobal, type Span } from '../trace' import { trace, flushAllTraces, setGlobal, type Span } from '../trace'
import { writeRouteBundleStats } from './route-bundle-stats' import { writeRouteBundleStats } from './route-bundle-stats'
import { import {
...@@ -950,6 +951,10 @@ export default async function build( ...@@ -950,6 +951,10 @@ export default async function build(
let loadedConfig: NextConfigComplete | undefined let loadedConfig: NextConfigComplete | undefined
let staticWorker: StaticWorker let staticWorker: StaticWorker
// Drives an OSC 9;4 terminal progress bar across the build stages. No-op when
// not attached to a TTY, in CI, or when NEXT_DISABLE_BUILD_PROGRESS is set.
const buildProgress = createBuildProgressBar()
// Turbopack compile warnings are deferred until after static generation. // Turbopack compile warnings are deferred until after static generation.
let deferredTurbopackWarnings: string[] | undefined let deferredTurbopackWarnings: string[] | undefined
const flushTurbopackWarnings = () => { const flushTurbopackWarnings = () => {
...@@ -986,6 +991,8 @@ export default async function build( ...@@ -986,6 +991,8 @@ export default async function build(
.traceFn(() => loadEnvConfig(dir, false, Log)) .traceFn(() => loadEnvConfig(dir, false, Log))
NextBuildContext.loadedEnvFiles = loadedEnvFiles NextBuildContext.loadedEnvFiles = loadedEnvFiles
buildProgress.startStage('setup')
// Log the version banner before loading the config just like `dev` // Log the version banner before loading the config just like `dev`
logStartInfo({ logStartInfo({
networkUrl: null, networkUrl: null,
...@@ -1639,6 +1646,9 @@ export default async function build( ...@@ -1639,6 +1646,9 @@ export default async function build(
// #region Compile // #region Compile
buildProgress.completeStage('setup')
buildProgress.startStage('compile')
Log.info('Creating an optimized production build ...') Log.info('Creating an optimized production build ...')
traceMemoryUsage('Starting build', nextBuildSpan) traceMemoryUsage('Starting build', nextBuildSpan)
...@@ -1813,13 +1823,17 @@ export default async function build( ...@@ -1813,13 +1823,17 @@ export default async function build(
// #endregion // #endregion
buildProgress.completeStage('compile')
// For app directory, we run type checking after build. // For app directory, we run type checking after build.
if (appDir && !isCompileMode && !isGenerateMode) { if (appDir && !isCompileMode && !isGenerateMode) {
buildProgress.startStage('type-check')
await updateBuildDiagnostics({ await updateBuildDiagnostics({
buildStage: 'type-checking', buildStage: 'type-checking',
}) })
await startTypeChecking(typeCheckingOptions) await startTypeChecking(typeCheckingOptions)
traceMemoryUsage('Finished type checking', nextBuildSpan) traceMemoryUsage('Finished type checking', nextBuildSpan)
buildProgress.completeStage('type-check')
} }
// #region required-server-files // #region required-server-files
...@@ -2025,6 +2039,17 @@ export default async function build( ...@@ -2025,6 +2039,17 @@ export default async function build(
`Collecting page data using ${numberOfWorkers} worker${numberOfWorkers > 1 ? 's' : ''}` `Collecting page data using ${numberOfWorkers} worker${numberOfWorkers > 1 ? 's' : ''}`
) )
buildProgress.startStage('collect-page-data')
let collectedPageCount = 0
const onPageDataCollected = () => {
collectedPageCount++
buildProgress.setStageFraction(
'collect-page-data',
collectedPageCount,
totalPageCount
)
}
const buildManifestPath = path.join(distDir, BUILD_MANIFEST) const buildManifestPath = path.join(distDir, BUILD_MANIFEST)
let staticAppPagesCount = 0 let staticAppPagesCount = 0
...@@ -2590,6 +2615,7 @@ export default async function build( ...@@ -2590,6 +2615,7 @@ export default async function build(
}) })
}) })
}) })
.map((pagePromise) => pagePromise.finally(onPageDataCollected))
) )
const errorPageResult = await errorPageStaticResult const errorPageResult = await errorPageStaticResult
...@@ -2614,6 +2640,7 @@ export default async function build( ...@@ -2614,6 +2640,7 @@ export default async function build(
) )
postCompileSpinner.stopAndPersist() postCompileSpinner.stopAndPersist()
} }
buildProgress.completeStage('collect-page-data')
traceMemoryUsage('Finished collecting page data', nextBuildSpan) traceMemoryUsage('Finished collecting page data', nextBuildSpan)
if (customAppGetInitialProps) { if (customAppGetInitialProps) {
...@@ -3051,6 +3078,7 @@ export default async function build( ...@@ -3051,6 +3078,7 @@ export default async function build(
} }
const outdir = path.join(distDir, 'export') const outdir = path.join(distDir, 'export')
buildProgress.startStage('static-generation')
const exportResult = await exportApp( const exportResult = await exportApp(
dir, dir,
{ {
...@@ -3066,11 +3094,19 @@ export default async function build( ...@@ -3066,11 +3094,19 @@ export default async function build(
numWorkers: numberOfWorkers, numWorkers: numberOfWorkers,
appDirOnly, appDirOnly,
bundler, bundler,
onProgress: (done, total) =>
buildProgress.setStageFraction(
'static-generation',
done,
total
),
}, },
nextBuildSpan, nextBuildSpan,
staticWorker staticWorker
) )
buildProgress.completeStage('static-generation')
// If there was no result, there's nothing more to do. // If there was no result, there's nothing more to do.
if (!exportResult) return if (!exportResult) return
...@@ -3962,6 +3998,7 @@ export default async function build( ...@@ -3962,6 +3998,7 @@ export default async function build(
flushTurbopackWarnings() flushTurbopackWarnings()
buildProgress.startStage('finalize')
const finalizingPageOptimizationStart = process.hrtime() const finalizingPageOptimizationStart = process.hrtime()
const postBuildSpinner = createSpinner('Finalizing page optimization') const postBuildSpinner = createSpinner('Finalizing page optimization')
let buildTracesSpinner let buildTracesSpinner
...@@ -4287,6 +4324,9 @@ export default async function build( ...@@ -4287,6 +4324,9 @@ export default async function build(
) )
postBuildSpinner.stopAndPersist() postBuildSpinner.stopAndPersist()
} }
buildProgress.finish()
console.log() console.log()
if (debugOutput) { if (debugOutput) {
...@@ -4348,6 +4388,7 @@ export default async function build( ...@@ -4348,6 +4388,7 @@ export default async function build(
} }
}) })
} catch (e) { } catch (e) {
buildProgress.fail()
const telemetry: Telemetry | undefined = traceGlobals.get('telemetry') const telemetry: Telemetry | undefined = traceGlobals.get('telemetry')
if (telemetry) { if (telemetry) {
telemetry.record( telemetry.record(
......
// The CI gate reads `isCI` from this module at construction time; force it off
// so the bar is enabled for the "enabled" tests below.
jest.mock('../server/ci-info', () => ({ isCI: false }))
import { createBuildProgressBar } from './progress-bar'
const ESC = '\x1b'
const BEL = '\x07'
/** Parse the `<state>;<pct>` pairs out of captured OSC 9;4 writes. */
function parseOsc(writes: string[]): Array<{ state: number; pct: number }> {
return writes
.join('')
.split(BEL)
.filter(Boolean)
.map((seq) => {
const match = seq.match(/\]9;4;(\d+);(\d+)$/)
if (!match) {
throw new Error(`unexpected sequence: ${JSON.stringify(seq)}`)
}
return { state: Number(match[1]), pct: Number(match[2]) }
})
}
describe('createBuildProgressBar', () => {
let writeSpy: jest.SpyInstance
let writes: string[]
const originalIsTTY = process.stdout.isTTY
const originalDisable = process.env.NEXT_DISABLE_BUILD_PROGRESS
beforeEach(() => {
writes = []
writeSpy = jest
.spyOn(process.stdout, 'write')
.mockImplementation((chunk: any) => {
writes.push(String(chunk))
return true
})
;(process.stdout as any).isTTY = true
delete process.env.NEXT_DISABLE_BUILD_PROGRESS
})
afterEach(() => {
writeSpy.mockRestore()
;(process.stdout as any).isTTY = originalIsTTY
if (originalDisable === undefined) {
delete process.env.NEXT_DISABLE_BUILD_PROGRESS
} else {
process.env.NEXT_DISABLE_BUILD_PROGRESS = originalDisable
}
jest.useRealTimers()
})
it('emits well-formed OSC 9;4 sequences with ESC prefix and BEL terminator', () => {
const bar = createBuildProgressBar()
bar.startStage('collect-page-data')
bar.setStageFraction('collect-page-data', 1, 1)
expect(writes.every((w) => w.startsWith(`${ESC}]9;4;`))).toBe(true)
expect(writes.every((w) => w.endsWith(BEL))).toBe(true)
})
it('maps a counted stage fraction into its band', () => {
const bar = createBuildProgressBar()
// collect-page-data band is 74 -> 88, so 50% => 81.
bar.setStageFraction('collect-page-data', 5, 10)
const events = parseOsc(writes)
expect(events.at(-1)).toEqual({ state: 1, pct: 81 })
})
it('never moves the bar backwards', () => {
const bar = createBuildProgressBar()
bar.setStageFraction('collect-page-data', 8, 10) // ~85
bar.setStageFraction('collect-page-data', 2, 10) // would be ~77, ignored
const pcts = parseOsc(writes).map((e) => e.pct)
for (let i = 1; i < pcts.length; i++) {
expect(pcts[i]).toBeGreaterThanOrEqual(pcts[i - 1])
}
})
it('snaps to the band end on completeStage', () => {
const bar = createBuildProgressBar()
bar.startStage('collect-page-data')
bar.setStageFraction('collect-page-data', 1, 10)
bar.completeStage('collect-page-data')
expect(parseOsc(writes).at(-1)).toEqual({ state: 1, pct: 88 })
})
it('eases toward the band end without reaching it, then snaps on completion', () => {
jest.useFakeTimers()
const bar = createBuildProgressBar()
bar.startStage('compile') // band 3 -> 62, easing
jest.advanceTimersByTime(250 * 20)
const beforeComplete = parseOsc(writes).at(-1)!
expect(beforeComplete.pct).toBeGreaterThan(3)
expect(beforeComplete.pct).toBeLessThan(62)
bar.completeStage('compile')
expect(parseOsc(writes).at(-1)).toEqual({ state: 1, pct: 62 })
})
it('finish fills to 100 then clears the bar', () => {
const bar = createBuildProgressBar()
bar.startStage('finalize')
bar.finish()
const events = parseOsc(writes)
expect(events.some((e) => e.state === 1 && e.pct === 100)).toBe(true)
expect(events.at(-1)).toEqual({ state: 0, pct: 0 })
})
it('fail emits the error state then clears the bar', () => {
const bar = createBuildProgressBar()
bar.startStage('compile')
bar.setStageFraction('collect-page-data', 1, 2)
bar.fail()
const events = parseOsc(writes)
expect(events.some((e) => e.state === 2)).toBe(true)
expect(events.at(-1)).toEqual({ state: 0, pct: 0 })
})
it('is a no-op when not attached to a TTY', () => {
;(process.stdout as any).isTTY = false
const bar = createBuildProgressBar()
bar.startStage('compile')
bar.setStageFraction('collect-page-data', 1, 2)
bar.completeStage('compile')
bar.finish()
expect(writes).toHaveLength(0)
})
it('is a no-op when NEXT_DISABLE_BUILD_PROGRESS is set', () => {
process.env.NEXT_DISABLE_BUILD_PROGRESS = '1'
const bar = createBuildProgressBar()
bar.startStage('compile')
bar.finish()
expect(writes).toHaveLength(0)
})
})
describe('createBuildProgressBar in CI', () => {
it('is a no-op when isCI is true', () => {
jest.resetModules()
jest.doMock('../server/ci-info', () => ({ isCI: true }))
const writes: string[] = []
const writeSpy = jest
.spyOn(process.stdout, 'write')
.mockImplementation((chunk: any) => {
writes.push(String(chunk))
return true
})
const originalIsTTY = process.stdout.isTTY
;(process.stdout as any).isTTY = true
try {
const { createBuildProgressBar: create } =
require('./progress-bar') as typeof import('./progress-bar')
const bar = create()
bar.startStage('compile')
bar.finish()
expect(writes).toHaveLength(0)
} finally {
writeSpy.mockRestore()
;(process.stdout as any).isTTY = originalIsTTY
jest.dontMock('../server/ci-info')
jest.resetModules()
}
})
})
import * as ciEnvironment from '../server/ci-info'
/**
* OSC 9;4 terminal progress reporting for `next build`.
*
* The build has no single unit of "total work", so we model it as a fixed set
* of weighted stages, each owning a band of the overall 0-100% range. Stages
* that expose a real count (collecting page data, static generation) fill their
* band from that count; stages that don't (compiling, type checking) ease
* toward their band end over time so the bar keeps visibly moving. This is
* deliberately heuristic — the goal is "roughly right and always moving", not
* byte-accurate progress.
*
* The OSC 9;4 sequence (`ESC ] 9 ; 4 ; <state> ; <progress> BEL`) is rendered
* as an OS taskbar / terminal-tab progress bar by terminals that support it
* (Windows Terminal, ConEmu, WezTerm, Ghostty, foot, Rio). Terminals that don't
* support it ignore the sequence silently, so it is safe to emit on any TTY.
*/
export type BuildProgressStage =
| 'setup'
| 'compile'
| 'type-check'
| 'collect-page-data'
| 'static-generation'
| 'finalize'
interface Band {
start: number
end: number
}
/**
* Fixed bands applied in pipeline order. Stages that don't run in a given build
* (compile-only / generate-only mode, no app dir, zero export paths) simply
* leave the bar wherever it was; the next stage that starts advances it to its
* band start.
*/
const BANDS: Record<BuildProgressStage, Band> = {
setup: { start: 0, end: 3 },
compile: { start: 3, end: 62 },
'type-check': { start: 62, end: 74 },
'collect-page-data': { start: 74, end: 88 },
'static-generation': { start: 88, end: 99 },
finalize: { start: 99, end: 100 },
}
/** OSC 9;4 progress states we use. */
const enum OscState {
Clear = 0,
Normal = 1,
Error = 2,
}
/** How often the easing timer ticks, in milliseconds. */
const EASE_INTERVAL_MS = 250
/**
* Easing factor per tick. On each tick the current position moves this fraction
* of the remaining distance to the band end, so it approaches but never reaches
* the end until the stage completes and snaps it there.
*/
const EASE_FACTOR = 0.06
export interface BuildProgressBar {
/** Enter a stage. Starts easing for stages without a real count. */
startStage(stage: BuildProgressStage): void
/** Fill a counted stage's band from `done`/`total`. */
setStageFraction(stage: BuildProgressStage, done: number, total: number): void
/** Leave a stage, snapping the bar to the band end. */
completeStage(stage: BuildProgressStage): void
/** Mark the build complete: fill to 100%, then clear the bar. */
finish(): void
/** Mark the build as failed: show the error state, then clear the bar. */
fail(): void
}
/** A progress bar that does nothing, used when reporting is disabled. */
const noopBuildProgressBar: BuildProgressBar = {
startStage() {},
setStageFraction() {},
completeStage() {},
finish() {},
fail() {},
}
function writeOsc(state: OscState, progress: number): void {
// Clamp to the 0-100 integer range OSC 9;4 expects.
const pct = Math.max(0, Math.min(100, Math.round(progress)))
process.stdout.write(`\x1b]9;4;${state};${pct}\x07`)
}
/**
* Create a build progress bar. Returns a no-op implementation (with the same
* shape, so call sites need no conditionals) when reporting is disabled:
* non-TTY output, CI environments, or when `NEXT_DISABLE_BUILD_PROGRESS` is set.
*/
export function createBuildProgressBar(): BuildProgressBar {
if (
!process.stdout.isTTY ||
ciEnvironment.isCI ||
process.env.NEXT_DISABLE_BUILD_PROGRESS
) {
return noopBuildProgressBar
}
// The last integer percent we emitted, so we only write on change (OSC
// progress is an integer, so this is natural throttling).
let lastEmitted = -1
// The current fractional position of the bar (0-100).
let current = 0
let easeTimer: ReturnType<typeof setInterval> | undefined
let cleanedUp = false
const emit = (state: OscState, progress: number): void => {
const pct = Math.round(progress)
if (state === OscState.Normal && pct === lastEmitted) {
return
}
lastEmitted = pct
writeOsc(state, progress)
}
const advanceTo = (progress: number): void => {
// Never move the bar backwards.
if (progress <= current) {
return
}
current = progress
emit(OscState.Normal, current)
}
const stopEasing = (): void => {
if (easeTimer) {
clearInterval(easeTimer)
easeTimer = undefined
}
}
const clear = (): void => {
if (cleanedUp) {
return
}
cleanedUp = true
stopEasing()
writeOsc(OscState.Clear, 0)
process.removeListener('exit', onExit)
process.removeListener('SIGINT', onSigint)
}
// Ensure an interrupted or crashed build never leaves a stuck taskbar bar.
const onExit = (): void => clear()
const onSigint = (): void => clear()
process.on('exit', onExit)
process.on('SIGINT', onSigint)
return {
startStage(stage) {
const band = BANDS[stage]
stopEasing()
advanceTo(band.start)
// Counted stages fill their band from setStageFraction instead of easing.
if (stage === 'collect-page-data' || stage === 'static-generation') {
return
}
easeTimer = setInterval(() => {
// Asymptotically approach the band end without reaching it; the stage's
// completeStage snaps to the end.
advanceTo(current + (band.end - current) * EASE_FACTOR)
}, EASE_INTERVAL_MS)
// Don't keep the process alive just for the progress timer.
easeTimer.unref?.()
},
setStageFraction(stage, done, total) {
const band = BANDS[stage]
if (total <= 0) {
return
}
const fraction = Math.max(0, Math.min(1, done / total))
advanceTo(band.start + (band.end - band.start) * fraction)
},
completeStage(stage) {
stopEasing()
advanceTo(BANDS[stage].end)
},
finish() {
stopEasing()
current = 100
emit(OscState.Normal, 100)
clear()
},
fail() {
stopEasing()
emit(OscState.Error, current)
clear()
},
}
}
...@@ -781,10 +781,22 @@ async function exportAppImpl( ...@@ -781,10 +781,22 @@ async function exportAppImpl(
`Exporting using ${options.numWorkers} worker${options.numWorkers > 1 ? 's' : ''}` `Exporting using ${options.numWorkers} worker${options.numWorkers > 1 ? 's' : ''}`
) )
// Wrap `progress.run` so that, in addition to the spinner, we can report
// completed/total to the build progress bar via `options.onProgress`.
let exportedPathCount = 0
const trackedProgress = {
run: () => {
exportedPathCount++
options.onProgress?.(exportedPathCount, totalExportPaths)
progress.run()
},
clear: progress.clear,
}
if (staticWorker) { if (staticWorker) {
// TODO: progress shouldn't rely on "activity" event sent from `exportPage`. // TODO: progress shouldn't rely on "activity" event sent from `exportPage`.
staticWorker.setOnActivity(progress.run) staticWorker.setOnActivity(trackedProgress.run)
staticWorker.setOnActivityAbort(progress.clear) staticWorker.setOnActivityAbort(trackedProgress.clear)
worker = staticWorker worker = staticWorker
} else { } else {
worker = createStaticWorker(nextConfig, { worker = createStaticWorker(nextConfig, {
...@@ -792,7 +804,7 @@ async function exportAppImpl( ...@@ -792,7 +804,7 @@ async function exportAppImpl(
kind: 'export-page', kind: 'export-page',
}), }),
numberOfWorkers: options.numWorkers, numberOfWorkers: options.numWorkers,
progress, progress: trackedProgress,
}) })
} }
......
...@@ -114,6 +114,7 @@ export interface ExportAppOptions { ...@@ -114,6 +114,7 @@ export interface ExportAppOptions {
numWorkers: number numWorkers: number
appDirOnly: boolean appDirOnly: boolean
bundler: Bundler bundler: Bundler
onProgress?: (done: number, total: number) => void
} }
export type ExportPageMetadata = { export type ExportPageMetadata = {
......
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