Resolving Hot Refresh and Hot Module Replacement Issues in Webpack 4

Author Zhang Mingpan, a front‑end engineer at Beike, shares his experience troubleshooting Webpack hot refresh and hot reload problems in a project that combines front‑end JavaScript (built with Webpack), a Node authentication server, and a PHP back‑end.

1. Introduction – Webpack offers powerful features such as hot refresh (full page reload on file change) and hot reload (module‑level update without losing state). The article aims to document the pitfalls encountered while configuring these features in Webpack 4.

2. Problem scenario – The project uses a custom host entry (test.link.lianjia.com) and accesses the site via a domain name. After modifying JavaScript, the page did not refresh automatically, indicating that hot refresh was not working. A minimal demo using the IP address worked, suggesting the issue was related to host handling.

The error shown was "Invalid Host header" from webpack-dev-server . Investigation revealed that the checkHost function in webpack-dev-server/lib/Server.js validates the request host against several rules (disableHostCheck, localhost, allowedHosts, publicHost, etc.). In the author's setup the hostname test.link.lianjia.com did not satisfy any rule, so checkHost returned false and the server rejected the request.

Solution: add the domain to allowedHosts (whitelist) or disable host checking. After adding the whitelist, hot refresh started working.

3. Enabling hot module replacement – To move from hot refresh to hot reload, the following configuration was added:

devServer: {
    contentBase: './dist',
    port: '7008',
    inline: true,
    host: '0.0.0.0',
    disableHostCheck: true, // disable host check for team development
    hot: true,
    plugins: [
        new MiniCssExtractPlugin({ filename: "css/[name].css" }),
        new HtmlWebpackPlugin({ title: 'Output Management' }),
        new webpack.HotModuleReplacementPlugin()
    ]
}

if (module.hot) {
    module.hot.accept();
}

During this process a CORS error appeared because webpack-dev-server runs an Express server. The author first tried a proxy configuration (which is for forwarding requests to another server) and then added a before hook to set CORS headers:

before: (app) => {
    app.use('*', (req, res, next) => {
        res.header("Access-Control-Allow-Origin", "*");
        res.header("Access-Control-Allow-Methods", "POST,GET");
        res.header("Access-Control-Allow-Headers", "Origin,Accept,Content-Type,Content-Length, Authorization, Accept,X-Requested-With");
        next();
    });
}

After these changes, hot module replacement worked correctly.

4. Source‑code analysis – The article walks through the relevant parts of the Webpack source that handle host checking, hot update emission, and module acceptance. Key functions examined include Server.prototype.checkHost , the socket‑based ok handler, reloadApp , and the logging utilities that report which modules were updated or could not be hot‑updated.

5. Summary – When facing configuration‑related issues, consult the official documentation first. If the docs do not help, trace the source code step by step, focusing on error messages. The final recommended Webpack 4 configuration for hot refresh and hot reload is provided below.

devServer: {
    contentBase: './dist',
    port: '7008',
    inline: true,
    host: '0.0.0.0',
    disableHostCheck: true,
    // allowedHosts: ['your-domain.com'] // optional whitelist
}

// Full hot‑reload configuration
devServer: {
    contentBase: './dist',
    port: '7008',
    inline: true,
    host: '0.0.0.0',
    disableHostCheck: true,
    hot: true,
    before: (app) => {
        app.use('*', (req, res, next) => {
            res.header("Access-Control-Allow-Origin", "*");
            res.header("Access-Control-Allow-Methods", "POST,GET");
            res.header("Access-Control-Allow-Headers", "Origin,Accept,Content-Type,Content-Length, Authorization, Accept,X-Requested-With");
            next();
        });
    }
},
plugins: [
    new MiniCssExtractPlugin({ filename: "css/[name].css" }),
    new HtmlWebpackPlugin({ title: 'Output Management' }),
    new webpack.HotModuleReplacementPlugin()
]

if (module.hot) {
    module.hot.accept();
}

By following these steps—checking host validation, adding a whitelist or disabling the check, configuring CORS, and enabling the HotModuleReplacementPlugin—developers can achieve stable hot refresh and hot module replacement in Webpack 4 projects.