Watchers
Configure runtime directory and file watchers
BoxLang includes a built-in WatcherService for monitoring directories and reacting to filesystem events. Watchers can be configured globally in boxlang.json and/or managed dynamically at runtime.
Use this when you want to:
trigger hot-reload flows
rebuild assets after file changes
run custom automation from filesystem events
Configuration Structure
The watcher configuration lives in the watcher segment of your boxlang.json file:
{
"watcher": {
"recursive": true,
"debounce": 0,
"throttle": 0,
"atomicWrites": true,
"delay": 0,
"errorThreshold": 10,
"definitions": {}
}
}Configuration Properties
recursive
Type: boolean Default: true
Whether watchers recurse into subdirectories.
debounce
Type: long (milliseconds) Default: 0
Debounce window in milliseconds. When set above 0, events are held until no new events arrive during the window.
throttle
Type: long (milliseconds) Default: 0
Throttle window in milliseconds. When set above 0, only one event is emitted per window and additional events are dropped.
atomicWrites
Type: boolean Default: true
When enabled, noisy intermediate events from atomic save patterns (temp file + rename) are reduced.
delay
Type: long (milliseconds) Default: 0
Startup delay before watchers begin processing events.
errorThreshold
Type: integer Default: 10
Number of consecutive listener errors before a watcher auto-stops. Set to 0 to disable this auto-shutdown behavior.
definitions
Type: object Default: {}
Map of named watcher definitions that are auto-registered and started at runtime startup.
Each entry supports:
paths
string or array
Yes
Directory path or list of directories to watch
listener
string
Yes
BoxLang class path implementing listener behavior
recursive
boolean
No
Per-watcher override for recursion
debounce
long
No
Per-watcher debounce override
throttle
long
No
Per-watcher throttle override
atomicWrites
boolean
No
Per-watcher atomic write filtering override
delay
long
No
Per-watcher startup delay override
errorThreshold
integer
No
Per-watcher error threshold override
Inside boxlang.json, the listener must be a class name string. If you want to use closures or struct listeners, create watchers programmatically with watcherNew().
Definition Example
Runtime Management
You can also create and manage watchers dynamically with BIFs:
watcherNew()watcherStart()watcherStop()watcherRestart()watcherList()watcherGet()watcherGetAll()watcherExists()watcherShutdown()watcherStopAll()watcherShutdownAll()
For full usage examples, see Directory + File Watchers.
Related Configuration
Last updated
Was this helpful?