Dojo Foundation Packages

By on July 25, 2011 12:01 am

The Dojo Foundation was founded for the purpose of facilitating an active and open community of web technology, making high-quality code accessible to developers without constraint. The Dojo community has a history of commitment to the open web, with active involvement in many standards bodies and interoperability efforts, dedication to standards based approaches with the move to the AMD format and promises implementation, HTML5-based store API, data attributes, to-the-letter HTTP REST implementation, and more. The Dojo Foundation is working to further advance the open web with the introduction of a JavaScript package repository.

The new Dojo Foundation package repository provides a place for JavaScript packages to easily be registered (with github integration for automatic version syncing) and downloaded for use in web applications. You can also install packages using our new package installer, which you can use by downloading and install CPM (CommonJS Package Manager). Installation involves simply setting up the script to run from one of your bin path directories and point to the CPM directory. Then you can start installing packages:

cpm install dojo

This will automatically download and install the latest version and all necessary dependencies as packages into the current directory.

We can now use a compliant AMD module loader including Dojo and RequireJS to load modules from these packages. We could alternately install RequireJS with:

cpm install requirejs

Now the loader will download and be ready for use. In our page, we can load the script module loader to bootstrap the loading of the rest of our modules:

  <script src="/path/to/packages/dojo/dojo.js"></script>

Or we could do the same thing with RequireJS:

  <script src="/path/to/packages/requirejs/require.js"></script>

And that’s all we need to do get up and running with packages for your web application!

Installing Package Versions

The CPM also includes options for specifying specific package versions or downloading from URLs. For example, to download Dijit 1.6.1, we could do:

cpm install dijit 1.6.1

And again, this will download the version of the package specified and appropriate package dependencies (with the correct versions). As another example, to download the “master” version (the typical head in git), we could do:

cpm install dijit master

Packages may use nested directories for the JavaScript modules (in “lib” rather than being at the root). If the package is structured as such, the CPM automatically copies the lib directory contents to the package root to ensure that package modules can easily be referenced in <package>/<module> form.

Use the Packages with NPM/Node

This entire toolset is also open source and interoperable. The package repository is based on the CommonJS package specification and registry specification that was developed and is used by Isaac Schlueter for NPM (Node Package Manager). NPM and the package registry specification was designed for multiple registries, and the package repository fits into the distributed package registry model used by NPM. In fact, you can actually install packages from the package repository using the NPM. For example, if you have NPM installed, you can run:

npm install compose

This package is linked between the repositories, so NPM is automatically directed to the Dojo foundation repository when you run this command.

Replacing DojoX

The Dojo Toolkit has long used DojoX to house Dojo extensions. However, as DojoX has grown, it has become increasingly onerous to keep every sub-project within DojoX on the same release cycle as Dojo and Dijit. We also want the set of available extensions to be driven by a wider community of authors than just Dojo committers. Part of the motivation for the Dojo Foundation package repository is replacing DojoX for Dojo 2.0. While we will most likely continue to include DojoX in 1.x releases, all new projects and the latest releases of actively developed existing projects from DojoX will be available from the package repository.

If you have code that relies on a DojoX package and you want to use a release from the package repository, you can install the package into a specific location to match the DojoX namespace:

cpm install window-name 0.4 dojox/io

And this would install the window-name package into the dojox/io namespace (where it exists in DojoX).

Adding Packages

Adding packages to the package repository is extremely easy. Simply click on the submit link and provide the URL for your project. If it is a github project, the repository will automatically query for all the tags and branches in your project and make these available as versions through the repository. You never need to update or publish to the repository again, every time your package is requested, github will be re-queried for the latest tags and branches. You can even have your package auto-linked to the NPM registry if the package will run on Node by checking the NPM checkbox.

Packages follow the CommonJS package specification. We have a package template that makes a great starting point for developing a new package. Every package should include a package.json that describes it. The package repository will use your package.json information in the package listing.

This is an introduction to the Dojo Foundation package repository. This will hopefully give you a good start to leveraging this repository and easily adding packages to your web application. In the future, we will look at some of the exciting packages available in the package repository.

Other posts in the series