Getting Started (jpm)

This tutorial walks through creating a simple add-on using the SDK.

Prerequisites

To create add-ons for Firefox using the SDK, you'll need:

• Firefox version 38 or later. If you need to work with earlier versions of Firefox, you'll need to use the old cfx tool. See instructions for getting started with cfx.
• the command-line jpm tool. See the instructions for installing jpm. Once you've done that, you'll be looking at a command prompt.

Initializing an empty add-on

In the command prompt, create a new directory. Navigate to it, type jpm init, and hit enter:

mkdir my-addon
cd my-addon
jpm init

You'll then be asked to supply some information about your add-on: this will be used to create your add-on's package.json file. For now, just press Enter to accept the default for each property. For more information on jpm init, see the jpm command reference.

Once you've supplied a value or accepted the default for these properties, you'll be shown the complete contents of "package.json" and asked to accept it.

Implementing the add-on

Now you can write the add-on's code. Unless you've changed the value of "entry point" ("main" in package.json), this goes in "index.js" file in the root of your add-on. This file was created for you in the previous step. Open it and add the following code:

var buttons = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");

var button = buttons.ActionButton({
  id: "mozilla-link",
  label: "Visit Mozilla",
  icon: {
    "16": "./icon-16.png",
    "32": "./icon-32.png",
    "64": "./icon-64.png"
  },
  onClick: handleClick
});

function handleClick(state) {
  tabs.open("https://www.mozilla.org/");
}

Save the file.

Next, create a directory called "data" in your add-on's root,

mkdir data

and save these three icon files to the "data" directory:

	icon-16.png
	icon-32.png
	icon-64.png

Back at the command prompt, type:

jpm run

This is the jpm command to run a new instance of Firefox with your add-on installed.

If Firefox can not be located, you may need to provide the path to it (example in Ubuntu):

jpm run -b /usr/bin/firefox

When Firefox launches, in the top-right corner of the browser you'll see an icon with the Firefox logo. Click the icon, and a new tab will open with https://www.mozilla.org/ loaded into it.

That's all this add-on does. It uses two SDK modules: the action button module, which enables you to add buttons to the browser, and the tabs module, which enables you to perform basic operations with tabs. In this case, we've created a button whose icon is the Firefox icon, and added a click handler that loads the Mozilla home page in a new tab.

Try editing this file. For example, we could change the page that gets loaded:

var buttons = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");

var button = buttons.ActionButton({
  id: "mozilla-link",
  label: "Visit Mozilla",
  icon: {
    "16": "./icon-16.png",
    "32": "./icon-32.png",
    "64": "./icon-64.png"
  },
  onClick: handleClick
});

function handleClick(state) {
  tabs.open("https://developer.mozilla.org/");
}

At the command prompt, execute jpm run again. This time clicking it takes you to https://developer.mozilla.org/.

Packaging the add-on

When you've finished the add-on and are ready to distribute it, you'll need to package it as an XPI file. This is the installable file format for Firefox add-ons. You can distribute XPI files yourself or publish them to https://addons.mozilla.org so other users can download and install them.

To build an XPI, just execute the command jpm xpi from the add-on's directory:

jpm xpi

You should see a message like:

JPM info Successfully created xpi at /path/to/my-addon/@my-addon-0.0.1.xpi

To test that this worked, try installing the XPI file in your own Firefox installation. You can do this by pressing the Ctrl+O key combination (Cmd+O on Mac) from within Firefox, or selecting the "Open" item from Firefox's "File" menu. This will bring up a file selection dialog: navigate to the "@my-addon.xpi" file, open it and follow the prompts to install the add-on.

Note that Firefox by default requires add-ons, even locally developed ones, to be signed. After installation they'll show up disabled in the list of installed add-ons, noting the missing signature. During development, or if you don't plan to distribute, you can open about:config and set xpinstall.signatures.required to false to run it unsigned. This setting applies to any add-on, so take extra care to not accidently install a malicious one from elsewhere.

To distribute your add-on, submit the XPI file to addons.mozilla.org or run jpm sign if you wish to distribute the add-on on your own server.

Summary

In this tutorial we've built and packaged an add-on using three commands:

• jpm init to initialize an empty add-on template
• jpm run to run a new instance of Firefox with the add-on installed, so we can try it out
• jpm xpi to package the add-on into an XPI file for distribution

These are the three main commands you'll use when developing SDK add-ons. There's comprehensive reference documentation covering all the commands you can use and all the options they take.

The add-on code itself uses two SDK modules, action button and tabs. There's reference documentation for all the high-level and low-level APIs in the SDK.

What's next?

To get a feel for some of the things you can do with the SDK APIs, try working through some of the tutorials.