Dojo FAQ: Why is dojo.* unavailable when I set async: true in data-dojo-config?

By on January 29, 2014 10:35 am

The evolution of the Dojo Toolkit from namespaces to AMD packages has resulted in many changes over the years. In Dojo 1.x, we strive to maintain forwards-compatibility, while introducing new features and best practices in parallel. Mixing modern best practices and legacy code can lead to unexpected behavior.

One issue we see fairly often is setting async: true in the data-dojo-config property of Dojo’s script tag. This configuration setting tells Dojo to load resources as AMD modules using its asynchronous module loader. Many users choose this, but then rely on legacy package names such as dojo and dijit when migrating their old code. Unfortunately, this leads to failures when you try to use dojo.* statements within your application. This is a simple issue to identify and correct.

Setting async: true makes your application faster, but it will not load everything that used to be loaded with dojo.*. If you want true legacy behavior while using newer versions of Dojo, you should set async to false. To use more modern Dojo best practices, you should instead load the dependencies you need for your application, and update our source code to use AMD syntax.

This means that when using the loader in asynchronous mode, instead of using dojo.require("dojo.window") and calling dojo.window.getBox(), for example, we could use require to pull in the window module and reference it within the local scope:

], function (winUtils) {

The AMD syntax adds a lot of flexibility and portability to Dojo and JavaScript. It also works well with the Dojo build optimization process, and allows you to include exactly what you need in your initial page load. The asynchronous nature of AMD allows you to require modules when they are needed, to optimize bandwidth, HTTP requests, and memory consumption as needed for your application.

For more information on AMD, check out our AMD: the definitive source article.