We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.
Don't use these techniques to develop new add-ons. Use WebExtensions instead.
If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions instead.
Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
The Add-on SDK includes a command-line tool that you use to initialize, run, test, and package add-ons. The current tool is called jpm, and is based on Node.js. It replaces the old cfx tool.
You can use jpm from Firefox 38 onwards.
This article highlights the main differences between cfx and jpm.
A guide to working with jpm if you're already familiar with cfx.
cfx is Python-based and is distributed as a zip file. jpm is Node-js-based and is distributed through npm. So for jpm you don't need Python, but you do need npm.
To get new updates of cfx you download and extract a new zip file, while to get the new version of jpm, use
For jpm installation instructions, see the Installation section in the jpm reference.
You need to call
cfx activate before you can use cfx, and this only works in the current command shell: if you open a new shell you have to call
With jpm, you don't need to activate. Once it's installed, you can just use it.
In most respects, add-ons created with cfx will work fine with jpm. However, there are a few differences you have to know about.
The add-on ID is a unique identifier for your add-on. In a built XPI, it's the ID field in the add-on's Install Manifest (install.rdf) file.
The ID is used for a variety of purposes. For example: addons.mozilla.org uses it to distinguish between new add-ons and updates to existing add-ons, and the
simple-storage module uses it to figure out which stored data belongs to which add-on.
ID handling with cfx
When you use cfx, the ID is taken from the
id field in the add-on's package.json file. You can edit this file to create your own ID, but if you don't, cfx will generate one for you, which will look something like "
jid1-F3BoogbjQJE67A". Add-on IDs need to be one of two types: a GUID or a string that includes an
"@" symbol. The SDK expects the latter format, and if the ID in package.json doesn't contain "@", then cfx xpi will append "
@jetpack" to the package.json field, and make that the add-on ID.
So: if you never did anything with IDs when using cfx, then the value in your add-on's package.json will be something like "
jid1-F3BoogbjQJE67A", and the corresponding ID in the install.rdf will be "
ID handling with jpm
When you create an XPI with
- if the package.json does not include an
idfield, then the ID written into the install.rdf is the value of the
namefield prepended with "@".
- if the package.json does include an
idfield, and it contains "@", then this is written into the install.rdf as the add-on ID.
- if the package.json does include an
idfield, and it does not contain "@", then jpm xpi raises an error and the XPI will not be built.
What you need to do
All this means that: if your package.json contains an id field, and its value does not contain "@", then you must append "@jetpack" to it when switching to jpm.
If you do this, the add-on's ID will be the same as it was when you were using cfx.
The add-on's entry point is the file that's executed when the add-on needs to initialize itself: for example, when Firefox starts, or when the add-on's installed, enabled, or upgraded. With cfx, this defaults to "lib/main.js", although it can be set to a different file using the
main field in package.json.
In jpm, the entry point defaults to "index.js". So when switching over to jpm:
- either rename your "main.js" to "index.js" and move it from "lib" to the top level
- or add a
mainfield to package.json with the value "lib/main.js".
The jpm tool uses the same logic as Node.js to determine how to resolve the argument to
require(). In most respects this is the same as the old cfx logic. However there are a few differences, because old compatibility shims have been removed.
Requiring local modules
Suppose your add-on is structured into separate modules:
When you want to use the "utils" module in "main.js", you should use a path relative to "main.js", and prefix the path with "./" to indicate that it's a relative path:
var utils = require("./utils");
However, with cfx you are also allowed to omit the "./":
var utils = require("utils"); // this will not work with jpm!
This second form will not work with jpm.
Requiring modules from test code
Similarly, suppose you've written some tests for your add-on:
With cfx, code inside "test-my-addon.js" can import "my-addon.js" using a statement like this:
var my_addon = require("my-addon"); // this will not work with jpm!
With jpm, you must specify the path to "my-addon" explicitly, using a relative path:
var my_addon = require("../lib/my-addon");
The SDK has always supported third-party modules: developers can write their own modules that extend the SDK's APIs or add new APIs, and other add-on developers can make use of these modules in the same way that they use the SDK's built-in modules.
In jpm the old way to use third-party modules no longer works. Instead, jpm expects third-party modules to be hosted on npm, and you can use them by installing them from npm into your add-on's directory tree, then requiring them. See the tutorial on using third-party modules with jpm.
jpm does not support the "--force-mobile" option, instead you will need to define engines in package.json and add "fennec" there.
There is a known bug in simple options handling which may require the workaround described in https://bug635044.bugzilla.mozilla.org/show_bug.cgi?id=1243467
Commands and command options
Permanently removed commands
jpm has dropped support for all the "Internal" cfx commands.
Permanently removed options
jpm has dropped support for:
--extra-packages --use-config --package-path --pkgdir --no-strip-xpi --harness-option --manifest-overload --output-file --templatedir --keydir --profiledir --overload-modules --static-args --app --no-run --addons --e10s --logfile --dependencies --force-mobile --test-runner-pkg
Instead of using
--force-mobile, explicitly add
fennec to engines section of your package.json.
Many package.json fields are implicit commands to cfx. In jpm, we've removed support for some of these fields, and are still working on supporting some others.
Permanently removed fields
Where with cfx you might have had to escape with 2 upto 3 backslashes ( \ ), jpm only needs one now.