What’s the issue?
Webpack supports adding multiple entry points in an app. Entry Points page in documentation explains that a bundle for each entry point is created separately, which can help reduce load time by caching bundles that aren’t modified (e.g. node_modules). But having multiple entry points may lead to following error during hot reloads:
ChunkLoadError: Loading hot update failed.
One of my org’s repo had a long standing issue of hot reloads not working. Digging further into the issue, I found this solution on stack overflow of adding runtimeChunk: 'single' to webpack.dev.js. But there was hardly any explanation of what the other options for runtimeChunk actually did in simple words.
Understanding runtimeChunk in Webpack
Runtime code is a tiny file Webpack adds to manage module loading and execution when your site runs. It also handles import() statements for code-splitting. The runtimeChunk option controls how the Webpack runtime file is included in your final bundles. There are three primary options:
| Value | Files created | What it does | Best For |
|---|---|---|---|
| ‘single’ | runtime.bundle.js | a single runtime file is created, which is a singleton for all bundles to refer from | Multi-entry or code splitting setups |
| ‘multiple’ | runtime\~userApp.bundle.js, runtime\~adminApp.bundle.js | a unique runtime file is created for each bundle | Fully isolated entry points |
| false (default) | no runtime files created | a single runtime chunk is created, whose copy is sent to all bundles | Simple apps |
We can see this with a simple experiment too. Create two entry points - userApp and adminApp. Now let’s use /public dir for webpack’s build. Try each of the runtimeChunk options.
Why ChunkLoadError Happens
When using anything other than single, each entry point gets its own runtime file. During hot module replacement (HMR), only the modified chunks are updated. If one runtime is updated but another isn’t, their internal logic can get out of sync. This mismatch causes the browser to fail loading the updated chunk.
This issue only affects projects with multiple entry points, because single-entry-point apps don’t have to coordinate multiple runtimes.
Using runtimeChunk: 'single' guarantees that all entry points refer to the same runtime file, and updates remain consistent across the board during hot reloads.