feat(core): add server:watch script with automatic restart on file changes (#3920)

## Description

This PR adds a new `server:watch` script that runs MagicMirror² in
server-only mode with automatic restart and browser reload capabilities.

Particularly helpful for:
- **Developers** who need to see changes immediately without manual
restarts.
- **Users setting up their mirror** who make many changes to `config.js`
or `custom.css` and need quick feedback.

### What it does

When you run `npm run server:watch`, the watcher monitors files you
specify in `config.watchTargets`. Whenever a monitored file changes:

1. The server automatically restarts
2. Waits for the port to become available
3. Sends a reload notification to all connected browsers via Socket.io
4. Browsers automatically refresh to show the changes

This creates a seamless development experience where you can edit code,
save, and see the results within seconds.

### Implementation highlights

**Zero dependencies:** Uses only Node.js built-ins (`fs.watch`,
`child_process.spawn`, `net`, `http`) - no nodemon or external watchers
needed.

**Smart file watching:** Monitors parent directories instead of files
directly to handle atomic writes from modern editors (VSCode, etc.) that
create temporary files during save operations.

**Port management:** Waits for the old server instance to fully release
the port before starting a new one, preventing "port already in use"
errors.

### Configuration

Users explicitly define which files to monitor in their `config.js`:

```js
let config = {
  watchTargets: [
    "config/config.js",
    "css/custom.css",
    "modules/MMM-MyModule/MMM-MyModule.js",
    "modules/MMM-MyModule/node_helper.js"
  ],
  // ... rest of config
};
```

This explicit approach keeps the implementation simple (~260 lines)
while giving users full control over what triggers restarts. If
`watchTargets` is empty or undefined, the watcher starts but monitors
nothing, logging a clear warning message.

---

**Note:** This PR description has been updated to reflect the final
implementation. During the review process, we refined the approach
multiple times based on feedback.

---------

Co-authored-by: Jboucly <contact@jboucly.fr>
Co-authored-by: Kristjan ESPERANTO <35647502+KristjanESPERANTO@users.noreply.github.com>
This commit is contained in:
Jboucly
2025-10-28 19:14:51 +01:00
committed by GitHub
parent 2e795f6552
commit 961b3c96d6
7 changed files with 304 additions and 4 deletions

View File

@@ -15,7 +15,7 @@ const Utils = require(`${__dirname}/utils`);
const defaultModules = require(`${global.root_path}/modules/default/defaultmodules`);
// used to control fetch timeout for node_helpers
const { setGlobalDispatcher, Agent } = require("undici");
const { getEnvVarsAsObj } = require("#server_functions");
const { getEnvVarsAsObj, getConfigFilePath } = require("#server_functions");
// common timeout value, provide environment override in case
const fetch_timeout = process.env.mmFetchTimeout !== undefined ? process.env.mmFetchTimeout : 30000;
@@ -72,7 +72,7 @@ function App () {
// For this check proposed to TestSuite
// https://forum.magicmirror.builders/topic/1456/test-suite-for-magicmirror/8
const configFilename = path.resolve(global.configuration_file || `${global.root_path}/config/config.js`);
const configFilename = getConfigFilePath();
let templateFile = `${configFilename}.template`;
// check if templateFile exists