Documentation

stye watches files or folders and re-runs a command when something changes. v1.2.0 · Node.js 18+.

Installation

npm i -g @oxaccolades/stye

# or from source
git clone https://github.com/Accoladesio/stye
cd stye && npm install && npm link

Usage

stye [options] <path> <command...>
stye [options] -w <path> [-w <path>...] <command...>
stye [options] -- <command...>   # paths come from config

Options go before the path or command. Quote the command if it contains shell characters like && or |.

stye ./src "npm run build"
stye -w src -w tests -e ts,tsx --mode queue npm test
stye --ignore "*.{log,tmp}" . node server.js
stye --verbose --timestamps ./src "npm run build"

Options

Watching

Option	Description
`-w, --watch <path>`	File or folder to watch. Repeat for several.
`-e, --ext <list>`	Only react to these extensions, e.g. `ts,js`.
`--include <glob>`	Only react to matching paths (repeatable).
`--ignore <glob>`	Never react to matching paths (repeatable).
`--no-default-ignore`	Also watch node_modules, .git, dist and editor temp files.
`--fallback`	Use the built-in directory walker instead of native recursive watching.

Running

Option	Description
`-d, --debounce <ms>`	Quiet period after the last change before running (default 300).
`-m, --mode <mode>`	`restart` (default), `queue` or `concurrent`.
`--kill-timeout <ms>`	Wait after SIGTERM before SIGKILL (default 3000).

Output and other

Option	Description
`-q, --quiet / --verbose`	Only errors and failed runs / extra diagnostics.
`--timestamps`	Prefix log lines with the time.
`--no-color`	Disable colours (NO_COLOR is honoured too).
`--no-keys`	Disable the interactive shortcuts.
`-c, --config <file>`	Read settings from a JSON file.
`-h, --help / -v, --version`	Help / version.

Run modes

restart — a new change stops the previous run and everything it spawned, then starts fresh.
queue — a running command is left alone; changes meanwhile trigger exactly one more run afterwards.
concurrent — every change starts a new run immediately.

Patterns

Globs support *, **, ?, [abc], [!abc] and {a,b}.

Without a / the pattern matches any path segment: node_modules, *.log.
With a / it is anchored to the watched folder: src/generated, src/**/*.tmp.
--ignore wins over --include and --ext. An explicitly named file is always watched.

Keys

In interactive terminals: r rerun now · c clear screen · q or Ctrl+C quit.

Config file

Use stye.config.json, a "stye" key in package.json, or --config <file>, then just run stye.

{
  "watch": ["src", "tests"],
  "command": "npm test",
  "ext": ["ts"],
  "ignore": ["src/generated", "*.snap"],
  "debounce": 200,
  "mode": "queue"
}

Keys: watch, command, include, ext, ignore, defaultIgnore, debounce, mode, killTimeout, quiet, verbose, timestamps, color, keys, fallback. CLI flags override the config per key (lists are replaced). With config-supplied paths, pass the command after --: stye -- npm run lint.

Behaviour

Recursive watching with a fallback walker for Node 18 on Linux.
Debounced runs: a burst of saves triggers one run.
SIGTERM then SIGKILL across the whole process tree.
Live stdout/stderr; each run ends with exit code and duration.
Friendly one-line errors; clean shutdown on Ctrl+C or SIGTERM.