devwatch

A professional file watcher and auto-runner for Node.js development.
A full-featured, configurable alternative to nodemon — with lifecycle hooks, env management, crash-loop protection, and desktop notifications.

Install

# Global (recommended for CLI use)
npm install -g devwatch

# Local to a project
npm install --save-dev devwatch

Quick start

devwatch server.js
devwatch src/index.js --env dev --delay 300

Configuration

Scaffold a config file:

devwatch --init

This creates devwatch.config.js in your current directory.
You can also add a "devwatch" key to your package.json.

Full devwatch.config.js reference

module.exports = {
  // Entry point (can also be the first CLI argument)
  entry: "src/index.js",

  // Runtime: "node" | "bun" | "ts-node" | "esm"
  runtime: "node",
  runtimeArgs: [], // flags before your file, e.g. ["--inspect"]
  scriptArgs: [], // flags after  your file, e.g. ["--port","3000"]

  // Environment
  env: "default", // devwatch --env dev  switches to .env.development
  envFiles: {
    default: ".env",
    dev: ".env.development",
    prod: ".env.production",
    test: ".env.test",
  },

  // Watch settings
  watch: {
    paths: ["src", "config"], // extra dirs/files to watch
    ignore: ["node_modules", ".git", "dist", "*.log"],
    extensions: [".js", ".ts", ".json"],
  },

  // Runner behaviour
  runner: {
    debounce: 250, // ms to wait after last change
    clearConsole: true, // clear terminal on restart
    gracefulShutdown: true, // SIGTERM → wait → SIGKILL
    killTimeout: 3000,
    restartOnError: false, // restart even on non-zero exit
    maxRestarts: 0, // crash-loop guard (0 = unlimited)
    restartWindowMs: 10000,
  },

  // Lifecycle hooks: shell string OR async function(ctx)
  // ctx = { file, env, config, changedFile?, exitCode? }
  hooks: {
    beforeStart: "npm run build",
    beforeRestart: "npm run lint --silent",
    afterRestart: async ({ changedFile }) =>
      console.log("changed:", changedFile),
    onCrash: async ({ exitCode }) => console.error("crashed:", exitCode),
  },

  // Desktop notifications (optional: npm install node-notifier)
  notify: {
    enabled: true,
    onRestart: true,
    onCrash: true,
  },

  // Logging
  log: {
    level: "info", // silent | error | warn | info | debug
    timestamps: true,
    colors: true,
    prefix: "devwatch",
    file: "devwatch.log", // also write to file
  },
};

CLI options

| Flag | Alias | Description | | ----------------- | ----- | ----------------------------------- | | --config <path> | -c | Path to config file | | --env <name> | -e | Environment (default/dev/prod/test) | | --delay <ms> | -d | Debounce delay in ms | | --quiet | -q | Suppress all output | | --no-clear | | Don't clear console on restart | | --init | | Scaffold devwatch.config.js | | --version | -v | Print version | | --help | -h | Show help |

Runtimes

| Value | Requires | | --------- | ---------------------------------------- | | node | Node.js (default) | | bun | Bun installed | | ts-node | npm i -g ts-node | | esm | Node.js with --experimental-vm-modules |

Features

• chokidar watching — reliable, cross-platform, recursive
• Debounce — ignores rapid save storms
• Graceful shutdown — SIGTERM → wait → SIGKILL
• Crash-loop guard — stops after N restarts in a window
• Lifecycle hooks — shell commands or async functions
• Env management — per-environment .env files via dotenv
• Multiple runtimes — node / bun / ts-node / esm
• Desktop notifications — via optional node-notifier
• Structured logging — levels, colours, timestamps, log file
• Zero-config — works with just devwatch server.js

License

MIT