AMD offers many benefits over the legacy Dojo module syntax. While Dojo is forwards-compatible, to take advantage of the benefits of AMD, developers are often faced with the challenge of migrating and refactoring large quantities of boilerplate code from the legacy dojo.provide/dojo.require syntax to AMD’s define and require. As we make the upgrade to AMD in our projects, we also usually want to leverage the latest version of our evolving APIs. With early work beginning on Dojo 2.0, we definitely need to work together as a community to automate as much of the upgrade process as possible.

Introducing the dojo-amd-converter

We have created an alpha quality release of dojo-amd-converter, a tool for helping you make a one-time migration of your existing source code to a newer version of Dojo.

Be warned, the tool handles only 70-80% of the manual conversion process, and generally does better with more standard usage of Dojo. Normally we wait a bit longer before announcing our projects, but this should be useful in its early alpha state. We know this tool has quite a few open issues that need to be fixed and we invite you to help us improve it.

Our hope is that this conversion tool, which is today useful for converting pre-AMD code to AMD code, could also form the basis for a community effort to make it possible to migrate code bases more efficiently from Dojo 1.x (pre-AMD or AMD) to Dojo 2.x. That work has not yet started, since Dojo 2.0 is not yet an actual thing.

What does it do?

Based on a collection of rules, and leveraging Node.js, libxml.js, and esprima, the parser will take an existing Dojo source tree, and convert the following:

  • non-AMD modules to AMD modules
  • namespace references to module references
  • legacy HTML custom attributes to HTML5 compliant data-dojo-*
  • legacy i18n bundles to AMD bundles
  • older Dojo APIs to their refined replacements

For example, if before conversion you had a file like this:

dojo.provide("my.namespace.i18n.Bundle");
dojo.requireLocalization("dijit", "common");
dojo.requireLocalization("foo.package", "Bundle");
dojo.requireLocalization("bar.package", "Bundle2");

var foo = dojo.i18n.getLocalization("foo.package", "Bundle"),
	bar = dojo.i18n.getLocalization("bar.package", "Bundle2", foo.bar),
	baz = {
		locale: "en-lol",
		i18n: dojo.i18n.getLocalization("bar.package", "Bundle2", this.locale)
	};

You would end up with this, after conversion:

define([
	"dojo",
	"dojo/i18n",
	"dojo/i18n!bar/package/nls/Bundle2",
	"dojo/i18n!dijit/nls/common",
	"dojo/i18n!foo/package/nls/Bundle"
], function (dojo, i18n, i18nBundle2, i18ncommon, i18nBundle) {

	var foo = i18nBundle,
		bar = i18n.getLocalization("bar.package", "Bundle2", foo.bar),
		baz = {
			locale: "en-lol",
			i18n: i18n.getLocalization("bar.package", "Bundle2", this.locale)
		};
});

Usage

To use the dojo-amd-converter, Mac and Linux users should follow these simple steps:

  1. Clone the repo using Git:
    git clone --recursive https://github.com/SitePen/dojo-amd-converter.git
  2. Modify the provided config.js file to specify some basic settings for your application, such as your source and destination directories.
  3. From within the repo, run the provided shell script on your configuration file:
    ./parse.sh config.js
If you receive a permission denied error, you may need to chmod the shell script:

chmod +x parse.sh

config.js options

  • excludePaths – An array of paths that will be excluded from processing. Each path should be a regular expression
  • srcDir – Root directory of the files to process.
  • distDir – Output directory of the processed files.
  • printOutput – Print output instead of sending it to the output directory.
  • makeDeclareAnonymous – Make declare calls anonymous instead of leaving the first argument as-is. This will avoid creating any global variables with declare.
  • removeUnusedDependencies – Remove dependencies that are not referenced in a converted module.
  • onlyProcessTemplates – Only process HTML files inside template directories.

The AMD converter does not currently work on Windows, due to the dependency on libxmljs.

Getting Involved

This project is in the early stages, and our hope is that it will also be used for work to convert to Dojo 2.0. We have many open issues for items we have already identified in our work using this tool. The dojo-amd-converter tool is licensed under the same terms and conditions as other Dojo Foundation projects.

To get involved, you will need to have a Dojo Foundation CLA on file for us to consider your code change. Please get involved if this tool is of interest to you now or in the future, as we think it is a much needed improvement for making it easier to upgrade between Dojo releases.