Migrating to Webpack 5: Team Practices, Pitfalls, and New Features

Webpack 5 was officially released on October 10 2020 and has since received numerous minor updates, introducing features such as persistent disk caching, improved long‑term caching, better tree‑shaking, enhanced web‑platform compatibility, and internal clean‑ups.

Team Practice

The team migrated from Webpack 4 by following the official upgrade guide, addressing required changes like Node version ≥10.13.0, upgrading html-webpack-plugin , workbox-webpack-plugin , and webpack-dev-server to versions compatible with Webpack 5, and handling the removal of Node.js polyfills.

// webpack.config.js
{
    ..., 
    plugins: [
        ..., 
        new webpack.ProvidePlugin({
            process: 'process/browser',
        }),
    ]
}

Common warnings can be resolved by updating plugins such as terser-webpack-plugin and mini-css-extract-plugin .

Preparation

Upgrade Node to ^10.13.0.

Upgrade html-webpack-plugin to a version that supports Webpack 5.

Upgrade workbox-webpack-plugin accordingly.

Upgrade webpack-dev-server to ^4 (next) to avoid HMR issues.

Install polyfills for removed Node.js core modules (e.g., process ).

npm install webpack@latest --dev

Pitfalls

Ecosystem Alignment

Errors such as Cannot add property htmlWebpackPluginAlterChunks, object is not extensible are solved by updating html-webpack-plugin . Similar issues with workbox-webpack-plugin and optimize-css-assets-webpack-plugin are addressed by switching to css-minimizer-webpack-plugin .

HMR Breakage

Webpack 5 requires target: 'web' in the configuration for HMR to work; using an array for target disables it. Upgrading webpack-dev-server to the next version resolves the problem.

Build‑time New Features

Asset Modules

Webpack 5 provides built‑in handling for static assets without extra loaders. Example configuration:

// webpack.config.js
module.exports = {
    ..., 
    module: {
        rules: [{
            test: /\.(png|jpg|svg|gif)$/,
            type: 'asset/resource',
            generator: {
                filename: 'assets/[hash:8].[name][ext]'
            }
        }]
    }
}

Supported types: asset/source , asset/inline , asset/resource , and asset (auto‑select based on size).

Filesystem Cache

Webpack 5 includes built‑in filesystem caching for modules and chunks, configurable via the cache option.

// webpack.config.js
module.exports = {
    ..., 
    cache: {
        type: 'filesystem',
        buildDependencies: { config: [__filename] },
        name: ''
    }
}

Cache files are stored under node_modules/.cache/webpack/default-production by default.

WebAssembly Support

Webpack 5 adds native async WebAssembly support. Enable it with:

// webpack.config.js
module.exports = {
    ..., 
    experiments: { asyncWebAssembly: true },
    module: { rules: [{ test: /\.wasm$/, type: 'webassembly/async' }] }
}

Usage becomes as simple as importing the generated .wasm file.

Web Worker Support

New syntax allows creating workers via new URL() without a dedicated loader:

// master.js
const worker = new Worker(new URL('./calc.js', import.meta.url), { name: 'calc' });
worker.onmessage = e => console.log(e.data.value);

Legacy worker-loader still works for projects that rely on the .worker.js convention.

Runtime New Features

Removed Node.js Polyfills

Developers must manually add polyfills for Node core modules (e.g., process ) when needed.

Improved Long‑Term Caching

Webpack 5 generates stable chunk IDs and real content hashes, reducing cache invalidation when unrelated files change.

Top‑Level Await

Enable with experiments.topLevelAwait = true and use await directly at module top level.

// webpack.config.js
module.exports = {
    ..., 
    experiments: { topLevelAwait: true }
}

Example usage replaces async IIFE wrappers.

Performance Comparison

Enabling filesystem cache dramatically speeds up second builds. Long‑term cache tests show that only modified chunks cause cache invalidation in Webpack 5, unlike Webpack 4 where a new chunk invalidated all.

Conclusion

Webpack 5 offers many new features that improve build performance, bundle size, and developer experience. Upgrading is relatively smooth thanks to ecosystem alignment and comprehensive documentation.

Recruitment Notice

The ByteDance front‑end team is hiring; interested candidates can follow the provided referral code HTZYCHN or contact [email protected] .