watch: add --watch-kill-signal flag

dario-piotrowicz · aduh95 · commit 4dc6b4c67aaa · 2025-07-24T20:08:29.000+02:00
add the new `--watch-kill-signal` to allow users to customize what signal is sent to the process on restarts during watch mode PR-URL: #58719 Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -3080,6 +3080,19 @@ mode. If no file is provided, Node.js will exit with status code `9`.
 node --watch index.js
 ```
 
+### `--watch-kill-signal`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+Customizes the signal sent to the process on watch mode restarts.
+
+```bash
+node --watch --watch-kill-signal SIGINT test.js
+```
+
 ### `--watch-path`
 
 <!-- YAML
@@ -3422,6 +3435,7 @@ one is included in the list below.
 * `--use-openssl-ca`
 * `--use-system-ca`
 * `--v8-pool-size`
+* `--watch-kill-signal`
 * `--watch-path`
 * `--watch-preserve-output`
 * `--watch`
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
@@ -568,6 +568,9 @@
         "watch": {
           "type": "boolean"
         },
+        "watch-kill-signal": {
+          "type": "string"
+        },
         "watch-path": {
           "oneOf": [
             {
diff --git a/lib/internal/main/watch_mode.js b/lib/internal/main/watch_mode.js
@@ -20,6 +20,7 @@ const {
 const { getOptionValue } = require('internal/options');
 const { FilesWatcher } = require('internal/watch_mode/files_watcher');
 const { green, blue, red, white, clear } = require('internal/util/colors');
+const { convertToValidSignal } = require('internal/util');
 
 const { spawn } = require('child_process');
 const { inspect } = require('util');
@@ -30,8 +31,7 @@ const { once } = require('events');
 prepareMainThreadExecution(false, false);
 markBootstrapComplete();
 
-// TODO(MoLow): Make kill signal configurable
-const kKillSignal = 'SIGTERM';
+const kKillSignal = convertToValidSignal(getOptionValue('--watch-kill-signal'));
 const kShouldFilterModules = getOptionValue('--watch-path').length === 0;
 const kEnvFile = getOptionValue('--env-file') || getOptionValue('--env-file-if-exists');
 const kWatchedPaths = ArrayPrototypeMap(getOptionValue('--watch-path'), (path) => resolve(path));
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -862,6 +862,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "path to watch",
             &EnvironmentOptions::watch_mode_paths,
             kAllowedInEnvvar);
+  AddOption("--watch-kill-signal",
+            "kill signal to send to the process on watch mode restarts"
+            "(default: SIGTERM)",
+            &EnvironmentOptions::watch_mode_kill_signal,
+            kAllowedInEnvvar);
   AddOption("--watch-preserve-output",
             "preserve outputs on watch mode restart",
             &EnvironmentOptions::watch_mode_preserve_output,
diff --git a/src/node_options.h b/src/node_options.h
@@ -229,6 +229,7 @@ class EnvironmentOptions : public Options {
   bool watch_mode = false;
   bool watch_mode_report_to_parent = false;
   bool watch_mode_preserve_output = false;
+  std::string watch_mode_kill_signal = "SIGTERM";
   std::vector<std::string> watch_mode_paths;
 
   bool syntax_check_only = false;
diff --git a/test/parallel/test-runner-watch-mode-kill-signal.mjs b/test/parallel/test-runner-watch-mode-kill-signal.mjs
@@ -0,0 +1,122 @@
+import * as common from '../common/index.mjs';
+import { describe, it, beforeEach } from 'node:test';
+import { once } from 'node:events';
+import assert from 'node:assert';
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import tmpdir from '../common/tmpdir.js';
+
+if (common.isWindows) {
+  common.skip('no signals on Windows');
+}
+
+if (common.isIBMi) {
+  common.skip('IBMi does not support `fs.watch()`');
+}
+
+if (common.isAIX) {
+  common.skip('folder watch capability is limited in AIX.');
+}
+
+const indexContents = `
+  const { setTimeout } = require("timers/promises");
+  (async () => {
+      // Wait a few milliseconds to make sure that the
+      // parent process has time to attach its listeners
+      await setTimeout(200);
+
+      process.on('SIGTERM', () => {
+          console.log('__SIGTERM received__');
+          process.exit(123);
+      });
+
+      process.on('SIGINT', () => {
+          console.log('__SIGINT received__');
+          process.exit(124);
+      });
+
+      console.log('ready!');
+
+      // Wait for a long time (just to keep the process alive)
+      await setTimeout(100_000_000);
+  })();
+`;
+
+let indexPath = '';
+
+function refresh() {
+  tmpdir.refresh();
+  indexPath = tmpdir.resolve('index.js');
+  writeFileSync(indexPath, indexContents);
+}
+
+describe('test runner watch mode with --watch-kill-signal', () => {
+  beforeEach(refresh);
+
+  it('defaults to SIGTERM', async () => {
+    let currentRun = Promise.withResolvers();
+    const child = spawn(process.execPath, ['--watch', indexPath], {
+      cwd: tmpdir.path,
+    });
+
+    let stdout = '';
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      currentRun.resolve();
+    });
+
+    await currentRun.promise;
+
+    currentRun = Promise.withResolvers();
+    writeFileSync(indexPath, indexContents);
+
+    await currentRun.promise;
+    child.kill();
+    const [exitCode] = await once(child, 'exit');
+    assert.match(stdout, /__SIGTERM received__/);
+    assert.strictEqual(exitCode, 123);
+  });
+
+  it('can be overridden (to SIGINT)', async () => {
+    let currentRun = Promise.withResolvers();
+    const child = spawn(process.execPath, ['--watch', '--watch-kill-signal', 'SIGINT', indexPath], {
+      cwd: tmpdir.path,
+    });
+    let stdout = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      if (stdout.includes('ready!')) {
+        currentRun.resolve();
+      }
+    });
+
+    await currentRun.promise;
+
+    currentRun = Promise.withResolvers();
+    writeFileSync(indexPath, indexContents);
+
+    await currentRun.promise;
+    child.kill();
+    const [exitCode] = await once(child, 'exit');
+    assert.match(stdout, /__SIGINT received__/);
+    assert.strictEqual(exitCode, 124);
+  });
+
+  it('errors if an invalid signal is provided', async () => {
+    const currentRun = Promise.withResolvers();
+    const child = spawn(process.execPath, ['--watch', '--watch-kill-signal', 'invalid_signal', indexPath], {
+      cwd: tmpdir.path,
+    });
+    let stdout = '';
+
+    child.stderr.on('data', (data) => {
+      stdout += data.toString();
+      currentRun.resolve();
+    });
+
+    await currentRun.promise;
+
+    assert.match(stdout, new RegExp(/TypeError \[ERR_UNKNOWN_SIGNAL\]: Unknown signal: invalid_signal/));
+  });
+});
