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

jboucly · 2025-10-19T17:40:48Z

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:

The server automatically restarts
Waits for the port to become available
Sends a reload notification to all connected browsers via Socket.io
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:

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.

sdetweil · 2025-10-19T18:13:54Z

You can reload the browser side anytime, ctl-r, or f5

it only loads the web side. You have to stop server and start to reload node_helpers

sdetweil · 2025-10-19T18:16:07Z

What does server dev do? dev was only for web side

if you open your own browser it doesn’t get that parm

sdetweil · 2025-10-19T18:22:45Z

The scripted installer handles node install plus other things

jboucly · 2025-10-19T19:22:51Z

Yes, but stopping the server and then restarting it quickly becomes redundant when we make a lot of modifications and tests on the module side in development....

jboucly · 2025-10-19T19:24:27Z

You can reload the browser side anytime, ctl-r, or f5

it only loads the web side. You have to stop server and start to reload node_helpers

Yes, but stopping the server and then restarting it quickly becomes redundant when we make a lot of modifications and tests on the module side in development....

What does server dev do? dev was only for web side

if you open your own browser it doesn’t get that parm

I don't understand

sdetweil · 2025-10-19T19:28:21Z

So again, change module, ctrl-r if cursor is over web side, f5 if over dev window side

what does server:dev do?
The dev parm is only used when electron is the browser in full mode, npm run start:dev

in run server mode
You have to start your own browser. Chrome/firefox/surf/safari pointing at the MagicMirror address and port

dev mode curl-shift-I , toggles the dev window open or closed

.nvmrc

package.json

KristjanESPERANTO · 2025-10-19T20:27:28Z

what does server:dev do?

To start MagicMirror in server mode + Nodemon keeps an eye on server-side files, and whenever a change is detected the server restarts automatically.

sdetweil · 2025-10-19T20:29:25Z

Ah

KristjanESPERANTO · 2025-10-21T22:48:32Z

Thanks for the changes 🙂 I would like to test something relevant. Give me some time for the review.

…r configuration

….nvmrc entry

…g and port management - Add port availability checks before restart to prevent race conditions - Add error handler for spawn failures - Extract hardcoded values to constants (RESTART_DELAY_MS, PORT_CHECK_*) - Add getConfigFilePath() helper for cleaner config path resolution - Watch js/ and serveronly/ directories in addition to modules/ and config/ - Watch all JS files (.js, .mjs, .cjs) instead of just node_helper.js - Improve restart mechanism with isRestarting flag - Better error messages for watcher and spawn failures - Remove unused app.restart() method from app.js These changes make the watcher more robust and easier to maintain.

KristjanESPERANTO · 2025-10-22T13:03:37Z

I have re-based the branch.

During my tests, I encountered various issues. For example, the restart was triggered by files that my editor created temporarily when saving. Furthermore, the restart did not wait until the old instance released the port, so the new instance could not use it. I have adjusted this and other details in one commit.

Please feel free to give feedback on my changes.

From my point of view, everything looks good now 😃 However, I would wait for the opinion of at least one other contributor on the current status.

Edit: I removed the manual restart option since it would be another feature. One feature per PR is easier to handle.

jboucly · 2025-10-22T13:48:16Z

I have re-based the branch.

During my tests, I encountered various issues. For example, the restart was triggered by files that my editor created temporarily when saving. Furthermore, the restart did not wait until the old instance released the port, so the new instance could not use it. I have adjusted this and other details in one commit.

Please feel free to give feedback on my changes.

From my point of view, everything looks good now 😃 However, I would wait for the opinion of at least one other contributor on the current status.

Edit: I removed the manual restart option since it would be another feature. One feature per PR is easier to handle.

Nice jobs ! Thanks for the changes ! I see that I don't have the whole history of the project when I see all the changes you made 🫣

Ok for the removal of manual reload and sorry for my english in changelog file x')

But i don't understand why on your local you have this bug with my version of watcher 🤔

Edit: I change the description of the PR

serveronly/watcher.js

