Load big web applications quickly with a custom Dojo build

Learn how a custom Dojo build can reduce the overall JavaScript footprint of your large applications. This article uses an example web project to walk you through the prerequisites, the build profile, optimization, and buildscripts.


Poornima Anantharaman, Staff Software Engineer, IBM

Photo of Poornima AnantharamanPoornima Anantharaman, a staff software engineer, is a Java/J2EE and web developer with eight years of experience. She is currently focused on the console development of the eDiscovery Manager product under ECM/IM.

Swetha Kunche, Software Developer, IBM

Photo of Swetha KuncheSwetha Kunche is a Sun Certified Web Component Developer for Java programming. She has worked for IBM for five years and is currently with the eDiscovery Manager team. Her areas of interest include Java and Web 2.0 technologies.

29 March 2011

Also available in Japanese


Develop skills on this topic

This content is part of a progressive knowledge path for advancing your skills. See Get started with Dojo development

When might you need a Dojo build? How about when the application is huge and uses a lot of widgets? Or when large widgets are frequently requested from the server using dojo.require statements? In these instances, a Dojo build can come in handy. If you're dealing with small files for a small application, however, a Dojo build would be overkill.

To increase the speed of the page load in a web application, you need to reduce the number of synchronous requests to the server to load the required files. The size of the file also matters. Based on the file size, number of files, and usage frequency of the JavaScript files, you can decide whether a build is required. If so, you define the files to be loaded in the first go as well as the files to be stored in the cache.

A Dojo build:

  • Puts multiple JavaScript modules together into a single JavaScript file called a layer.
  • Picks up the template for rendering from the HTML file associated with a widget and adds it to the templateString attribute in the JavaScript file of the widget.

The layer file is then compressed using ShrinkSafe, a JavaScript-based compressor. The Dojo build reduces the overall JavaScript footprint of a huge web application. Figure 1 shows a server request pattern from a web page without the use of layers.

Figure 1. Requests from a web page without use of layers
Picture of a web page with 7 arrows pointing to and from a box representing the server.

Figure 2 shows the server request pattern from a web page using layers.

Figure 2. Requests from a web page using layers
Picture of a web page with 2 arrows pointing to and from a box representing the server.

In this article, learn how to do a build of a sample web application. The example uses Rational® Application Developer (Application Developer) for the integrated development environment (IDE). However, you can achieve the same result with any other IDE or through the command prompt.

You can download the sample web project and build the profile used in this article.

The terms "Dojo build" and "Dojo custom build" are used interchangeably in this article.

Prerequisites for a custom Dojo build

For a custom Dojo build, you will need:

  • A web application with all the custom widgets and other JavaScript files.
  • The Dojo SDK (see Resources). Build tools are not included in the Dojo official release; use the Dojo SDK version 1.5 to do the custom build.
  • A build profile.
  • Apache Ant. You don't have to download Ant if the build is done through Application Developer or Eclipse. If the build is done with the command prompt, ant.jar must be set to the classpath.

Sample application

The sample application includes a custom widget for a JSP and rendering. It's simple, yet has most of the important components of a web application. The sample application contains:

  • A simple custom widget (Hey) that has some styled text (Hey.js, Hey.html).
  • A simple JavaScript file with initialization code (helloworld.js).
  • A JSP file to include the custom widget and render it (index.jsp).
  • A CSS file for styling (Hey.css).
  • A JavaScript file with messages for localization (messages.js).
  • A Build profile (custombuild.profile.js).
  • An Ant script to run the build (build.xml).

The positioning of the files for the sample web application is shown in Figure 3.

Figure 3. Sample application components
Directory structure showing the files for the sample application.

Build profile

Most pages in the web application require that certain JavaScripts download during the page load. As mentioned, it's good to optimize the number of requests to the server and download the required files in a single step. With the build profile, all the files or resources that must be downloaded in a single synchronous request are consolidated into a single JavaScript file, which can be included directly at the head of the page. The general rule is to have one layer for each page or one layer for files that are used on most pages.

The profile file is a configuration file that specifies what goes into each layer, and it contains a JSON object. Each of the widgets mentioned in the layer are files that would otherwise be downloaded using explicit dojo.require statements. Listing 1 shows the profile file used in the sample web application.

