Bundle Loader

0.5.6 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader that wraps modules in a require.ensure block to create separate chunks for lazy loading. Version 0.5.6 is the current stable release; last updated February 2018. Key differentiator: simple callback-based API for loading code-split bundles on demand, with options for lazy loading and custom chunk naming. Unlike dynamic import(), it uses webpack's legacy require.ensure and is best suited for webpack 1–3 projects. No longer actively maintained; users should migrate to webpack's built-in dynamic import or @loadable-component.

Common errors

error require.ensure is not a function ↓

cause bundle-loader is used with webpack 4+ which removed require.ensure or the loader is not applied correctly.

fix

Ensure the loader is applied to the correct file pattern and consider upgrading to dynamic import(). For webpack 4, use output.enabledChunkLoadingTypes or migrate.

error Module not found: Error: Can't resolve 'bundle-loader' ↓

cause bundle-loader is not installed or webpack configuration is missing resolveLoader.

fix

Run 'npm install bundle-loader --save-dev' and ensure webpack is configured to resolve node_modules loaders.

error Error: Chunk.entrypoints: Use Chunks.groupsIterable and filter by instanceof Entrypoint instead ↓

cause Using bundle-loader with webpack 5 which deprecated the entrypoints API.

fix

Use webpack 4 or migrate to dynamic import(). This is a compatibility issue.

Warnings

deprecated bundle-loader uses legacy require.ensure which is discouraged in webpack 4+. Use dynamic import() instead. ↓

fix Replace bundle-loader usage with dynamic import() and webpack's magic comments.

gotcha Chunks generated by bundle-loader respect output.chunkFilename, not output.filename. Default chunkFilename may produce unexpected filenames. ↓

fix Set output.chunkFilename in webpack config (e.g., '[name].[id].js') and use the name option to control chunk naming.

gotcha When using the name option, [name] refers to the custom name set in options, not the original module name. [hash] does not work correctly in the name option. ↓

fix Use [name] in the name option to set a custom name; add hash via output.chunkFilename instead.

breaking In webpack 2+, the loader configuration must use module.rules instead of module.loaders. Using loaders will break silently. ↓

fix Use module.rules array with use/loader property.

deprecated The package is no longer actively maintained. Last release was in 2018. No new features or bug fixes are expected. ↓

fix Consider migrating to dynamic import() or a modern code-splitting library like @loadable/component.

Install

npm install bundle-loader

yarn add bundle-loader

pnpm add bundle-loader

Imports

bundle-loader
wrong
```
const bundle = require('bundle-loader!./file.bundle.js');
```
correct
```
import bundle from './file.bundle.js';
```
bundle-loader returns a function that takes a callback; the callback receives the module exports. Inline loader syntax is deprecated.
bundle-loader (CommonJS)
wrong
```
const bundle = require('bundle-loader!./file.bundle.js');
```
correct
```
const bundle = require('./file.bundle.js');
```
CommonJS require returns the same callback-wrapped function as ESM import. Avoid inline loader syntax.

Options with webpack config

wrong

module.exports = { module: { loaders: [ { test: /\.bundle\.js$/, loader: 'bundle-loader?lazy=true' } ] } };

correct

module.exports = { module: { rules: [ { test: /\.bundle\.js$/, use: { loader: 'bundle-loader', options: { lazy: true } } } ] } };

Use module.rules (webpack 2+) and options object instead of inline query strings and loaders array.

Quickstart

Shows how to set up bundle-loader in webpack config and use it to lazy load a module only on user click.

// webpack.config.js
module.exports = {
  entry: './App.js',
  output: {
    path: __dirname + '/dist',
    filename: '[name].js',
    chunkFilename: '[name].[id].js'
  },
  module: {
    rules: [
      {
        test: /\.bundle\.js$/,
        use: {
          loader: 'bundle-loader',
          options: {
            lazy: true,
            name: '[name]'
          }
        }
      }
    ]
  }
};

// App.js
import loadLazyModule from './lazy.bundle.js';

// The module is not loaded until the callback is invoked
document.getElementById('button').addEventListener('click', () => {
  loadLazyModule((module) => {
    console.log('Lazy module loaded:', module);
  });
});