Skip to content

Latest commit

 

History

History
218 lines (184 loc) · 13.3 KB

README.md

File metadata and controls

218 lines (184 loc) · 13.3 KB

Build Status

Your script loader probably doesn’t have the callback behavior you want.

Using a popular library?

curl.js Status HeadJS Status jQuery Status LABjs Status RequireJS Status $script.js Status yepnope Status YUI Status

Or perhaps one of these lesser-known packages?

getscript Status JSL Status kist-loader Status l.js Status LazyLoad Status load-script Status loadrunner Status loads-js Status NBL Status script-load Status scriptinclude Status scriptload Status toast Status

Sorry.

Introducing…

script-atomic-onload

A build matrix of every script loader ever made.

This project tests script loaders for atomic onload support, which is the only correct behavior. It also contains a reference implementation, which has been adopted in the production-ready little-loader module.

little-loader Status

🏆 little-loader is the only correct script loader ever made.

The only correct behavior…

Yes, calling onload immediately (aka synchronously or atomically) after a <script> has executed is the correct and officially defined behavior. So what’s the problem? Internet Explorer. Below version 10, getting this behavior requires you jump through some hoops. Even if you don’t support Internet Explorer, your script loader may be breaking your code in compliant browsers due to its faulty onload workarounds. Some script loaders just don’t try; for example, jQuery’s getScript does not make this guarantee, documenting that “The callback is fired once the script has been loaded but not necessarily executed.” Those that do try often try very hard and end up being too clever and still incorrect. In giving IE a pass on this behavior, many loaders have left other browsers broken as well.

If you haven’t designed for it by bundling all your code or using a system like AMD, having other code run in between your script and its onload callback can be potentially disastrous. For instance, let’s say you make a widget people can load on their site, and it relies on jQuery. You want to load jQuery from a CDN. But since your widget might be used on sites that already use jQuery, you need to use jQuery.noConflict to keep yours isolated. When you load your version of jQuery in IE, it’s possible other code on the page can see it before your onload callback fires. Any code can then modify your instance of jQuery, adding plugins and such (most likely mistaking it for a different instance of jQuery). Eventually your noConflict gets called, but it’s too late – the plugins are attached to the wrong jQuery instance. This is not a problem with jQuery, but with the script loader.

This particular implementation may not be widely adopted, but it has been battle-tested on many high-traffic, script-laden sites in production. Just because you’ve never had an issue with your script loader, doesn’t mean it’s correct! One particular issue that this loader resolved was only ever seen on one site, and only sometimes (when certain race conditions were triggered).

Reference Implementation

Install

npm install script-atomic-onload

Usage

loadScript(src[, callback, thisValue])

Arguments:

  • src: The URL of the script to load.
  • callback: The function to call immediately after the script has executed. It will be called with no arguments, but we reserve the right to pass an err parameter in future versions. (Load errors can be difficult to detect on cross-domain scripts in older versions of IE anyway.)
  • thisValue: The this value that your callback will receive.

Examples

var loadScript = require("script-atomic-onload");

loadScript("https://code.jquery.com/jquery-1.11.3.min.js", function() {
  var jQuery = window.jQuery.noConflict(true);
  // We’re guaranteed to have an instance of jQuery that no other script on the
  // page has extended or modified.
});

I don’t support old IE anyway, am I safe?

Maybe! Have a look at the results from our build matrix:

Library Browser Status
🏆 little-loader little-loader Browser Status
curl.js curl.js Browser Status
HeadJS HeadJS Browser Status
jQuery jQuery Browser Status
LABjs LABjs Browser Status
RequireJS RequireJS Browser Status
$script.js $script.js Browser Status
yepnope yepnope Browser Status
YUI YUI Browser Status
getscript getscript Browser Status
JSL JSL Browser Status
kist-loader kist-loader Browser Status
l.js l.js Browser Status
LazyLoad LazyLoad Browser Status
load-script load-script Browser Status
loadrunner loadrunner Browser Status
loads-js loads-js Browser Status
NBL NBL Browser Status
script-load script-load Browser Status
scriptinclude scriptinclude Browser Status
scriptload scriptload Browser Status
toast toast Browser Status