webpack-retry-chunk-load-plugin

3.1.1 verified Sat Apr 25 auth: no javascript

A webpack plugin that automatically retries loading of async chunks that fail to load. Version 3.1.1 supports webpack 5 or newer. It is actively maintained, with regular updates. Key features include configurable retry delay, maximum retries, chunk filtering, cache busting, and a last resort script. It provides TypeScript type declarations and is a drop-in solution compared to manual retry logic.

Common errors

error Cannot find module 'webpack-retry-chunk-load-plugin' ↓

cause Package not installed or missing from node_modules.

fix

Run npm install webpack-retry-chunk-load-plugin --save-dev

error TypeError: RetryChunkLoadPlugin is not a constructor ↓

cause Default import used incorrectly; plugin is a named export.

fix

Use import { RetryChunkLoadPlugin } from 'webpack-retry-chunk-load-plugin' or require with destructuring.

error Error: webpack version 4.x is not supported ↓

cause Using v2+ of the plugin with webpack 4.

fix

Either upgrade to webpack 5 or use v1.x of the plugin.

Warnings

breaking Version 2.0.0 dropped webpack 4 support; only webpack 5+ is compatible. ↓

fix Upgrade to webpack 5 or stay on v1.x for webpack 4.

gotcha The cacheBust option must be a stringified function expression, not a plain string. ↓

fix Use a string like `function() { return Date.now(); }` instead of just `Date.now()`.

gotcha The plugin only retries loading of chunks that failed; it does not affect initial bundle loading. ↓

fix Ensure your chunk splitting is configured correctly for async chunks.

gotcha The lastResortScript option must be a string of JavaScript code, not a function reference. ↓

fix Pass a string like "window.location.href='/error'" instead of a function.

Install

npm install webpack-retry-chunk-load-plugin

yarn add webpack-retry-chunk-load-plugin

pnpm add webpack-retry-chunk-load-plugin

Imports

RetryChunkLoadPlugin

wrong

const RetryChunkLoadPlugin = require('webpack-retry-chunk-load-plugin')

correct

import { RetryChunkLoadPlugin } from 'webpack-retry-chunk-load-plugin'

Named import is correct; the plugin is exported as a named member. CommonJS require works if not using ESM.

Quickstart

Shows how to require and instantiate the plugin in a webpack config with common options.

const { RetryChunkLoadPlugin } = require('webpack-retry-chunk-load-plugin');

module.exports = {
  plugins: [
    new RetryChunkLoadPlugin({
      maxRetries: 3,
      retryDelay: 1000,
      cacheBust: `function() { return Date.now(); }`,
      lastResortScript: "window.location.href='/500.html';",
    }),
  ],
};