Best practice for documenting javascript library dependencies

Question

So you're creating a bunch of code in an external .js file that requires jQuery and a few of its plugins, or MooTools, or perhaps some more esoteric libraries. Obviously the actual "include" is done in the host HTML page in the HEAD section as you load in each script.

But as a best practice for portability, what built-in features, or widely-adopted conventions exist within your JavaScript .js file to ensure that the next schmoe who uses your code remembers to also include those other required libraries?

I'm looking for some consensus from the developer community, so please be sure to vote for the answer that seems most common or that you are the most familiar with.

Answer 1

jQuery UI adds the dependencies of their widgets in the file header:

/*
* jQuery UI Effects Bounce @VERSION
*
* Copyright 2011, AUTHORS.txt (http://jqueryui.com/about)
* Dual licensed under the MIT or GPL Version 2 licenses.
* http://jquery.org/license
*
* http://docs.jquery.com/UI/Effects/Bounce
*
* Depends:
* jquery.effects.core.js
*/

Now unfortunately JavaScript dependency managers are used way less than they should, but if you can make your libraries users switch to one you wouldn't have to worry about that at all:

• StealJS
• Jingo
• YUI loader
• Pyramid Dependency Manager

Checking explicitly might be a good idea, too, since you can dynamically react if certain plugins are or are not available (e.g. either throw an exception if the jQuery UI dialog hasn't been found or just degrade gracefully and show a simple modal window):

if(!$.isFunction($.fn.dialog)) {
    throw "Could not find jQueryUI dialog. Please include jQuery UI";
}

That way your script doesn't have to break entirely if an optional dependency is not met.

Answer 2

For the Visual Studio developers out there you may want to try blocks like these in your header

/// <reference path="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.6-vsdoc.js" />
/// <reference path="thirdparty/ba-debug.js" />
/// <reference path="thirdparty/underscore.js" />

While this doesn't resolve your dependencies, it does document them, AND it gives you intellisense in Visual Studio...

See http://msdn.microsoft.com/en-us/library/bb385682.aspx, then look for References Directives (no a name or id to link directly to, sorry...)

Answer 3

my js headers look like this:

////////////////////////////////////////////////////////////////////////////////
//
//  src:        www.someDomain.com/js/modules/etc
//  author:     someguy
//  date:       6-22-11
//  intent:     what is the purpose / use of this module
//  package:    prototype parent
//  requires:   jquery.1.4.js
//              fancybox
//              etc
//
////////////////////////////////////////////////////////////////////////////////

Any dependencies are then quite clear to anyone on my team, and this has proven pretty reliable. As a (hopefully) secondary measure, I will always test for those dependencies at runtime and throw up an alert should a script not be included.