Dojo version 1.6 and Asynchronous Loading

Notes about Dojo's use of the AMD Module Format

Rawld Gill

This document was generated 2011-02-2717:44:26.


This article summaries Dojo's move to CommonJS Modules/AsynchronousDefinition(AMD)-compliant format which has started as of version 1.6.

When moving a general purpose library like Dojo from a synchronous design to an asynchronous design, several problems must be solved:

  1. [done] Change the expression of individual modules to the AMD format.

  2. [done] Provide a way to get back the dojo.require/dojo.provide module for back compat; this is accomplished by doing a build.

  3. [done] Update the bootstrap and synchronous loader to support the AMD format.

  4. [not done] Remove any assumptions of global variables (e.g., global dojo or dijit) in the library. For most of Dojo, this is no problem; however, some parts (e.g., the parser) and many usages on html pages assume global dojo/dijit.

  5. [not done] Update all the tests to test both synchronous and asynchronous versions.

  6. [not part of dojo] Provide an AMD-compliant loader; both bdLoad and RequireJS can be used, but neither is a part of Dojo as of 1.6

  7. [not part of dojo] Provide a system to "build" release versions. The word "build" seems to be interchangeable with "optimize" today. Both bdBuild and RequireJS's optimizer are available for this.

The move to the AMD module format in v1.6 is preparatory; full support of AMD module loading will come in v1.7 and v2.0. This is to say that Dojo does not officially support asynchronous module loading and as of v1.6 this is considered experimental (some things may change in subsequent versions). For support with asynchronous loading, consult your loader vendor (see below).

Some Dojo user's have built applications that depend on dojo.require and dojo.provide (for example, server-side dynamic loading). Care has been taken to ensure the build utility can transform the dojo and dijit modules back to the dojo.require/dojo.provide format. If you are a user that needs dojo modules expressed in terms of dojo.require/dojo.provide and are using the source distribution, execute a build and you will see the modules restored to the synchronous format. You can use the following build switches to get modules that look like source modules:

./ action=release mini=false addGuards=false internStrings=false profile=profile

Execute this from the directory util/buildscripts within the source release tree. Note that you'll need to substitute the appropriate build profile for profile. If you want to build the entire Dojo toolkit library, you can use the demos-all profile (this is what we use for the nightly build). To just get dojo and dijit, you could use the following:

dependencies = {
  prefixes: [
    [ "dijit", "../dijit" ]

Warning: the processes that transform v1.6 dojo/dijit modules back to their synchronous equivalents are not generalized and are not intended to convert random AMD modules into equivalent modules that use dojo.require and dojo.provide. This will be addressed with a new build system in v1.7. Build tool limitations are tracked at; see comment #9 in particular.

There are two AMD-compliant loaders known to work with Dojo:

The source release of the toolkit includes proof-of-concept tests of loading dojo with bdLoad and RequireJS at dojo/tests/amd/smoke-bdLoad.html and dojo/test/amd/smoke-requirejs.html. These tests assume the source release of Dojo is in the directory dojotoolkit, and bdLoad and RequireJS are each installed in siblings to dojotoolkit.

Regarding stability:

  • dojo 1.6 has been tested fairly deeply with bdLoad (by me, at least). Unless you are doing something extreme, you should have no problems with this.

  • dijit 1.6 has been tested lightly with bdLoad (be me, at least). As long as you keep dojo and dijit global, dijit should work for you.

  • dojox support is variable. If you see define statements, it will likely work, and conversely.

Kris Zyp has another nice article on this topic at