fix #4178: add the --watch-delay= option

evanw · evanw · commit 1e3fb57adcbd · 2025-07-07T00:19:11.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -41,6 +41,12 @@
     (()=>{})();
     ```
 
+* Support a configurable delay in watch mode before rebuilding ([#3476](https://github.com/evanw/esbuild/issues/3476), [#4178](https://github.com/evanw/esbuild/issues/4178))
+
+    The `watch()` API now takes a `delay` option that lets you add a delay (in milliseconds) before rebuilding when a change is detected in watch mode. If you use a tool that regenerates multiple source files very slowly, this should make it more likely that esbuild's watch mode won't generate a broken intermediate build before the successful final build. This option is also available via the CLI using the `--watch-delay=` flag.
+
+    This should also help avoid confusion about the `watch()` API's options argument. It was previously empty to allow for future API expansion, which caused some people to think that the documentation was missing. It's no longer empty now that the `watch()` API has an option.
+
 * Allow mixed array for `entryPoints` API option ([#4223](https://github.com/evanw/esbuild/issues/4223))
 
     The TypeScript type definitions now allow you to pass a mixed array of both string literals and object literals to the `entryPoints` API option, such as `['foo.js', { out: 'lib', in: 'bar.js' }]`. This was always possible to do in JavaScript but the TypeScript type definitions were previously too restrictive.
diff --git a/cmd/esbuild/main.go b/cmd/esbuild/main.go
@@ -54,6 +54,7 @@ var helpText = func(colors logger.Colors) string {
                         safari11, edge16, node10, ie9, opera45, default esnext)
   --watch               Watch mode: rebuild on file system changes (stops when
                         stdin is closed, use "--watch=forever" to ignore stdin)
+  --watch-delay=...     How many milliseconds to wait before watch mode rebuilds
 
 ` + colors.Bold + `Advanced options:` + colors.Reset + `
   --allow-overwrite         Allow output files to overwrite input files
diff --git a/cmd/esbuild/service.go b/cmd/esbuild/service.go
@@ -334,7 +334,11 @@ func (service *serviceType) handleIncomingPacket(bytes []byte) {
 				go func() {
 					defer service.keepAliveWaitGroup.Done()
 					defer build.disposeWaitGroup.Done()
-					if err := ctx.Watch(api.WatchOptions{}); err != nil {
+					var options api.WatchOptions
+					if value, ok := request["delay"]; ok {
+						options.Delay = value.(int)
+					}
+					if err := ctx.Watch(options); err != nil {
 						service.sendPacket(encodeErrorPacket(p.id, err))
 					} else {
 						service.sendPacket(encodePacket(packet{
diff --git a/lib/shared/common.ts b/lib/shared/common.ts
@@ -1060,11 +1060,13 @@ function buildOrContextImpl(
         watch: (options = {}) => new Promise((resolve, reject) => {
           if (!streamIn.hasFS) throw new Error(`Cannot use the "watch" API in this environment`)
           const keys: OptionKeys = {}
+          const delay = getFlag(options, keys, 'delay', mustBeInteger)
           checkForInvalidFlags(options, keys, `in watch() call`)
           const request: protocol.WatchRequest = {
             command: 'watch',
             key: buildKey,
           }
+          if (delay) request.delay = delay
           sendRequest<protocol.WatchRequest, null>(refs, request, error => {
             if (error) reject(new Error(error))
             else resolve(undefined)
diff --git a/lib/shared/stdio_protocol.ts b/lib/shared/stdio_protocol.ts
@@ -98,6 +98,7 @@ export interface CancelRequest {
 export interface WatchRequest {
   command: 'watch'
   key: number
+  delay?: number
 }
 
 export interface OnServeRequest {
diff --git a/lib/shared/types.ts b/lib/shared/types.ts
@@ -513,7 +513,9 @@ export interface AnalyzeMetafileOptions {
   verbose?: boolean
 }
 
+/** Documentation: https://esbuild.github.io/api/#watch-arguments */
 export interface WatchOptions {
+  delay?: number // In milliseconds
 }
 
 export interface BuildContext<ProvidedOptions extends BuildOptions = BuildOptions> {
diff --git a/pkg/api/api.go b/pkg/api/api.go
@@ -501,7 +501,9 @@ type ServeResult struct {
 	Hosts []string
 }
 
+// Documentation: https://esbuild.github.io/api/#watch-arguments
 type WatchOptions struct {
+	Delay int // In milliseconds
 }
 
 type BuildContext interface {
diff --git a/pkg/api/api_impl.go b/pkg/api/api_impl.go
@@ -1081,6 +1081,7 @@ func (ctx *internalContext) Watch(options WatchOptions) error {
 		rebuild: func() fs.WatchData {
 			return ctx.rebuild().watchData
 		},
+		delayInMS: time.Duration(options.Delay),
 	}
 
 	// All subsequent builds will be watch mode builds
diff --git a/pkg/api/watcher.go b/pkg/api/watcher.go
@@ -51,6 +51,7 @@ type watcher struct {
 	data              fs.WatchData
 	fs                fs.FS
 	rebuild           func() fs.WatchData
+	delayInMS         time.Duration
 	recentItems       []string
 	itemsToScan       []string
 	mutex             sync.Mutex
@@ -68,7 +69,11 @@ func (w *watcher) setWatchData(data fs.WatchData) {
 	// Print something for the end of the first build
 	if w.shouldLog && w.data.Paths == nil {
 		logger.PrintTextWithColor(os.Stderr, w.useColor, func(colors logger.Colors) string {
-			return fmt.Sprintf("%s[watch] build finished, watching for changes...%s\n", colors.Dim, colors.Reset)
+			var delay string
+			if w.delayInMS > 0 {
+				delay = fmt.Sprintf(" with a %dms delay", w.delayInMS)
+			}
+			return fmt.Sprintf("%s[watch] build finished, watching for changes%s...%s\n", colors.Dim, delay, colors.Reset)
 		})
 	}
 
@@ -100,6 +105,11 @@ func (w *watcher) start() {
 
 			// Rebuild if we're dirty
 			if absPath := w.tryToFindDirtyPath(); absPath != "" {
+				// Optionally wait before rebuilding
+				if w.delayInMS > 0 {
+					time.Sleep(w.delayInMS * time.Millisecond)
+				}
+
 				if w.shouldLog {
 					logger.PrintTextWithColor(os.Stderr, w.useColor, func(colors logger.Colors) string {
 						prettyPath := resolver.PrettyPath(w.fs, logger.Path{Text: absPath, Namespace: "file"})
diff --git a/pkg/cli/cli_impl.go b/pkg/cli/cli_impl.go
@@ -51,6 +51,7 @@ const (
 
 type parseOptionsExtras struct {
 	watch       bool
+	watchDelay  int
 	metafile    *string
 	mangleCache *string
 }
@@ -127,6 +128,17 @@ func parseOptionsImpl(
 				extras.watch = value
 			}
 
+		case strings.HasPrefix(arg, "--watch-delay=") && buildOpts != nil:
+			value := arg[len("--watch-delay="):]
+			delay, err := strconv.Atoi(value)
+			if err != nil {
+				return parseOptionsExtras{}, cli_helpers.MakeErrorWithNote(
+					fmt.Sprintf("Invalid value %q in %q", value, arg),
+					"The watch delay must be an integer.",
+				)
+			}
+			extras.watchDelay = delay
+
 		case isBoolFlag(arg, "--minify"):
 			if value, err := parseBoolFlag(arg, true); err != nil {
 				return parseOptionsExtras{}, err
@@ -893,6 +905,7 @@ func parseOptionsImpl(
 				"tsconfig-raw":       true,
 				"tsconfig":           true,
 				"watch":              true,
+				"watch-delay":        true,
 			}
 
 			colon := map[string]bool{
@@ -1329,7 +1342,9 @@ func runImpl(osArgs []string, plugins []api.Plugin) int {
 				return 1
 			}
 
-			ctx.Watch(api.WatchOptions{})
+			ctx.Watch(api.WatchOptions{
+				Delay: extras.watchDelay,
+			})
 
 			// Do not exit if we're in watch mode
 			<-make(chan struct{})
diff --git a/scripts/js-api-tests.js b/scripts/js-api-tests.js
@@ -4230,6 +4230,57 @@ let watchTests = {
       await context.dispose()
     }
   },
+
+  async watchDelay({ esbuild, testDir }) {
+    const srcDir = path.join(testDir, 'src')
+    const outdir = path.join(testDir, 'out')
+    const input = path.join(srcDir, 'in.js')
+    const output = path.join(outdir, 'in.js')
+    await mkdirAsync(srcDir, { recursive: true })
+    await writeFileAsync(input, `throw 1`)
+
+    const { rebuildUntil, plugin } = makeRebuildUntilPlugin()
+    const context = await esbuild.context({
+      entryPoints: [input],
+      outdir,
+      format: 'esm',
+      logLevel: 'silent',
+      plugins: [plugin],
+    })
+
+    try {
+      const delay = 2000
+      const result = await rebuildUntil(
+        () => context.watch({ delay }),
+        () => true,
+      )
+      assert.strictEqual(result.errors.length, 0)
+      assert.strictEqual(await readFileAsync(output, 'utf8'), 'throw 1;\n')
+
+      // Edit a file
+      const startTime = Date.now()
+      const editPromise = rebuildUntil(
+        () => writeFileAtomic(input, `throw 2`),
+        () => fs.readFileSync(output, 'utf8') === 'throw 2;\n',
+      )
+
+      // Wait for half the delay time
+      await new Promise(resolve => setTimeout(resolve, delay / 2))
+
+      // The rebuild should not have happened yet (check synchronously)
+      if (Date.now() - startTime < delay) {
+        assert.strictEqual(fs.readFileSync(output, 'utf8'), 'throw 1;\n')
+      } else {
+        // To avoid a flaky test, don't check and assert if the CPU is busy and we missed our window
+      }
+
+      // Wait for the rebuild to happen
+      const result2 = await editPromise
+      assert.strictEqual(result2.errors.length, 0)
+    } finally {
+      await context.dispose()
+    }
+  },
 }
 
 let serveTests = {

Original file line number	Diff line number	Diff line change
`@@ -98,6 +98,7 @@ export interface CancelRequest {`
`98`	`98`	`export interface WatchRequest {`
`99`	`99`	`command: 'watch'`
`100`	`100`	`key: number`
	`101`	`+ delay?: number`
`101`	`102`	`}`
`102`	`103`
`103`	`104`	`export interface OnServeRequest {`
Original file line number	Diff line number	Diff line change
`@@ -513,7 +513,9 @@ export interface AnalyzeMetafileOptions {`
`513`	`513`	`verbose?: boolean`
`514`	`514`	`}`
`515`	`515`
	`516`	`+/** Documentation: https://esbuild.github.io/api/#watch-arguments */`
`516`	`517`	`export interface WatchOptions {`
	`518`	`+ delay?: number // In milliseconds`
`517`	`519`	`}`
`518`	`520`
`519`	`521`	`export interface BuildContext<ProvidedOptions extends BuildOptions = BuildOptions> {`
Original file line number	Diff line number	Diff line change
`@@ -501,7 +501,9 @@ type ServeResult struct {`
`501`	`501`	`Hosts []string`
`502`	`502`	`}`
`503`	`503`
	`504`	`+// Documentation: https://esbuild.github.io/api/#watch-arguments`
`504`	`505`	`type WatchOptions struct {`
	`506`	`+ Delay int // In milliseconds`
`505`	`507`	`}`
`506`	`508`
`507`	`509`	`type BuildContext interface {`
Original file line number	Diff line number	Diff line change
`@@ -1081,6 +1081,7 @@ func (ctx *internalContext) Watch(options WatchOptions) error {`
`1081`	`1081`	`rebuild: func() fs.WatchData {`
`1082`	`1082`	`return ctx.rebuild().watchData`
`1083`	`1083`	`},`
	`1084`	`+ delayInMS: time.Duration(options.Delay),`
`1084`	`1085`	`}`
`1085`	`1086`
`1086`	`1087`	`// All subsequent builds will be watch mode builds`