Jingo provides similar functionality to the "import" features of Java and Python.

If you'd like to skip the prose and go straight to the code you may want to try GettingStarted or the Jingo API Documentation.

The Pains of Modular JavaScript

Modular JavaScript architectures can be extremely difficult to maintain. Within each page, developers are forced to load all direct and transitive dependencies by hard-coding a script tag for each module in transitive dependency order. Developer reactions to this nightmare generally lead to one of two approaches. One approach is to cram nearly all JavaScript code for a given project into a single file in order to reduce the number of scripts that need to be managed. Another common approach is to manage the list of all known script tags in an external resource that is dynamically included in the page via a templating system. All modules are then loaded for every page whether they are needed or not. Both of these approaches have severe drawbacks and scale very poorly to the larger systems being written in JavaScript today.

In contrast, other platforms such as Python and Java manage modular architectures quite gracefully and, as a result, scale well to larger, more complex systems. In the past, JavaScript was called upon for rather small tasks within limited contexts. With the current industry push toward Web 2.0 and Rich Internet Applications (RIA), this no longer holds true - leaving the JavaScript community with some catching up to do in the area of dependency management.

First-Generation Solutions

Jingo is by no means the first solution to the JavaScript dependency management problem. However, other solutions are often delivered in the context of a catch-all framework that requires a larger commitment. We also believe that the two main approaches common at the time of this writing suffer from significant drawbacks, as first-generation solutions often do. We'll call these approaches "Script Tag Append" and "Ajax and Eval".

• Script Tag Append: In this approach, the dependency name is passed through a mapping strategy to derive a URL for the required JavaScript source file. Then a <script> tag with its src attribute set to the derived URL is appended to the Document Object Model (DOM). This approach is extremely simple, ties into typical browser caching strategies and maintains the association between a script's source and the file it originated from. The unfortunate drawback of this approach is that scripts are loaded asynchronously and transitive dependency load order cannot be maintained.

• Ajax and Eval: The first step of this approach is identical to Script Tag Append. However, the resource identified by the derived URL is retrieved in a very different way - a synchronous XML HTTP Request (XHR) call is used to download the script's source code into a JavaScript string. The string is then passed to a window.eval() call. The synchronous nature of script loading and evaluation means it can enforce transitive dependency load order while the use of the XHR ensures standard browser caching behavior. However, unlike Script Tag Append, this approach attributes the newly loaded source to the script that called window.eval() rather than the actual file resource it was loaded from. This behavior severely handicaps most JavaScript debugging tools.

Jingo, A New Approach

In our opinion, the framework bias and technical limitations of current approaches to JavaScipt dependency management are deal breakers. Script Tag Append is able to properly attribute source code to its file resource, which keeps crucial tools like Firebug working for us, but Ajax and Eval guarantees dependency order. Why can't we have our cake and eat it too? Jingo was created with the goal of learning from both approaches and delivering the best of both in a single, lightweight, framework-agnostic package. We think we've succeeded in doing so, and we hope your project will benefit from the fruits of our labor.