Reference
Config options
Every option, with its type and default. For how they fit together, see the configuration guide.
Top-level options
Set on the object braid.config.ts default-exports.
processes
Required. The processes to run, described below. A config can also default-export this array on its own.
plugins
Plugins to load, by package name or path, each optionally with an options object. Resolved from the config file's directory. Options must be plain data. See Plugins.
logs.dir
Where per-process log files go, relative to the directory braid runs in.
logs.maxSizeBytes
Size at which a process's log rotates. One backup is kept.
logs.timestamps
Prefix every output line with HH:MM:SS.mmm, in log files, the terminal and the dashboard alike.
foreground
Run braid start attached to the terminal instead of as a background daemon. Overridden by --foreground and --daemon.
statsPollIntervalMs
How often each process's CPU and memory are sampled.
startupTimeoutMs
How long braid start waits for the daemon to come up before giving up and stopping it. Raise it for a slow plugin or a cold TypeScript compile.
Process options
Set on each entry in processes.
name
Required and unique. Used in log prefixes, as the log file name and by every command that targets a process. Can't contain /, \ or control characters, and can't be ., .. or *.
command
Required. The executable to run, such as pnpm or node.
args
Arguments passed to command.
cwd
Working directory, relative to the directory braid runs in.
env
Extra environment variables for this process only, merged over braid's own environment.
color
Color of the process's [name] prefix: black, red, green, yellow, blue, magenta, cyan, white or gray.
url
An address to show in the startup summary and braid status. Informational only.
watch
Paths to watch. A matching change restarts the process. See Restarting on file changes.
ext
Comma-separated extensions that count as a change. Only used with watch.
exclude
Paths (or globs) to leave out of watch, each with everything under it.
readyPattern
A regex. The process counts as ready once a line of its output matches, tested against the line exactly as the app printed it. Gates startAfter, onRestart and dependsOn.
readyTimeoutMs
How long to wait for readyPattern before carrying on anyway.
startAfter
Hold this process's first start until every named process is ready. Later restarts aren't affected.
dependsOn
Restart this process whenever one of the named processes restarts, once that process is ready. run executes after this process stops and before it starts again.
onRestart
A command to run after this process restarts and is ready. Dependents restart only once it succeeds.
beforeRestart
A command to run after a watch-triggered stop and before the fresh start, such as regenerating code the new process needs. Requires watch. If it keeps failing, the process stays stopped until the next change.
autoStart
Set false to leave the process out of braid start; start it with braid start <name>. Can't be combined with dependsOn, or be another process's startAfter target.
autoRestart
Restart the process when it crashes, instead of stopping the whole stack.
maxRestarts
Crashes in a row before autoRestart gives up and stops the stack.
restartDelayMs
First autoRestart delay, doubling on each crash in a row, up to 10 seconds.
minUptimeMs
How long a restarted process must stay up for its crash count to reset.
stopTimeoutMs
How long to wait after SIGTERM before sending SIGKILL.
RestartHook
The shape of dependsOn.run, onRestart and beforeRestart. A hook that exits non-zero is retried.
command
Required. The executable to run.
args
Arguments passed to command.
cwd
Working directory. For beforeRestart it's relative to the process's own cwd; for the other hooks, to the directory braid runs in.
retries
Extra attempts after a non-zero exit.
retryDelayMs
Delay between attempts.