Listing 1. Sample profile file
dependencies = {
layers: [
		name: "../customjs/customhelloworld.js",
		name: "../customjs/customjs.js",


prefixes: [
		[ "dijit", "../dijit" ],
		[ "dojox", "../dojox" ],
		[ "customjs", "../customjs" ],

Each entry under prefixes is a mapping of a relative path to a module. The modules are used in the layer definitions, and their path is resolved based on the prefix.

In the custom build profile, custom.js and customhelloworld.js are layers. Both of these layers include the dependencies or the JavaScripts that are loaded when the layer or module is included in a page. For example, when custom.js is included in a page, the dependent widgets are dijit.form.button and customjs.widgets. Hey gets downloaded in one synchronous request.

Layer dependencies indicate the other layers that the particular layer is dependent on (indicating that before loading this layer, the dependent layers have to be loaded). For example, the customjs.js layer has a dependency on the layer customhelloworld.js.

The profile file should be placed under the util/buildscripts/profiles directory of the Dojo directory path, as shown in Figure 4.

Figure 4. Custom build profile
Directory structure showing util/buildscripts/profiles/custombuild.profile.js.

Creating build scripts for a custom Dojo build in Application Developer

The build script is essentially an Ant script that can be run from any convenient location—the IDE or command prompt. The build script:

  1. Cleans up all the build-related folders.
  2. Copies the latest version of Dojo from a specified folder into the build folder.
  3. Copies all the application-related widgets and JavaScript files into the build folder.
  4. Uses the details in the profile file to run the custom build and generate the custom release.

In this example, the build folder refers to the common location where all the files to be built reside. The Dojo files are also copied into the build folder.

Listing 2 shows the target for copying all the Dojo files into the build folder.

Listing 2. Target for copying Dojo files into the build folder
<target name="copy_dojo_toolkit" unless="dojo.upToDate">
	<!-- Clean the dojo directories -->
	<antcall target="clean_dojo" inheritAll="yes" />
	<copy todir="./dojo">
		<fileset dir=”../dojo-release-1.5.0-src/dojo-release-1.5.0-src/dojo">
			<exclude name="**/.copyarea.db"/>
	<copy todir="./dijit">
		<fileset dir=”../dojo-release-1.5.0-src/dojo-release-1.5.0-src/dijit">
			<exclude name="**/.copyarea.db"/>
	<copy todir="./dojox">
		<fileset dir="../dojo-release-1.5.0-src/dojo-release-1.5.0-src/dojox">
			<exclude name="**/.copyarea.db"/>
	<copy todir="./util">
		<fileset dir="../dojo-release-1.5.0-src/dojo-release-1.5.0-src/util">
			<exclude name="**/.copyarea.db"/>

Listing 3 shows the target for copying all the application-related files into the build folder and running the custom build with the specified arguments. The build program is controlled by the command line arguments.

Listing 3. Target with build command
<target name="do_custom_dojo_build" unless="custombuild.upToDate">
	<copy todir="../customjs/nls">
		<fileset dir="../resource/i18n/nls">
			<exclude name="**/.copyarea.db"/>
	<echo level="info" message="Copy the custom files and widgets" />
	<copy todir="./customjs">
		<fileset dir="../customjs">
			<exclude name="**/.copyarea.db"/>
	<!--Copy the profile file-->
	<copy todir="./util/buildscripts/profiles">
		<fileset file="../dojo-release-1.5.0-src/dojo-release-1.5.0-
	<echo level="info" message="Creating dojo custom build ..." />
	<java  classname="org.mozilla.javascript.tools.shell.Main"  
		<arg value="build.js" />
		<arg value="action=release" />
		<arg value="profile=custombuild" />
		<arg value="optimize=shrinksafe" />
		<arg value="releaseName=myDojo" />
		<arg value="version=0.1.0" />
		<arg value="releaseDir=../../../myDojo/" />
			<pathelement location="util/shrinksafe/shrinksafe.jar"/>
			<pathelement location="util/shrinksafe/js.jar"/>
	<echo level="info" message=" dojo custom build complete ..." />

The first argument goes in without a name value pair. It specifies the main build file for Dojo (build.js), which is located under the util/buildscripts directory. Other arguments include:

Specifies the task to be done by the build. The three possible values are: release (builds a release), clean (cleans up all the build folders), and help (prints the help message from the build.js file).
Specifies the name of the profile file that has to be used for the build. For a profile file named custombuild.profile.js, the argument value would be custombuild. By default, profile files are placed in the folder util/buildscripts/profiles.

For the file name to be mentioned as a command line argument, the name profileFile is used and the file name has a path relative to util/buildscripts.

The custom name for the custom Dojo release. It is dojo by default. After the build is complete, all the built files are placed in a folder with the specified releaseName.
The version of the build being done.
Specifies the path for the build/release folder.

All the paths mentioned in the build command arguments are relative to the path mentioned in the dir argument of the java tag.


Optimizing the layers is one of the main steps in the Dojo build process. The layers are compressed by the Dojo build, creating both compressed and uncompressed versions of the whole package, reducing the JavaScript footprint even further. The uncompressed resource has the suffix uncompressed.js and can be used for debugging. For example, in the sample application the compressed and uncompressed versions of the customjs.js layer are customjs.js and customjs.js.uncompressed.js, respectively.

As shown in Listing 4, the optimize argument of the build command has the value Shrinksafe. Shrinksafe, a Dojo-Rhino compressor used for optimization, compresses the files by removing white spaces, comments, and shortening variable names. No decompression is required when the files have to be used in the application.

Listing 4. Optimization argument for build command
<arg value="optimize=shrinksafe" />

Custom output

After the build is complete, the release directory contains all the built files, as shown in Figure 5.

Figure 5. Custom build output
Directory structure with 5 files under the widgets subdirectory.

The Dojo build has created custom, consolidated, and compressed layers of JavaScript that you can use in the sample web application, as shown in Listing 5.

Listing 5. Built layer included in a web application
<script type="text/javascript"  src= "myDojo/release/dojo/customjs/customhelloworld.js">
<script type="text/javascript" src="myDojo/release/dojo/customjs/customjs.js">

All the paths in the build.xml file are relative to the location of the build.xml file, with the exception of paths mentioned for the build command. All paths in the profile file are relative to the location of the profile file.


Sample Web projectsample_web_application.zip6129KB
Build profilecustombuild_profile.zip1KB
Sample web project set up instructionsSet_up_instructions.zip4KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Web development on developerWorks

Zone=Web development
ArticleTitle=Load big web applications quickly with a custom Dojo build