Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

You save a file and the browser does not update

ErrorNo rebuild appears in the terminal after saving a file

Short answer

Saving a file must trigger two things: webpack has to notice the change and rebuild, and the browser has to receive the update over a websocket. Run the dev server with progress output to see which half fails, then check the watcher (polling, inotify, editor safe write), the update handler, or the websocket URL behind a proxy.

  • Applies to webpack 5, webpack-dev-server 5, Node.js 22, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Start the dev server with progress output and save a file. If the terminal shows a new build, the watcher works and the problem is the browser side. If nothing happens, the watcher is the problem.

    npx webpack serve --progress
  2. 2Match what you see, then jump to its fix

    1. 1Nothing happens in the terminal when you saveThe file watcher never sees the change (Docker, VM, WSL, network drive)Fix
    2. 2Rebuilds happen with some editors or after some saves, but not othersThe editor saves in a way that does not trigger the watcherFix
    3. 3The build finishes, then the whole page reloads and state is lostNo module accepts the update, so the dev server falls back to a full reloadFix
    4. 4Edits to a template (for example a .php or .html file) never refresh the pageFiles outside the bundle are not watched, or hot is switched offFix
    5. 5The build updates in the terminal but the browser console shows a failed websocket connectionThe browser cannot reach the dev server's websocket (proxy, other host or port)Fix

What does the error look like?

  • No rebuild appears in the terminal after saving a file
  • The page does a full reload instead of a hot update
  • Changes appear only after a manual refresh or a restart of the dev server

Cause 1 of 5

The file watcher never sees the change (Docker, VM, WSL, network drive)

1Check

File events often do not cross a bind mount, a VirtualBox shared folder, NFS or the Windows-to-WSL boundary. On Linux, a low inotify watch limit has the same effect.

cat /proc/sys/fs/inotify/max_user_watches

2Fix

Turn on polling in the webpack config and keep the large node_modules folder out of the watch. If the inotify limit is low, raise it.

// webpack.config.js
module.exports = {
  watchOptions: {
    poll: 1000,
    ignored: /node_modules/,
  },
};

# raise the inotify limit on Ubuntu
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

3Verify

Restart the dev server, edit a source file and watch for a new build line.

npx webpack serve --progress

Confirmed by webpack.js.org

Did this fix it?

Cause 2 of 5

The editor saves in a way that does not trigger the watcher

1Check

Some editors write through a backup copy or a safe-write temp file, and the watcher then misses the change. Vim and WebStorm are the two the webpack docs name.

webpack --watch --progress

2Fix

In Vim set backupcopy so the original file is overwritten. In WebStorm turn off the safe-write or back-up-before-saving setting.

:set backupcopy=yes

3Verify

Save again and check that the progress output shows a rebuild.

npx webpack serve --progress

Confirmed by webpack.js.org

Did this fix it?

Cause 3 of 5

No module accepts the update, so the dev server falls back to a full reload

1Check

When a module changes, webpack walks up through the modules that import it looking for one that accepts the change. If none does, the update is aborted and webpack-dev-server reloads the page. Plain JavaScript needs an accept call. React, Vue, Svelte and Angular get it from their own loader or tooling.

grep -R "module.hot\|import.meta.webpackHot" src | head

2Fix

For plain modules, accept the dependency in the module that imports it. For a framework, use its documented HMR loader or plugin instead of writing accept calls by hand.

import printMe from './print.js';

if (module.hot) {
  module.hot.accept('./print.js', function () {
    printMe();
  });
}

3Verify

Edit print.js and confirm the console callback runs without a page reload.

npx webpack serve --hot

Confirmed by webpack.js.org

Did this fix it?

Cause 4 of 5

Files outside the bundle are not watched, or hot is switched off

1Check

liveReload refreshes the page on file changes, but the hot option must be disabled or watchFiles must be set for it to take effect. A template that is not imported by any bundle is only watched if you list it in watchFiles.

grep -n "hot\|liveReload\|watchFiles" webpack.config.js

2Fix

List the extra files in watchFiles. Check that liveReload is not set to false.

module.exports = {
  devServer: {
    watchFiles: ['src/**/*.php', 'public/**/*'],
    liveReload: true,
  },
};

3Verify

Restart the dev server and edit one of the listed files.

npx webpack serve

Confirmed by webpack.js.org

Did this fix it?

Cause 5 of 5

The browser cannot reach the dev server's websocket (proxy, other host or port)

1Check

The client script does not always know where the dev server really is when a proxy sits in front of it. Look at the Network tab, filter by WS, and see which URL the client is trying.

npx webpack serve --progress

2Fix

Tell the client where to connect. The value auto://0.0.0.0:0/ws makes it take protocol, host and port from the browser address.

module.exports = {
  devServer: {
    client: {
      webSocketURL: 'auto://0.0.0.0:0/ws',
    },
  },
};

3Verify

Reload the page: the WS request in the Network tab should connect, and an edit should update the page.

npx webpack serve

Confirmed by webpack.js.org

Did this fix it?

How do I stop it coming back?

  • In Docker or a VM, set watchOptions.poll from the start and ignore node_modules.
  • Use the HMR loader or plugin your framework documents rather than relying on a full reload.
  • List non-bundled template files in devServer.watchFiles when they should refresh the page.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.