Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Migration and Alternatives

Upgrading from Webpack 4 to 5

A step-by-step migration guide from webpack 4 to 5: asset modules replace file-loader, Node polyfills are gone, persistent caching, new ids and the removed options.

Many production projects still run on webpack 4 configs inherited from years ago. Webpack 5 is faster, produces smaller and more cacheable output, and is the version every current plugin targets, but it removes some conveniences and changes a few defaults. A careful migration is mostly mechanical. This lesson lists the breaking changes in the order you will meet them, with the replacement for each, and a practical upgrade routine.

Webpack cannot run on this site. The configs below are read-only. The TryIt blocks are Node.js stand-ins: one reads a legacy config object and prints the migration steps it needs, and one shows how polyfill-free code can replace Node built-ins. They illustrate the checks; they do not replace running the real build.

Before you start

  1. Make sure webpack 4 builds cleanly. Fix its deprecation warnings first.
  2. Update loaders and plugins to versions that support webpack 5 (html-webpack-plugin, mini-css-extract-plugin, terser-webpack-plugin, webpack-dev-server, babel-loader and so on). Most of the pain comes from a plugin that was never updated.
  3. Run on a current Node.js LTS. Commit, then upgrade in a branch.
  4. Run node --trace-deprecation node_modules/webpack/bin/webpack.js to see where deprecations come from.

What changed

1. file-loader, url-loader and raw-loader became asset modules

Webpack 5 handles files itself with asset modules:

Webpack 4 Webpack 5 type
file-loader asset/resource (emit a file, give its URL)
url-loader asset/inline (data URI) or asset with a size limit
raw-loader asset/source (the file's text)
JavaScript
// webpack 4
{ test: /\.(png|jpg|svg)$/, use: [{ loader: 'url-loader', options: { limit: 8192, name: '[name].[hash].[ext]' } }] }

// webpack 5
{
  test: /\.(png|jpg|svg)$/,
  type: 'asset',
  parser: { dataUrlCondition: { maxSize: 8 * 1024 } },
  generator: { filename: 'images/[name].[contenthash:8][ext]' },
}

Note the [ext] placeholder now includes the dot. Remove the old loaders from package.json.

2. No automatic Node.js polyfills

Webpack 4 silently bundled browser versions of crypto, stream, buffer, path, os and others when a dependency needed them, adding hundreds of kilobytes. Webpack 5 stops doing that. If a dependency needs one, you get "Module not found: Can't resolve 'crypto'". Your options, in order of preference:

  1. Stop needing it. Use the Web Crypto API, URL, TextEncoder, or a browser-friendly package.
  2. Provide a fallback explicitly: resolve.fallback: { path: require.resolve('path-browserify') }.
  3. Disable it: resolve.fallback: { fs: false } for modules that only run on the server.

Also, process and Buffer are no longer defined globally. Add new webpack.ProvidePlugin({ Buffer: ['buffer', 'Buffer'], process: 'process/browser' }) only where required.

Node.js Stand-in: replacing a Node built-in with a platform API

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

3. Persistent caching

The cache-loader and hard-source-webpack-plugin packages are obsolete. Use the built-in cache: { type: 'filesystem' } described in long-term caching. Delete cache-loader from your rules.

4. Deterministic ids and contenthash

Webpack 5 defaults to moduleIds: 'deterministic' and chunkIds: 'deterministic' in production. Remove plugins such as HashedModuleIdsPlugin and NamedChunksPlugin. For file names, [contenthash] now works as expected for JavaScript too.

5. Removed and renamed options

Webpack 4 Webpack 5
optimization.splitChunks.name: true Removed (names are deterministic)
node: { fs: 'empty' } resolve.fallback: { fs: false }
output.jsonpFunction output.chunkLoadingGlobal
output.futureEmitAssets Default behaviour
devServer.contentBase devServer.static
devServer.inline, hotOnly Removed / hot: 'only'
require.include, NamedModulesPlugin Removed
optimization.occurrenceOrder chunkIds: 'natural' etc.
CleanWebpackPlugin output.clean: true
terser-webpack-plugin@1 Version 5 (webpack 5 ships it)

webpack-cli also changed: use webpack serve instead of webpack-dev-server, and webpack --watch stays.

6. Better tree shaking and new features

Nested tree shaking, inner-module analysis and sideEffects now work better, so bundles may shrink without changes (see tree shaking). New features you can adopt after the migration: Module Federation, experiments.topLevelAwait, output.library.type: 'module' for ES module libraries, and resolve.conditionNames for exports field support.

A migration checker stand-in

This Node stand-in reads a webpack 4-style config object and reports the steps the migration needs. Real projects can do the same with a quick review.

Node.js Stand-in: audit a legacy config

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Upgrade routine

  1. Upgrade webpack, webpack-cli, webpack-dev-server and every loader and plugin in one go.
  2. Run the build and fix errors one at a time, top to bottom; the messages name the missing option or polyfill.
  3. Compare output sizes and chunk names with the old build using bundle analysis.
  4. Turn on cache: { type: 'filesystem' } and measure the second build time.
  5. Test in the browser: lazy routes, source maps, hot reload and every asset type (fonts and images are common regressions).
  6. Roll out behind your normal release process; keep the old config in git history for rollback.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which asset module type replaces file-loader?

    asset/resource emits the file to the output folder and gives its URL, like file-loader. asset/inline is a data URI; asset/source is the raw text.
  2. 2. A dependency fails with "Can't resolve 'crypto'" after upgrading. What is the best first approach?

    Webpack 5 no longer includes Node polyfills automatically. Prefer platform APIs, or provide a fallback package explicitly.
  3. 3. What replaces cache-loader and hard-source-webpack-plugin?

    Webpack 5 has a built-in persistent cache enabled with the filesystem cache type.
  4. 4. What is devServer.contentBase called in webpack 5?

    Static file serving moved to devServer.static.

Summary

  • Update loaders and plugins first, then webpack itself.
  • Asset modules replace file-, url- and raw-loader; polyfills are no longer automatic.
  • Use the built-in filesystem cache and deterministic ids.
  • Rename or remove changed options, then verify output and behaviour.

Next: Webpack vs Vite, Rollup and esbuild