Using The Dojo Build System To Speed Up Your ESRI JavaScript API Apps

[Updated 4-15-2013]
I've come up with a solution for ESRI JSAPI 3.4 and AMD.


As your JavaScript projects get more and more complex, loading all of those Dojo classes can really slow down your load time. All those dojo.require calls add up in a hurry. The Dojo Build System can be a huge help in speeding up the load time and general performance of your apps. For example, a build that I ran on a recent project took the number of JavaScript requests on page load from 53 down to 5. The css request went from 16 down to 4. This ended up cutting the load time in half! Other nice features include stripping out all of the console calls, minifying your JavaScript and interning all of your widget templates.

The rest of this post assumes some familiarity with the Dojo Build System. If you haven't looked at it before, the documentation is worth reading. There's even a fancy new tutorial.

After reading all of the Dojo documentation it's easy to get excited about the possibilities. However, you will quickly find that mixing the ESRI api into the equation makes a big mess of everything. For example, the dojo build system assumes that you are hosting everything yourself. But because ESRI has not released a source/unbuilt version of their api that we can download we are stuck loading Dojo from their servers. The other problem is that when you load the ESRI api you are really loading their layer file which can have a lot of overlap with your layer file thus adding a lot of duplicate code. Not to mention the problems that the build system has when it sees: dojo.require("esri..."); and it doesn't know where to get it. Over the last few months I've developed a solution to overcome these problems and end up with a lean and mean (for the most part) product in the end.


First, let's look at my project template. You can check it out on GitHub here. I keep separate folders for the source version ("src") and built version ("build"). This makes it easy to update our servers when I do a new build. I just checkout the "build" folder through SVN and update when needed. Something not shown is a local copy of the Dojo source code that I have downloaded. This contains the Dojo Build System (see "util\buildscripts"). I keep only one copy of the Dojo code on my local machine and use it for all of my projects. This is possible because I keep my build profile within a project folder in "buildsupportfiles". That way I never touch the Dojo source code which makes it easier to upgrade to new versions.


Now let's take a look at my build profile template ("build.profile.js"):

dependencies = {
    cssOptimize: "comments",
    optimize: "shrinksafe",
    layerOptimize: "shrinksafe",
    action: "clean,release",
    version: "1.6.1src",
    internStrings: true,
    mini: true,
    stripConsole: "all",
    releaseName: "PROJECTNAME/content",
    layers: [
        {
            name: "esriapi.discard",
            resourceName: "esriapi.discard",
            discard: true,
            dependencies: [
                "dijit.WidgetSet",
                "dojo.fx.Toggler",
                "dojo.Stateful",
                "dijit._WidgetBase",
                "dijit._Widget",
                "dijit._Templated",
                "dijit._Container",
                "dijit._CssStateMixin",
                "dijit.form._FormWidget",
                "dijit.form._FormValueWidget",
                "dojo.dnd.Mover",
                "dojo.dnd.Moveable",
                "dojo.dnd.move.constrainedMoveable",
                "dojo.dnd.move.boxConstrainedMoveable",
                "dojo.dnd.move.parentConstrainedMoveable",
                "dijit._HasDropDown",
                "dijit.form.Button",
                "dijit.form.DropDownButton",
                "dijit.form.ComboButton",
                "dijit.form.ToggleButton",
                "dijit.form.HorizontalSlider",
                "dijit.form._SliderMover",
                "dijit.form.VerticalSlider",
                "dijit.form.HorizontalRule",
                "dijit.form.VerticalRule",
                "dijit.form.HorizontalRuleLabels",
                "dijit.form.VerticalRuleLabels"
            ]
        },
        {
            name: "../PROJECTNAMELyr.js",
            resourceName: "PROJECTNAMELyr",
            layerDependencies: [
                "esriapi.discard"
            ],
            dependencies: [
                "js.core"
            ]
        }
    ],
    prefixes: [
        ["agrc", "../../../../REST/PROJECTNAME/src/content/agrc"],
        ["css", "../../../../REST/PROJECTNAME/src/content/css"],
        ["html", "../../../../REST/PROJECTNAME/src/content/html"],
        ["ijit", "../../../../REST/PROJECTNAME/src/content/ijit"],
        ["images", "../../../../REST/PROJECTNAME/src/content/images"],
        ["js", "../../../../REST/PROJECTNAME/src/content/js"]
    ]
}

The end goal of this profile (other than some optimized css files) is the "PROJECTNAMELyr.js" file. "js.core" is my main JavaScript file for the project and includes all of the necessary dojo.require(...) calls. The build system takes that file and combines all of the dojo classes that are referenced and rolls them up into one compressed file. This means that the browser only has to make one request and parse a single file.

I did encounter a problem the first time that I tried a build that included a dojo.require call for some esri classes (ie. dojo.require("esri.dijit.Legend");). Since I don't have a local, unbuilt version of the ESRI API, the build script chokes because it can't find the appropriate files. After a little digging around I was able to find a work-around. If you use dojo["require"]("esri.dijit.Legend"); then the build script will skip it and leave it alone. So the file does not get rolled into your layer file, but a least it can finish your build. Then when the layer file loads it will still load the ESRI classes via dojo.require.


The "esriapi.discard" layer makes sure that I don't include any dojo classes in my layer file that are already in ESRI's layer file. I found this list of classes by searching their layer file for "dojo.declare".

After my build is finished, I delete the dojo and dijit folders (those will be loaded via ESRI's servers), and copy everything else to my "build/content" directory. The only thing left to do is re-point my web page to load the layer file.

Sometimes after I re-point my page to the layer file, I get the following error message: "uncaught exception: Could not load cross-domain resources: dojo.nls._en-us". The nls is the localization stuff. Even though I do copy that folder into project, for some reason I still have a problem. I have a feeling that this is related to the fact that I'm loading my layer file from a different domain that Dojo is being loaded from. The office genius (@SteveAGRC) helped me with a solution for this problem. If you load the _en-us file manually before you load the layer file, then you don't get the error message. So my header looks like this:

<script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/?v=2.3"></script>
<script type="text/javascript" src="content/nls/PROJECTNAMELyr_en-us.js"></script>
<script type="text/javascript" src="content/PROJECTNAMELyr.js"></script>

In the end, the Dojo Build System has cut my page load times down significantly thus giving my users a better experience. If you are headed down a similar road I hope that this post can save you some time beating your head against the wall.

Another helpful post:
http://blog.geocortex.com/2009/05/12/build-your-jsapi-applications-for-performance/