Numerous Philanthropic Misanthropes
    Have ideas to improve npm?Join in the discussion! »

    @wordpress/lazy-import
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.3 • Public • Published

    Lazy Import

    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

    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.

    Requirements

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

    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( 'fbjs@^1.0.0', {
    	localPath: './lib/shallowEqual',
    	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

    localPath

    • Type: string
    • Required: No

    Local path pointing to a file or directory that can be used when other script that main needs to be imported.

    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.

    Install

    npm i @wordpress/lazy-import

    DownloadsWeekly Downloads

    266

    Version

    1.2.3

    License

    GPL-2.0-or-later

    Unpacked Size

    113 kB

    Total Files

    9

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar