From CommonJS Spec Wiki
Jump to: navigation, search


Asynchronous Package Definition

This specification describes how to define the contents of a CommonJS package with an asynchronous API, specifically to facilitate loading packages in a browser. Given the URL of a package, regardless of the domain of the package (whether it be the same as the requested page or not) a client side browser-based loader should be able to load the metadata of the package and modules within that package based on a module id within the package.


A package that is intended to be available for client side usage and complies with this specification SHOULD provide a "package.js" resource at the root URL of the package. This module SHOULD provide the client with package metadata by calling the define.package function. A package.js resource, as well as any other JavaScript resource in the package, may call define(), as defined by the Asynchronous Module Definition [1] specification or Modules Transport [2] specification to register modules (package.js may include module definitions in order to avoid multiple requests). However, the define.package call SHOULD proceed any define() calls.


The define.package function must take a single argument that is a JavaScript object that corresponds to the package metadata. The properties of the package metadata object should follow the CommonJS package specification.


A package.js could include:

   name: "foo",
   description: "some package"

Any define() calls that exist in the package.js after the define.package must use provide module ids (they can not be anonymous, without their first parameter) to identify themselves.