cfx to jpm

A guide to working with jpm if you're already familiar with cfx.

Installation

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 npm update.

For jpm installation instructions, see the Installation section in the jpm reference.

Activation

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 activate again.

With jpm, you don't need to activate. Once it's installed, you can just use it.

Add-on incompatibilities

In most respects, add-ons created with cfx will work fine with jpm. However, there are a few differences you have to know about.

Add-on ID

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 "jid1-F3BoogbjQJE67A@jetpack".

ID handling with jpm

When you create an XPI with jpm xpi:

• if the package.json does not include an id field, then the ID written into the install.rdf is the value of the name field prepended with "@".
• if the package.json does include an id field, and it contains "@", then this is written into the install.rdf as the add-on ID.
• if the package.json does include an id field, 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.

Entry point

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 main field to package.json with the value "lib/main.js".

Loading modules

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:

• my-addon
  • lib
    • main.js
    • utils.js

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:

• my-addon
  • lib
    • my-addon.js
  • test
    • test-my-addon-js

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");

Third-party modules

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.

Mobile development

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 --profiledir and --overload-modules, use --profile and --overload.

Instead of using --force-mobile, explicitly add fennec to engines section of your package.json.

Package.json fields

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

• data
• fullName - use title instead
• lib
• packages
• tests
• icon64

Package.json escaping

Where with cfx you might have had to escape with 2 upto 3 backslashes ( \ ), jpm only needs one now.