promise-loader

1.0.0 verified Sat Apr 25 auth: no javascript maintenance

A Webpack loader that provides a promise-based alternative to bundle-loader for code splitting. It wraps lazy-loaded chunks behind a function that returns a Promise<module>, allowing you to control when the chunk is fetched. The loader requires a promise library parameter (e.g., 'bluebird', 'Q', or 'global'). Supports named chunks and filename/name substitutions in bundle names. Stable version 1.0.0, by Dan Abramov. Useful for single-page apps needing promise-based lazy loading with Webpack.

Common errors

error Module not found: Error: Cannot resolve module 'promise' ↓

cause The 'promise' package is not installed as a node_modules package; the loader is not being invoked correctly.

fix

Install the promise-loader package: npm install promise-loader --save-dev. Then use require('promise?bluebird!./file.js') with the loader prefix.

error TypeError: load is not a function ↓

cause The query parameter to specify the promise library is missing, causing the loader to return the module directly instead of a loading function.

fix

Add a query string with a promise library, e.g., require('promise?bluebird!./file.js'). Then load() returns a Promise.

error Cannot find module 'bluebird' ↓

cause The specified promise library (e.g., 'bluebird') is not installed or not available in the project's dependencies.

fix

Install the promise library: npm install bluebird. Alternatively, use 'global' if you have a global Promise.

Warnings

breaking You must specify a promise library as a query parameter; there is no default. ↓

fix Add a parameter like 'bluebird', 'Q', or 'global' to the loader query: require('promise?bluebird!./file.js').

gotcha Only 'lazy' mode is supported; unlike bundle-loader you cannot get an immediate synchronous require. ↓

fix Always use the returned function and await its promise. If you need synchronous loading, use bundle-loader instead.

deprecated Loader query syntax with '?' and ',' may be deprecated in newer Webpack versions in favor of options or resourceQuery. ↓

fix For Webpack 5+, consider using a custom rule with the 'use' property and options object, or use a different loader like @webpack-contrib/promise-loader.

breaking The 'global' promise parameter uses window.Promise; if unavailable, it will fail. ↓

fix Ensure a global Promise is present, either via native Promise or a polyfill like core-js or es6-promise.

Install

npm install promise-loader

yarn add promise-loader

pnpm add promise-loader

Imports

promise-loader
wrong
```
import load from 'promise!./file.js';
```
correct
```
const load = require('promise?bluebird!./file.js');
```
This is a Webpack loader, not a module. You 'require' it with a query parameter specifying the promise library. ESM import will not work directly; use require or configure in webpack.config.js.
promise-loader with chunk name
wrong
```
const load = require('promise?bluebird!./editor.js'); // missing chunk name
```
correct
```
const load = require('promise?bluebird,editor!./editor.js');
```
Chunk name is optional but if omitted, the chunk will have a numeric id. Specify as a comma-separated second parameter after the promise library.
promise-loader as a loader in webpack config
wrong
```
{ test: /\.json$/, loader: 'promise?bluebird' }
```
correct
```
{ test: /\.i18n\.json$/, loader: 'promise?global,[name].i18n' }
```
Use the 'loader' property in a rule. The query string includes the promise library and optional chunk name pattern with [filename] or [name] substitutions.

Quickstart

This shows how to configure promise-loader in Webpack to load files ending with .async.js lazily using Bluebird promises.

// webpack.config.js
module.exports = {
  entry: './index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist'
  },
  module: {
    loaders: [
      {
        test: /\.async\.js$/,
        loader: 'promise?bluebird'
      }
    ]
  }
};

// index.js
var load = require('./some.async.js');
load().then(function(module) {
  console.log(module);
}).catch(function(err) {
  console.error(err);
});