@wordpress/lazy-import Edit

Import an NPM module, even if not installed locally or defined as a dependency of the project. Uses a locally installed package if available. Otherwise, the package will be downloaded dynamically on-demand.

Installation Installation

Install the module

npm install @wordpress/lazy-import --save

This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Top ↑

Requirements Requirements

NPM 6.9.0 or newer is required, since it uses the package aliases feature to maintain multiple versions of the same package.

Top ↑

Usage Usage

Usage is intended to mimic the behavior of the dynamic import function, receiving the name (and optional version specifier) of an NPM package and returning a promise which resolves to the required module.

Note: Currently, this alignment to import is superficial, and the module resolution still uses CommonJS require, rather than the newer ES Modules support. Future versions of this package will likely support ES Modules, once an LTS release of Node.js including unflagged ES Modules support becomes available.

The string passed to lazyImport can be formatted exactly as you would provide to npm install, including an optional version specifier (including version ranges). If the version specifier is omitted, it will be treated as equivalent to *, using the version of a locally installed package if available, otherwise installing the latest available version.

const lazyImport = require( '@wordpress/lazy-import' );

lazyImport( 'is-equal-shallow@^0.1.3' ).then( ( isEqualShallow ) => {
    console.log( isEqualShallow( { a: true, b: true }, { a: true, b: true } ) );
    // true
} );

If you’re using Node v14.3.0 or newer, you can also take advantage of top-level await to simplify top-level imports:

const lazyImport = require( '@wordpress/lazy-import' );

const isEqualShallow = await lazyImport( 'is-equal-shallow@^0.1.3' );
console.log( isEqualShallow( { a: true, b: true }, { a: true, b: true } ) );
// true

lazyImport optionally accepts a second argument, an options object:

const lazyImport = require( '@wordpress/lazy-import' );

function onInstall() {
    console.log( 'Installing…' );

lazyImport( 'is-equal-shallow@^0.1.3', { onInstall } ).then( /* ... */ );

Note that lazyImport can throw an error when offline and unable to install the dependency using NPM. You may want to anticipate this and provide remediation steps for a failed install, such as logging a warning messsage:

try {
    await lazyImport( 'is-equal-shallow@^0.1.3' );
} catch ( error ) {
    if ( error.code === 'ENOTFOUND' ) {
        console.log( 'Unable to connect to NPM registry!' );

Options Options

onInstall onInstall

  • Type: Function
  • Required: No

Function to call if and when the module is being installed. Since installation can cause a delay in script execution, this can be useful to output logging information or display a spinner.

An installation can be assumed to finish once the returned promise is resolved.

Code is Poetry.