- allow `config.watchTargets` to opt into additional files while falling back to the active config and custom CSS - expose `/reload` in server.js that emits `RELOAD` so connected clients refresh automatically The watcher runs outside server.js and previously had no socket.io access, so browser reloads were impossible; the new endpoint bridges that gap.

serveronly/watcher.js

- Use existing getConfigFilePath() in getServerPort() - Remove hardcoded 127.0.0.1 from isPortAvailable() for container compatibility

- Move getConfigFilePath() to server_functions.js - Use in app.js and watcher.js to avoid duplication

…ibility

serveronly/watcher.js

khassel · 2025-10-27T21:48:01Z

From my side this can be merged. Will wait until tomorrow to give others a chance to comment/review.

…ConfigFilePath standalone-safe

KristjanESPERANTO

I've changed the PR text to reflect the current approach.

The new script was introduced in MagicMirrorOrg/MagicMirror#3920.

@Blackspirits

Thanks to: @Blackspirits, @Crazylegstoo, @jarnoml, @jboucly, @JHWelch, @khassel, @KristjanESPERANTO, @rejas, @sdetweil, @xsorifc28 ⚠️ This release needs nodejs version >=22.21.1 <23 || >=24 [Compare to previous Release v2.33.0](v2.33.0...develop) [core] Prepare Release 2.34.0 (#3998) dependency update + adjust Playwright setup + fix linter issue (#3994) demo with gif (#3995) [core] fix: allow browser globals in config files (#3992) [core] fix: restore --ozone-platform=wayland flag for reliable Wayland support (#3989) [core] auto create release notes with every push on develop (#3985) [core] chore: simplify Wayland start script (#3974) [gitignore] restore the old Git behavior for the default modules (#3968) [core] configure cspell to check default modules only and fix typos (#3955) [gitignore] restoring the old Git behavior for the CSS directory (#3954) feat(core): add server:watch script with automatic restart on file changes (#3920) [check_config] refactor: improve error handling (#3927) refactor: replace express-ipfilter with lightweight custom middleware (#3917) refactor: replace module-alias dependency with internal alias resolver (#3893) [dependencies] [chore] update dependencies and min. node version (#3986) [core] bump dependencies into december (#3982) Bump actions/checkout from 5 to 6 (#3972) Update deps, unpin parse5 (#3934) [core] Update deps and pin jsdom to v27.0.0 (#3925) chore: update dependencies (#3921) update deps, exclude node v23 (#3916) remove eslint warnings, add npm publish process to Collaboration.md (#3913) feat: add ESlint rule no-sparse-arrays for config check (#3911) chore: bump dependencies into october (#3909) [logging] logger: add calling filename as prefix on server side (#3926) [logger] Add prefixes to most Log messages (#3923) [modules/alert] Add new pt and pt-BR translations for Alert module and update global PT strings (#3965) [modules/calendar] add checksum to test whether calendar event list changed (#3988) [calendar] fix: prevent excessive fetching on client reload and refactor calendarfetcherutils.js (#3976) [calendar] refactor: migrate CalendarFetcher to ES6 class and improve error handling (#3959) [calendar] Show repeatingCountTitle only if yearDiff > 0 (#3949) [tests] suppress debug logs in CI environment + improve calendar symbol test stability (#3941) [calendar] chore: remove requiresVersion: "2.1.0" (#3932) [calendar] test: remove "Recurring event per timezone" test (#3929) [modules/compliments] [compliments] refactor: optimize loadComplimentFile method and add unit tests (#3969) fix: set compliments remote file minimum delay to 15 minutes (#3970) [compliments] fix: duplicate query param "?" in compliments module refresh url (#3967) [modules/newsfeed] [newsfeed] fix header layout issue (#3946) [modules/weather] [weatherprovider] update subclass language use override (#3914) [weather] fix wind-icon not showing in pirateweather (#3957) [weather] add error handling to weather fetch functions, including cors (#3791) remove deprecated ukmetoffice datapoint provider, cleanup .gitignore (#3952) fixes problems with daylight-saving-time in weather provider openmeteo (#3931) Fix for envcanada Provider to use updated Env Canada URL (#3919) [weather] feat: add configurable forecast date format option (#3918) [testing] testing: update "Enforce Pull-Request Rules" workflow (#3987) [core] refactor: replace XMLHttpRequest with fetch and migrate e2e tests to Playwright (#3950) [test] replace node-libgpiod with serialport in electron-rebuild workflow (#3945) [ci] Add concurrency to automated tests workflow to cancel outdated runs (#3943) [tests] migrate from jest to vitest (#3940) --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Karsten Hassel <hassel@gmx.de> Co-authored-by: Kristjan ESPERANTO <35647502+KristjanESPERANTO@users.noreply.github.com> Co-authored-by: Ryan Williams <65094007+ryan-d-williams@users.noreply.github.com> Co-authored-by: Veeck <github@veeck.de> Co-authored-by: Bugsounet - Cédric <github@bugsounet.fr> Co-authored-by: Marc Landis <dirk.rettschlag@gmail.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: HeikoGr <20295490+HeikoGr@users.noreply.github.com> Co-authored-by: Pedro Lamas <pedrolamas@gmail.com> Co-authored-by: veeck <gitkraken@veeck.de> Co-authored-by: Magnus <34011212+MagMar94@users.noreply.github.com> Co-authored-by: Ikko Eltociear Ashimine <eltociear@gmail.com> Co-authored-by: DevIncomin <56730075+Developer-Incoming@users.noreply.github.com> Co-authored-by: Nathan <n8nyoung@gmail.com> Co-authored-by: mixasgr <mixasgr@users.noreply.github.com> Co-authored-by: Savvas Adamtziloglou <savvas-gr@greeklug.gr> Co-authored-by: Konstantinos <geraki@gmail.com> Co-authored-by: OWL4C <124401812+OWL4C@users.noreply.github.com> Co-authored-by: BugHaver <43462320+bughaver@users.noreply.github.com> Co-authored-by: BugHaver <43462320+lsaadeh@users.noreply.github.com> Co-authored-by: Koen Konst <koenspero@gmail.com> Co-authored-by: Koen Konst <c.h.konst@avisi.nl> Co-authored-by: dathbe <github@beffa.us> Co-authored-by: Marcel <m-idler@users.noreply.github.com> Co-authored-by: Kevin G. <crazylegstoo@gmail.com> Co-authored-by: Jboucly <33218155+jboucly@users.noreply.github.com> Co-authored-by: Jboucly <contact@jboucly.fr> Co-authored-by: Jarno <54169345+jarnoml@users.noreply.github.com> Co-authored-by: Jordan Welch <JordanHWelch@gmail.com> Co-authored-by: Blackspirits <blackspirits@gmail.com> Co-authored-by: Samed Ozdemir <samed@xsor.io>

KristjanESPERANTO reviewed Oct 19, 2025

View reviewed changes

.nvmrc Outdated Show resolved Hide resolved

package.json Outdated Show resolved Hide resolved

jboucly changed the title ~~Create .nvmrc file and create server:dev script~~ Create server:dev script Oct 21, 2025

jboucly changed the title ~~Create server:dev script~~ Create server:watch script Oct 21, 2025

jboucly requested a review from KristjanESPERANTO October 21, 2025 14:19

Jboucly and others added 10 commits October 22, 2025 13:26

feat: add .nvmrc file with Node.js v22.20.0

8da1f1c

feat: add nodemon for development et and created nodemon.json file fo…

74506e5

…r configuration

feat: update changelog file

4dbfe29

feat: remove .nvmrc file

925d91d

refactor(deps): remove nodemon

833aca9

feat: add feature to reload server with rs or restart in stdin

95c6d7f

feat: add a monitoring script to restart the server on changes

fa3dcad

feat: update changelog to reflect new server:watch script and remove …

8b24dbf

….nvmrc entry

feat: remove useless config file

dfb1a55

KristjanESPERANTO force-pushed the feat/add-server-auto-reload-and-nvm-config branch from 206421c to c2103f5 Compare October 22, 2025 12:54

KristjanESPERANTO changed the title ~~Create server:watch script~~ feat(core): add server:watch script with automatic restart on file changes Oct 22, 2025

khassel reviewed Oct 22, 2025

View reviewed changes

serveronly/watcher.js Outdated Show resolved Hide resolved

khassel reviewed Oct 26, 2025

View reviewed changes

serveronly/watcher.js Outdated Show resolved Hide resolved

serveronly/watcher.js Outdated Show resolved Hide resolved

serveronly/watcher.js Outdated Show resolved Hide resolved

serveronly/watcher.js Outdated Show resolved Hide resolved

KristjanESPERANTO added 3 commits October 27, 2025 20:39

refactor(watcher): remove hardcoded config path and localhost IP

b79bfcc

- Use existing getConfigFilePath() in getServerPort() - Remove hardcoded 127.0.0.1 from isPortAvailable() for container compatibility

refactor: centralize config file path resolution

d8fe63b

- Move getConfigFilePath() to server_functions.js - Use in app.js and watcher.js to avoid duplication

fix(watcher): bind port checks to config.address for container compat…

5d90279

…ibility

khassel reviewed Oct 27, 2025

View reviewed changes

serveronly/watcher.js Outdated Show resolved Hide resolved

khassel reviewed Oct 27, 2025

View reviewed changes

serveronly/watcher.js Outdated Show resolved Hide resolved

fix(watcher): use config.address for reload notifications

f38be2d

khassel approved these changes Oct 27, 2025

View reviewed changes

KristjanESPERANTO added 2 commits October 27, 2025 23:00

docs: update changelog entry

6fff61b

refactor(watcher): simplify by removing fallback logic and making get…

487d270

…ConfigFilePath standalone-safe

khassel approved these changes Oct 27, 2025

View reviewed changes

KristjanESPERANTO approved these changes Oct 27, 2025

View reviewed changes

khassel merged commit 961b3c9 into MagicMirrorOrg:develop Oct 28, 2025
9 checks passed

KristjanESPERANTO added a commit to KristjanESPERANTO/MagicMirror-Documentation that referenced this pull request Nov 4, 2025

Add documentation for server:watch script

4f54692

The new script was introduced in MagicMirrorOrg/MagicMirror#3920.

KristjanESPERANTO mentioned this pull request Nov 4, 2025

Add documentation for server:watch script MagicMirrorOrg/MagicMirror-Documentation#336

Merged

rejas pushed a commit to MagicMirrorOrg/MagicMirror-Documentation that referenced this pull request Nov 4, 2025

Add documentation for server:watch script (#336)

1adfb8e

The new script was introduced in MagicMirrorOrg/MagicMirror#3920.

sdetweil mentioned this pull request Jan 1, 2026

Release 2.34.0 #3999

Merged

Uh oh!

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

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

Uh oh!

Conversation

jboucly commented Oct 19, 2025 • edited by KristjanESPERANTO Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What it does

Implementation highlights

Configuration

Uh oh!

sdetweil commented Oct 19, 2025

Uh oh!

sdetweil commented Oct 19, 2025

Uh oh!

sdetweil commented Oct 19, 2025

Uh oh!

jboucly commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jboucly commented Oct 19, 2025

Uh oh!

sdetweil commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

KristjanESPERANTO commented Oct 19, 2025

Uh oh!

sdetweil commented Oct 19, 2025

Uh oh!

KristjanESPERANTO commented Oct 21, 2025

Uh oh!

KristjanESPERANTO commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jboucly commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

khassel commented Oct 27, 2025

Uh oh!

KristjanESPERANTO left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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

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

jboucly commented Oct 19, 2025 •

edited by KristjanESPERANTO

Loading

jboucly commented Oct 19, 2025 •

edited

Loading

sdetweil commented Oct 19, 2025 •

edited

Loading

KristjanESPERANTO commented Oct 22, 2025 •

edited

Loading

jboucly commented Oct 22, 2025 •

edited

Loading