Dojo provides many settings to configure the optimal loading and building of your application source code. We are often asked about the differences between packages, paths, and aliases.

Here we provide a quick explanation showing common use cases for each.

aliases

aliases provide shortcuts to existing modules. You’ll want to use this if you’re looking to provide an easy way to access modules that may have longer paths.

dojoConfig:

var dojoConfig = {
	aliases: [
		["ready", "dojo/domReady"]
	]
};

The dojoConfig property accepts an array of arrays. The subarray should contain first the alias and then the module to which the alias will reference.

require:

require(["ready!"], function () {
	console.log("The DOM is ready!");
});

In this example, we set “ready” as an alias to the dojo/domReady module.

paths

paths register an alias to a path. You will want to use this if you need to map a directory to an alias.

dojoConfig:

var dojoConfig = {
	paths: {
		demo: location.href + "demo"
	}
};

The dojoConfig property accepts an object of key/value pairs. The key is your abbreviated path name, and the value is the full location of the path. By default, the location will be relative to baseUrl, or an absolute path can also be used.

require:

require(["demo/myModule"], function (myModule) {
	console.log(myModule.someProperty);
});

Here, we require the “myModule” module. We use the demo path we set up to point to the location of that module.

packages

packages are similar to paths, and they allow you to specify a main property, telling the loader which module to load as a default when this package is included in your application.

dojoConfig:

var dojoConfig = {
	packages: [
		{
			name: "demo",
			location: location.href + "demo",
			main: "myModule"
		}
	]
};

The dojoConfig property accepts an array of objects. Each object represents the configuration for a single package. Each object has three commonly used properties, name, location, and an optional main.

  • name is the package name that you will reference when you want to require the package within other modules
  • location is the path relative to baseUrl, or an absolute path
  • main is an optional property that is the name of the module that will be automatically returned

require:

require(["demo"], function (myModule) {
	console.log(myModule.someProperty);
});

In this require, we did not provide a module name, so myModule was returned. Specifying demo/myModule in the dependency list would have had the same result.

In most scenarios, you should use packages. When creating a custom Dojo build to optimize your application, you will find additional options such as renaming packages on the fly and defining alternative destination locations for a package.

The paths and aliases properties do allow for some powerful changes on the fly, and can be used to create some interesting loader configuration, especially in testing and debugging. However, really, the better option in newer versions of Dojo is the map property, which we’ll cover in the next FAQ!

As you can see, The Dojo Toolkit provides powerful options for configuring its loader when the default options do not match your application file structure and preferred naming conventions, or when you need to use multiple versions of a package that share the same name within your app.