feat(watch): expose debounce related options

hyf0 · hyf0 · commit 461527b60ab5 · 2026-03-07T10:32:03.000Z
diff --git a/crates/rolldown_binding/src/options/binding_input_options/binding_watch_option.rs b/crates/rolldown_binding/src/options/binding_input_options/binding_watch_option.rs
@@ -17,6 +17,9 @@ pub struct BindingWatchOption {
   pub use_polling: Option<bool>,
   pub poll_interval: Option<u32>,
   pub compare_contents_for_polling: Option<bool>,
+  pub use_debounce: Option<bool>,
+  pub debounce_delay: Option<u32>,
+  pub debounce_tick_rate: Option<u32>,
   #[napi(ts_type = "((id: string) => void) | undefined")]
   #[debug(skip)]
   pub on_invalidate: Option<JsCallback<FnArgs<(String,)>>>,
@@ -32,6 +35,9 @@ impl From<BindingWatchOption> for rolldown_common::WatchOption {
       use_polling: value.use_polling.unwrap_or_default(),
       poll_interval: value.poll_interval.map(u64::from),
       compare_contents_for_polling: value.compare_contents_for_polling.unwrap_or_default(),
+      use_debounce: value.use_debounce.unwrap_or_default(),
+      debounce_delay: value.debounce_delay.map(u64::from),
+      debounce_tick_rate: value.debounce_tick_rate.map(u64::from),
       on_invalidate: value.on_invalidate.map(|js_callback| {
         OnInvalidate::new(Arc::new(move |path| {
           let f = Arc::clone(&js_callback);
diff --git a/crates/rolldown_binding/src/watcher.rs b/crates/rolldown_binding/src/watcher.rs
@@ -66,33 +66,16 @@ impl BindingWatcher {
       .map(create_bundler_config_from_binding_options)
       .collect::<Result<Vec<_>, _>>()?;
 
-    // Forward the largest build_delay from configs to the watcher's debounce.
-    let build_delay =
-      configs.iter().filter_map(|c| c.options.watch.as_ref().and_then(|w| w.build_delay)).max();
-
-    // Extract use_polling / poll_interval / compare_contents_for_polling from the first config that specifies them.
-    let use_polling = configs
-      .iter()
-      .find_map(|c| c.options.watch.as_ref().filter(|w| w.use_polling).map(|w| w.use_polling))
-      .unwrap_or(false);
-    let poll_interval =
-      configs.iter().find_map(|c| c.options.watch.as_ref().and_then(|w| w.poll_interval));
-    let compare_contents_for_polling = configs
-      .iter()
-      .find_map(|c| {
-        c.options
-          .watch
-          .as_ref()
-          .filter(|w| w.compare_contents_for_polling)
-          .map(|w| w.compare_contents_for_polling)
-      })
-      .unwrap_or(false);
-
+    // Extract watcher config from the first config's watch options.
+    let watch = configs.first().and_then(|c| c.options.watch.as_ref());
     let watcher_config = WatcherConfig {
-      debounce: build_delay.map(|ms| Duration::from_millis(u64::from(ms))),
-      use_polling,
-      poll_interval,
-      compare_contents_for_polling,
+      debounce: watch.and_then(|w| w.build_delay).map(|ms| Duration::from_millis(u64::from(ms))),
+      use_polling: watch.is_some_and(|w| w.use_polling),
+      poll_interval: watch.and_then(|w| w.poll_interval),
+      compare_contents_for_polling: watch.is_some_and(|w| w.compare_contents_for_polling),
+      use_debounce: watch.is_some_and(|w| w.use_debounce),
+      debounce_delay: watch.and_then(|w| w.debounce_delay),
+      debounce_tick_rate: watch.and_then(|w| w.debounce_tick_rate),
     };
 
     let handler = NapiWatcherEventHandler { listener: Arc::new(listener) };
diff --git a/crates/rolldown_common/src/inner_bundler_options/types/watch_option.rs b/crates/rolldown_common/src/inner_bundler_options/types/watch_option.rs
@@ -14,12 +14,16 @@ use serde::{Deserialize, Deserializer};
   derive(Deserialize, JsonSchema),
   serde(rename_all = "camelCase", deny_unknown_fields)
 )]
+#[expect(clippy::struct_excessive_bools)]
 pub struct WatchOption {
   pub skip_write: bool,
   pub build_delay: Option<u32>,
   pub use_polling: bool,
   pub poll_interval: Option<u64>,
   pub compare_contents_for_polling: bool,
+  pub use_debounce: bool,
+  pub debounce_delay: Option<u64>,
+  pub debounce_tick_rate: Option<u64>,
   #[cfg_attr(
     feature = "deserialize_bundler_options",
     serde(default, deserialize_with = "deserialize_string_or_regex"),
diff --git a/crates/rolldown_testing/_config.schema.json b/crates/rolldown_testing/_config.schema.json
@@ -1458,6 +1458,25 @@
         "compareContentsForPolling": {
           "type": "boolean"
         },
+        "useDebounce": {
+          "type": "boolean"
+        },
+        "debounceDelay": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0
+        },
+        "debounceTickRate": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0
+        },
         "include": {
           "type": [
             "array",
@@ -1481,7 +1500,8 @@
       "required": [
         "skipWrite",
         "usePolling",
-        "compareContentsForPolling"
+        "compareContentsForPolling",
+        "useDebounce"
       ]
     },
     "LegalComments": {
diff --git a/crates/rolldown_watcher/src/watcher.rs b/crates/rolldown_watcher/src/watcher.rs
@@ -31,6 +31,12 @@ pub struct WatcherConfig {
   pub poll_interval: Option<u64>,
   /// Whether to compare file contents for poll-based watchers (only used when `use_polling` is true)
   pub compare_contents_for_polling: bool,
+  /// Whether to use debounced event delivery at the filesystem level
+  pub use_debounce: bool,
+  /// Debounce delay in milliseconds for fs-level debounced watchers (only used when `use_debounce` is true)
+  pub debounce_delay: Option<u64>,
+  /// Tick rate in milliseconds for the debouncer's internal polling (only used when `use_debounce` is true)
+  pub debounce_tick_rate: Option<u64>,
 }
 
 impl WatcherConfig {
@@ -45,8 +51,11 @@ impl WatcherConfig {
     }
     config.compare_contents_for_polling = self.compare_contents_for_polling;
     config.use_polling = self.use_polling;
-    // rolldown_watcher doesn't support debounce currently
-    config.use_debounce = false;
+    config.use_debounce = self.use_debounce;
+    if let Some(debounce_delay) = self.debounce_delay {
+      config.debounce_delay = debounce_delay;
+    }
+    config.debounce_tick_rate = self.debounce_tick_rate;
     config
   }
 }
diff --git a/packages/rolldown/src/binding.d.cts b/packages/rolldown/src/binding.d.cts
@@ -2780,6 +2780,9 @@ export interface BindingWatchOption {
   usePolling?: boolean
   pollInterval?: number
   compareContentsForPolling?: boolean
+  useDebounce?: boolean
+  debounceDelay?: number
+  debounceTickRate?: number
   onInvalidate?: ((id: string) => void) | undefined
 }
 
diff --git a/packages/rolldown/src/options/input-options.ts b/packages/rolldown/src/options/input-options.ts
@@ -81,6 +81,24 @@ export interface WatcherFileWatcherOptions {
    * @default false
    */
   compareContentsForPolling?: boolean;
+  /**
+   * Whether to use debounced event delivery at the filesystem level.
+   * This coalesces rapid filesystem events before they reach the build coordinator.
+   * @default false
+   */
+  useDebounce?: boolean;
+  /**
+   * Debounce delay in milliseconds for fs-level debounced watchers.
+   * Only used when {@linkcode useDebounce} is `true`.
+   * @default 10
+   */
+  debounceDelay?: number;
+  /**
+   * Tick rate in milliseconds for the debouncer's internal polling.
+   * Only used when {@linkcode useDebounce} is `true`.
+   * When undefined, auto-selects 1/4 of debounceDelay.
+   */
+  debounceTickRate?: number;
 }
 
 export interface WatcherOptions {
diff --git a/packages/rolldown/src/utils/bindingify-input-options.ts b/packages/rolldown/src/utils/bindingify-input-options.ts
@@ -309,6 +309,9 @@ function bindingifyWatch(watch: InputOptions['watch']): BindingInputOptions['wat
       usePolling: watcher.usePolling,
       pollInterval: watcher.pollInterval,
       compareContentsForPolling: watcher.compareContentsForPolling,
+      useDebounce: watcher.useDebounce,
+      debounceDelay: watcher.debounceDelay,
+      debounceTickRate: watcher.debounceTickRate,
       include: normalizedStringOrRegex(watch.include),
       exclude: normalizedStringOrRegex(watch.exclude),
       onInvalidate: (...args) => watch.onInvalidate?.(...args),
diff --git a/packages/rolldown/src/utils/validator.ts b/packages/rolldown/src/utils/validator.ts
@@ -274,6 +274,18 @@ const WatcherFileWatcherOptionsSchema = v.strictObject({
       'Compare file contents for poll-based watchers (only used when usePolling is true)',
     ),
   ),
+  useDebounce: v.pipe(
+    v.optional(v.boolean()),
+    v.description('Use debounced event delivery at the filesystem level'),
+  ),
+  debounceDelay: v.pipe(
+    v.optional(v.number()),
+    v.description('Debounce delay in milliseconds (only used when useDebounce is true)'),
+  ),
+  debounceTickRate: v.pipe(
+    v.optional(v.number()),
+    v.description('Tick rate in milliseconds for debouncer (only used when useDebounce is true)'),
+  ),
 });
 
 const WatcherOptionsSchema = v.strictObject({

Original file line number	Diff line number	Diff line change
`@@ -2780,6 +2780,9 @@ export interface BindingWatchOption {`
`2780`	`2780`	`usePolling?: boolean`
`2781`	`2781`	`pollInterval?: number`
`2782`	`2782`	`compareContentsForPolling?: boolean`
	`2783`	`+ useDebounce?: boolean`
	`2784`	`+ debounceDelay?: number`
	`2785`	`+ debounceTickRate?: number`
`2783`	`2786`	`onInvalidate?: ((id: string) => void) \| undefined`
`2784`	`2787`	`}`
`2785`	`2788`