Fetch Inject
A fetching async loader and DOM injection sequencer for high-performance websites.
Discuss it on Hacker News
Background
This library implements a performance optimization technique known as Fetch Injection for managing async dependencies with JavaScript. It also works for stylesheets too, and was designed to be extensible for any resource type which can be loaded using fetch
.
Use Fetch Inject to dynamically import page resources such as JS and CSS in parallel (even across the network), and load them into your page in a desired sequence.
Because it uses Fetch API, Fetch Inject will work alongside Service Workers, enabling you take the performance of your Progressive Web Apps to an entirely new level.
Waterfalls
Here are some example waterfalls using Fetch Inject, as well as links to more info and a live demo.
Loading Bootstrap 4:
Loading jQuery, Transit, Hover Intent, Superfish, Animo and main JS:
Loading and initializing PhotoSwipe:
For a more complex example see article titled Putting WordPress into Hyperdrive on Hacker Noon. A live demo is available on wordcamp.habd.as.
WordPress Plugin
Fetch Inject has been built into a WordPress plugin, enabling Fetch Injection to work within WordPress. Initial testing shows Fetch Injection enables WordPress to load pages 300% faster than conventional methods.
Access the plugin beta Hyperdrive repo on GitHub and see the related Hacker Noon article for more details.
Playground
Try Fetch Inject on CodePen using the latest version available on CDN.
Reference the Use Cases to get a feel for what it can do.
Installing
Fetch Inject is available on NPM, Bower and CDN. It ships in the following flavors: IIFE, UMD and ES6.
- Get it on NPM with
npm i -p fetch-inject
- Bower with
bower i -p fetch-inject
- CDN using jsDelivr
To download the lastest minified UMD bundle from the command line:
curl -L -o fetch-inject.umd.min.js https://go.habd.as/fetch-inject-umd-min
See the Development section for asset pipelines requiring vanilla AMD and CJS modules.
Syntax
Promise<Array<Object>> fetchInject(inputs, promise)
Parameters
- inputs
- Required. This defines the resources you wish to fetch. It must be an
Array
containing elements of type USVString
or Request
.
- promise
- Optional. A
Promise
to await before injecting fetched resources.
Return value
A Promise that resolves to an Array
of Object
s. Each Object
contains a list of resolved properties of the Response Body used in the module, e.g.
[{
blob: { size: 44735, type: "application/javascript" },
text: "/*!↵ * Bootstrap v4.0.0-alpha.5 ... */"
}, {
blob: { size: 31000, type: "text/css" },
text: "/*!↵ * Font Awesome 4.7.0 ... */"
}]
Use Cases
Preventing Script Blocking
Problem:
External scripts can lead to jank or SPOF if not handled correctly.
Solution:
Load external scripts without blocking:
fetchInject([
'https://cdn.jsdelivr.net/popper.js/1.0.0-beta.3/popper.min.js'
])
This is a simple case to get you started. Don't worry, it gets better.
Loading Non-critical CSS
Problem:
PageSpeed Insights and Lighthouse ding you for loading unnecessary styles on initial render.
Solution:
Inline your critical CSS and load non-critical styles asynchronously:
<style></style>
<script>
fetchInject([
'/css/non-critical.css',
'https://cdn.jsdelivr.net/fontawesome/4.7.0/css/font-awesome.min.css'
])
</script>
Unlike loadCSS
, Fetch Inject is smaller, doesn't use callbacks and ships a minifed UMD build for interop with CommonJS.
Lazyloading Scripts
Problem:
You want to load a script in response to a user interaction without affecting your page load times.
Solution:
Create an event listener, respond to the event and then destroy the listener.
const el = document.querySelector('details summary')
el.onclick = (evt) => {
fetchInject([
'https://cdn.jsdelivr.net/smooth-scroll/10.2.1/smooth-scroll.min.js'
])
el.onclick = null
}
Here we are loading the smooth scroll polyfill when a user opens a details element, useful for displaying a collapsed and keyboard-friendly table of contents.
Responding to Asynchronous Scripts
Problem:
You need to perform a synchronous operation immediately after an asynchronous script is loaded.
Solution:
You could create a script
element and use the async
and onload
attributes. Or you could...
fetchInject([
'https://cdn.jsdelivr.net/momentjs/2.17.1/moment.min.js'
]).then(() => {
console.log(`Finish in less than ${moment().endOf('year').fromNow(true)}`)
})
Ordering Script Dependencies
Problem:
You have several scripts that depend on one another and you want to load them all asynchronously, in parallel, without causing race conditions.
Solution:
Pass fetchInject
to itself as a second argument, forming a promise recursion:
fetchInject([
'https://npmcdn.com/bootstrap@4.0.0-alpha.5/dist/js/bootstrap.min.js'
], fetchInject([
'https://cdn.jsdelivr.net/jquery/3.1.1/jquery.slim.min.js',
'https://npmcdn.com/tether@1.2.4/dist/js/tether.min.js'
]))
Managing Asynchronous Dependencies
Problem:
You want to load some dependencies which require some dependencies, which require some dependencies. You want it all in parallel, and you want it now.
Solution:
You could scatter some link
s into your document head, blocking initial page render, bloat your application bundle with scripts the user might not actually need. Or you could...
const tether = ['https://cdn.jsdelivr.net/tether/1.4.0/tether.min.js']
const drop = ['https://cdn.jsdelivr.net/drop/1.4.2/js/drop.min.js']
const tooltip = [
'https://cdn.jsdelivr.net/tooltip/1.2.0/tooltip.min.js',
'https://cdn.jsdelivr.net/tooltip/1.2.0/tooltip-theme-arrows.css'
]
fetchInject(tooltip, fetchInject(drop, fetchInject(tether)))
.then(() => {
new Tooltip({
target: document.querySelector('h1'),
content: "You moused over the first <b>H1</b>!",
classes: 'tooltip-theme-arrows',
position: 'bottom center'
})
})
What about jQuery dropdown menus? Sure why not...
fetchInject([
'/assets/js/main.js'
], fetchInject([
'/assets/js/vendor/superfish.min.js'
], fetchInject([
'/assets/js/vendor/jquery.transit.min.js',
'/assets/js/vendor/jquery.hoverIntent.js'
], fetchInject([
'/assets/js/vendor/jquery.min.js'
]))))
Loading and Handling Composite Libraries
Problem:
You want to deep link to gallery images using PhotoSwipe without slowing down your page.
Solution:
Download everything in parallel and instantiate when finished:
const container = document.querySelector('.pswp')
const items = JSON.parse({{ .Params.gallery.main | jsonify }})
fetchInject([
'/css/photoswipe.css',
'/css/default-skin/default-skin.css',
'/js/photoswipe.min.js',
'/js/photoswipe-ui-default.min.js'
]).then(() => {
const gallery = new PhotoSwipe(container, PhotoSwipeUI_Default, items)
gallery.init()
})
This example turns TOML into JSON, parses the object, downloads all of the PhotoSwipe goodies and then activates the PhotoSwipe gallery immediately when the interface is ready to be displayed.
Supported Browsers
All browsers with support for Fetch and Promises. Because Fetch is a newer Web standard, we will help identify, open and track issues against browser implementations as they arise while specs are being finalized.
Progressive Enhancement
You don't need to polyfill fetch for older browsers when they already know how to load external scripts. Give them a satisfactory fallback experience instead.
In your document head
get the async loading started right away if the browser supports it:
(function () {
if (!window.fetch) return;
fetchInject([
'/js/bootstrap.min.js'
], fetchInject([
'/js/jquery.slim.min.js',
'/js/tether.min.js'
]))
})()
Then, before the close of the document body
, provide the traditional experience to avoid blocking the parser until content is visible:
(function () {
if (window.fetch) return;
document.write('<script src="/js/bootstrap.min.js"><\/script>');
document.write('<script src="/js/jquery.slim.min.jss"><\/script>');
document.write('<script src="/js/tether.min.js"><\/script>');
})()
This is entirely optional, but a good practice unless you're going full hipster.
Development
- Clone the repo.
- Install dev dependencies.
- Execute
npm run
for a listing of available commands.
If you need vanilla AMD or CJS modules, update the NPM scripts in the package manifest and npm run build
.
Contributing
Please use Issues for bugs and enhancement requests only. Bug reports not accompanied by a reduced test case, sufficient backing research and information to help progress the library may be closed without explanation.
When submitting pull requests, use npm run commit
to create Commitizen-friendly commit messages. Pulls should be squashed into a single commit prior to review and should PR against a backing issue.
If you need support, you know where to go.
See Also
License