CommonJS is the underlying infrastructure for both the SDK and the add-ons you build using the SDK. A CommonJS module is a piece of reusable JavaScript: it exports certain objects which are thus made available to dependent code. CommonJS defines:
- an object called
exports
which contains all the objects which a CommonJS module wants to make available to other modules - a function called
require
which a module can use to import theexports
object of another module.
Except for scripts that interact directly with web content, all the JavaScript code you'll write or use when developing add-ons using the SDK is part of a CommonJS module, including:
- SDK modules: the JavaScript modules which the SDK provides, such as
panel
andpage-mod
. - Local modules: each of the JavaScript files under your add-on's "lib" directory.
- External modules: reusable modules developed and maintained outside the SDK, but usable by SDK-based add-ons.
SDK Modules
The modules supplied by the SDK are divided into two sorts:
- High-level modules like
panel
andpage-mod
provide relatively simple, stable APIs for the most common add-on development tasks. - Low-level modules like
heritage
andnamespace
provide more powerful functionality, and are typically less stable and more complex.
To use SDK modules, you can pass require()
a complete path, starting with "sdk", to the module you want to use. For high-level modules this is just sdk/<module_name>
, and for low-level modules it is sdk/<path_to_module>/<module_name>
:
// load the high-level "tabs" module var tabs = require("sdk/tabs"); // load the low-level "uuid" module var uuid = require('sdk/util/uuid');
The path to specify for a low-level module is given along with the module name itself in the title of the module's documentation page (for example, system/environment).
Although the SDK repository in GitHub includes copies of these modules, they are built into Firefox and by default, when you run or build an add-on using jpm run
or jpm xpi
, it is the versions of the modules in Firefox that are used. If you need to use a different version of the modules, you can do this by checking out the version of the SDK that you need and passing the -o
or --overload
option to jpm run
or jpm xpi
.
Local Modules
At a minimum, an SDK-based add-on consists of a single module named main.js
, but you can factor your add-on's code into a collection of separate CommonJS modules. Each module is a separate file stored under your add-on's "lib" directory, and exports the objects you want to make available to other modules in your add-on. See the tutorial on creating reusable modules for more details.
To import a local module, specify a path relative to the importing module.
For example, the following add-on contains an additional module directly under "lib", and other modules under subdirectories of "lib":
- my-addon
- lib
- main.js
- password-dialog.js
- secrets
- hash.js
- storage
- password-store.js
- lib
To import modules into main
:
// main.js code var dialog = require("./password-dialog"); var hash = require("./secrets/hash");
To import modules into password-store
:
// password-store.js code var dialog = require("../password-dialog"); var hash = require("../secrets/hash");
External Modules
As well as using the SDK's modules and writing your own, you can use modules that have been developed outside the SDK and made available to other add-on authors.
There's a list of these "community-developed modules" in the SDK's GitHub Wiki, and to learn how to use them, see the tutorial on using external modules to add menu items to Firefox.
To import external modules, treat them like local modules: copy them somewhere under your add-ons "lib" directory and reference them with a path relative to the importing module.
For example, this add-on places external modules in a "dependencies" directory:
- my-addon
- lib
- main.js
- dependencies
- geolocation.js
- lib
It can then load them in the same way it would load a local module. For example, to load from main
:
// main.js code var geo = require("./dependencies/geolocation");
Freezing
The SDK freezes the exports
object returned by require
. So a if you import a module using require
, you can't change the properties of the object returned:
self = require("sdk/self"); // Attempting to define a new property // will fail, or throw an exception in strict mode self.foo = 1; // Attempting to modify an existing property // will fail, or throw an exception in strict mode self.data = "foo";
Using modules from outside the Add-on SDK
You can use CommonJS modules outside the Add-on SDK, in any environment where you can use Components.utils.import. Just call the following:
const { require } = Cu.import("resource://gre/modules/commonjs/toolkit/require.js", {})
This will import require()
into your scope.
You can then use that to import CommonJS modules. You can import SDK modules in just the same way you could from an SDK add-on:
// import the SDK's base64 module var base64 = require("sdk/base64"); base64.encode("hello"); // "aGVsbG8="
You can import other CommonJS modules, too, as long as you know the path to them:
// import my module var myModule = require("resource://path/to/my/module.js");
In this case, though, you might be better off creating your own loader, so you can specify the paths
property yourself.