@bigcommerce/script-loader

@bigcommerce/script-loader

A library for loading JavaScript files asynchronously. It loads script files by injecting script tags into DOM during runtime.

Install

You can install this library using npm.

npm install --save @bigcommerce/script-loader

Usage

For scripts

To load a single script:

import { createScriptLoader } from '@bigcommerce/script-loader';

const loader = createScriptLoader();

loader.loadScript('https://cdn.foo.bar/main.js')
    .then(() => {
        console.log('Loaded!');
    });

To load multiple scripts:

loader.loadScripts([
    'https://cdn.foo.bar/vendor.js',
    'https://cdn.foo.bar/main.js',
]);

To load a script with async attribute:

loader.loadScript('https://cdn.foo.bar/main.js', { async: true });

To preload or prefetch a script:

loader.preloadScript('https://cdn.foo.bar/chunk.js');
loader.preloadScript('https://cdn.foo.bar/another-chunk.js', { prefetch: true });

A prefetched script is a low priority resource, therefore it will be downloaded in the background when the browser is idle. On the other hand, a script without prefetch option will be marked as a high priority resource and downloaded immediately.

Please note that the preloaded or prefetched script won't be executed. It will just be downloaded to the browser cache. To attach it to the document and execute it, you will need to call loadScript with the same URL.

To preload or prefetch multiple scripts:

loader.preloadScripts([
    'https://cdn.foo.bar/chunk.js',
    'https://cdn.foo.bar/another-chunk.js',
]);

loader.preloadScripts([
    'https://cdn.foo.bar/chunk.js',
    'https://cdn.foo.bar/another-chunk.js',
], { prefetch: true });

For browsers that don't have the ability to preload or prefetch resources, scripts will be loaded using regular Ajax requests instead.

For stylesheets

To load a single stylesheet:

import { createStylesheetLoader } from '@bigcommerce/script-loader';

const loader = createStylesheetLoader();

loader.loadStylesheet('https://cdn.foo.bar/main.css')
    .then(() => {
        console.log('Loaded!');
    });

To load multiple stylesheets:

loader.loadStylesheet([
    'https://cdn.foo.bar/vendor.css',
    'https://cdn.foo.bar/main.css',
]);

To prepend, instead of append, a stylesheet to the head of a document:

loader.loadStylesheet('https://cdn.foo.bar/main.css', { prepend: true });

To preload or prefetch a stylesheet:

loader.preloadStylesheet('https://cdn.foo.bar/chunk.css');
loader.preloadStylesheet('https://cdn.foo.bar/another-chunk.css', { prefetch: true });

Similar to a preloaded script, a preloaded or prefetched stylesheet won't take an effect until it is attached to the document. To do it, you will need to call loadStylesheet with the same URL.

loader.preloadStylesheets([
    'https://cdn.foo.bar/chunk.css',
    'https://cdn.foo.bar/another-chunk.css',
]);

loader.preloadStylesheets([
    'https://cdn.foo.bar/chunk.css',
    'https://cdn.foo.bar/another-chunk.css',
], { prefetch: true });

Contribution

To release:

npm run release

To see other available commands:

npm run

License

MIT

Changelog

2.0.0 (2019-10-03)

⚠ BREAKING CHANGES

• core: Previously, when a script is loaded, we return the associated event object inside a promise object to the caller. With this change, we return an empty promise object instead. This change is necessary because we can't guarantee that scripts can be loaded in the same way across different browsers. For example, some browsers don't support rel="preload", so as a fallback, we have to preload scripts using regular XHR calls. In that case, we don't have an event object to return to the caller. We could potentially mock the event object to keep the return values consistent. But considering it is not a very useful thing to return, we've decided to make a breaking change and return nothing instead.

Bug Fixes

• core: CHECKOUT-4455 Provide fallback for browsers that don't support preload attribute (0fc52e7)

• core: CHECKOUT-4455 Stop resolving promise with load event (670fd2c)

<a name="1.0.0"></a>