README.md

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

Using a popular library?

Or perhaps one of these lesser-known packages?

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 of correct behavior, which has been adopted in the production-ready little-loader module.

🏆 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. 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 far too clever and still incorrect.

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
HeadJS
jQuery
LABjs
RequireJS
yepnope
getscript
kist-loader
load-script
loads-js
script-load
$script.js
scriptload
YUI