webpack webpack-dev-server html-webpack-plugin

The effect of HtmlWebpackPlugin on webpack dev server

I'm using Webpack on a React project and it seems like HtmlWebpackPlugin affects the webpack dev server in a weird way that I don't understand.

It seems to allow me to browse to index.html no matter where that file is in the code base, something that is not possible using the dev server alone.

Let's say that I have the following directory structure:

myproj/
  |- package.json
  |- webpack.config.js
  |- src/
    |- index.html
    |- index.jsx

and a webpack.config.js file that looks like this:

const path = require('path');

module.exports = {
    entry: './src/index.jsx',
   
    devServer: {
        contentBase: __dirname
    }
};

Then I run webpack-dev-server --mode=development. Since I have devServer.contentBase set to the current directory (myproj) and the index.html file is inside myproj/src, I must browse to http://localhost:8080/src/index.html to see my web app. If I try browsing http://localhost:8080/index.html then I get a 404. That makes sense to me.

Then I add the HtmlWebpackPlugin, changing nothing else inside webpack.config.js:

const HtmlWebpackPlugin = require('html-webpack-plugin');
....
plugins: [
    new HtmlWebpackPlugin({
        template: './src/index.html'
    })
]

Now all of a sudden I can browse to http://localhost:8080/index.html just fine. In fact, I can hit either http://localhost:8080/index.html or http://localhost:8080/src/index.html.

What's up with that? What did HtmlWebpackPlugin do to make this possible?

Solution

Okay, I think I figured this out.

TL;DR

Once you add HtmlWebpackPlugin you should remove this line from index.html:

<script type="text/javascript" src="main.bundle.js"></script>

and only browse to http://localhost:8080/index.html.

The Tedious Details:

Once you add in HtmlWebpackPlugin, it takes your index.html file and merges in a <script> tag that points to your webpack bundle. It serves this merged html file from http://localhost:8080. It does this even if index.html already contains a reference to the bundle.

The plugin doesn't actually overwrite index.html with the merged version. So browsing to http://localhost:8080/src/index.html just shows you that file as it is on disk.

So if your src/index.html file looks like this before you add HtmlWebpackPlugin:

<body>
    <div id="app">it worked</div>
    <script type="text/javascript" src="main.bundle.js"></script>
</body>

then after you add HtmlWebpackPlugin, browsing to http://localhost:8080 gives you this merged version:

<body>
    <div id="app">it worked</div>
    <script type="text/javascript" src="main.bundle.js"></script>
    <script type="text/javascript" src="main.bundle.js"></script>
</body>

So now you will have two references to the bundle, the one you added in the file and the one HtmlWebpackPlugin added.

Browsing to http://localhost:8080/src gives you what's on disk at src/index.html:

<body>
    <div id="app">it worked</div>
    <script type="text/javascript" src="main.bundle.js"></script>
</body>

However, since he whole point of using HtmlWebpackPlugin is to let it insert the bundle reference for you, that means you should remove that <script> tag from src/index.html. That in turn means that browsing to src/index.html won't work anymore because you no longer have a reference to your bundle!

You are now reliant on letting HtmlWepbackPlugin insert the <script> tag for you, which means that you must now browser to http://localhost:8080/index.html to get the version it generated.

Webpack. Be. Crazy.