braid

Run every process your project needs as one stack. Describe your API, web app and workers in one config file; braid starts them in the right order, restarts them when files change, handles crashes, and keeps their logs.

Documentation · Changelog · GitHub

Requires Node 22.18 or later, on macOS or Linux.

Install

npm install --save-dev @aip-tech/braid

Configure

Create braid.config.ts next to your package.json:

import { defineConfig } from "@aip-tech/braid";

export default defineConfig({
	processes: [
		{
			name: "api",
			command: "pnpm",
			args: ["--filter", "./api", "dev"],
			watch: ["api/src"],
			readyPattern: "^Server listening",
		},
		{
			name: "web",
			command: "pnpm",
			args: ["--filter", "./web", "dev"],
			startAfter: { processes: ["api"] },
		},
	],
});

In a project whose package.json isn't "type": "module" (npm init sets "commonjs"), name the file braid.config.mts instead; braid finds either.

Here api restarts when a file under api/src changes, and web waits for api to print its ready line before starting. See the configuration guide and the full list of options.

Run

npx braid start            # start the stack in the background
npx braid status           # state, CPU and memory for each process
npx braid logs --follow    # every process's output, live
npx braid restart api      # restart one process
npx braid stop             # stop everything

Add --foreground to start to stay attached to the terminal instead. Every command and flag is in the CLI reference.

Features

• Restarts on file changes, with extension filters and excludes.
• Dependencies between processes: wait for readiness on first start, restart dependents when a process restarts, and run commands such as codegen in between.
• Crash handling: a crash stops the whole stack by default, or restarts just that process with backoff.
• Persistent logs: a rotated log file per process, readable with braid logs.
• Real resource usage: CPU and memory for each app's whole process tree.
• Plugins: add routes, pages and event listeners to the stack's local control server. The web dashboard is one.

License

MIT