Jetpack/FAQ

JetPack" is the name of the project to make building add-ons even easier. Add-on Builder (Beta) and Add-on SDK. are tools that let developers make great add-ons using HTML, JavaScript and CSS.

General

What is the Add-on Builder?

The Add-on Builder is an online development environment which you can use with just a web browser. It provides a code editor, a file browser, and tools to help test and package your add-on right in the browser.

What is the Add-on SDK?

The Add-on SDK is a downloadable software development kit for building Firefox add-ons in a command line interface environment. It includes high-level APIs for interacting with and modifying web pages and Firefox's user interface along with tools for creating, testing, and packaging add-ons.

What is the Jetpack SDK?

Jetpack SDK is the old name for the Add-on SDK.

What are the benefits of using the Add-on SDK?

The Add-on SDK lets you build Firefox add-ons using common web technologies like HTML, JavaScript and CSS, and it includes tools to make it easy to create, test, and package add-ons.

The SDK is designed to produce add-ons that will be forwards-compatible with future versions of Firefox, so you won't need to update your add-on every time a new version of Firefox is released. SDK-based add-ons benefit from a security model that limits the harm that can be caused by a vulnerability in add-on code.

Finally, the SDK implements the CommonJS Packages and Modules specifications to enable a rich ecosystem of third-party APIs that developers can use to build their add-ons in addition to the APIs built into the SDK itself. We maintain a page listing some of the extra third-party APIs you can use in your add-on.

What are the benefits to users of SDK-based add-ons?

Add-ons created with the Builder or the Add-on SDK are restartless by default, meaning users can install and remove SDK-based add-ons instantly, without a browser restart. This makes it easier to try add-ons and personalize their browsing experience.

Developers and users alike also will not have to worry about add-on compatibility with new versions of Firefox.

Finally, SDK-based add-ons will soon load in separate processes, so slow-running add-ons won't slow down Firefox itself.

Can I do everything with the Add-on SDK that I could with a XUL-based add-on? Should I rewrite my XUL-based add-on now?

You can do substantially everything with an SDK-based add-on that you can do with a XUL-based add-on, including:

modifying XUL windows
accessing XPCOM components
loading your own XPCOM components, both binary and JavaScript.

You have to do some things differently: in particular, you can't use XUL overlays in SDK-based add-ons because they are not compatible with restartless add-ons. Instead, you have to use DOM manipulation.

However, in the 1.0 release the SDK is aimed primarily at Web developers who wish to write add-ons but are unfamiliar with the traditional XUL-based approach. So it supports a set of easy-to-use high level JavaScript APIs which address the most common use cases encountered by add-on developers. Using only the high level APIs, you can't do everything a XUL-based add-on can do.

After shipping 1.0 one of our top priorities is to help developers migrate from XUL-based add-ons to SDK-based add-ons, so implementing advanced add-ons with the SDK will get much easier.

So if you're a XUL add-on developer, an early adopter, and are willing to participate in the development process, then now is a great time to try out the SDK and help us figure out the right set of features to enable you to make the transition.

What do I need to know to write an add-on using the SDK?

You'll develop add-ons using JavaScript, and you'll interact with web content via the DOM. You'll use HTML and CSS to structure and style your own user interface components.

What are the system requirements for the SDK?

You need Python 2.5, 2.6, or 2.7, and Firefox version 4 or later.

If you're running Windows, MozillaBuild, while not mandatory, will install the correct version of Python and the MSYS package, which will make it easier to work with the SDK.

What are the system requirements for the Builder?

You need Firefox version 4 or later, and an Internet connection.

Will the SDK be fully integrated into Firefox?

The SDK is a separate product from Firefox, and there are no plans to integrate its functionality directly into Firefox. However, the Builder, Add-on SDK and Firefox teams work closely to ensure Firefox provides a great set of extension capabilities for SDK APIs to expose to add-on developers.

Do users need to download or install anything to use SDK-based add-ons?

No. Users only need to install the SDK-based add-ons themselves, which are all hosted in the same place as traditional XUL-based add-ons: addons.mozilla.org.

Will Mozilla stop supporting XUL-based add-ons?

Mozilla has no plans to stop supporting XUL-based add-ons, and it would be premature to start making such plans, as the vast majority of Firefox add-ons are XUL-based.

If at some point in the future that ratio changes, and the vast majority of Firefox add-ons become SDK-based, then it may make sense to consider deprecating XUL-based add-ons.

What about Firefox Mobile?

The Jetpack team's current focus is creating the best possible experience for developers of desktop Firefox add-ons. We are well aware, however, of the importance of mobile Firefox to Mozilla and its users, and we plan to prioritize mobile Firefox add-on development in a future release of the SDK.

What is Jetpack?

Jetpack is a project to make it easy to build Firefox add-ons using common web technologies like HTML, JavaScript, and CSS. Our goal is to enable anyone who can build a web site to participate in making the Web a better place to work, communicate, and play.

I have a Google Chrome plugin/Safari add-on. Will it work as a Firefox add-on?

You will need to do some porting, but the changes should be relatively straightforward. David Morgan has written an extension for Chrome and Firefox that shares much of the code: http://code.google.com/p/scry/.

Programming

Building a UI

How can I place my add-on's widget in a different part of the Firefox UI?

You can only place widgets in the add-on bar, although users can move them from there to another toolbar.

The purpose of the add-on bar is to consolidate add-on buttons/icons/widgets in a known location in the browser chrome, so that users who install an add-on with a UI will know where to look for it.

How can I make a Widget look and behave differently in different windows?

Use a WidgetView.

How can I have a Preferences UI/Options UI for my add-on?

At the moment the SDK doesn't offer a module to give you a Preferences/Options UI for your add-on. You have to build the UI yourself using the basic UI components provided.

We will add a module for this in a future release of the SDK.

Why can't I create Firefox toolbars using the SDK/Builder?

In the past, we haven't provided much guidance to add-on developers about how best to integrate their user interfaces into Firefox, and the add-ons manager did not make it easy for users to access an add-on's preferences. The result of this has been a proliferation of toolbars and menu items, which can lead to a cluttered and confusing user experience.

Therefore in the SDK, the preferred way for add-ons to expose a permanent user interface is through the Widget API, which will ensure that the user interfaces for all add-ons default to a standard location (the add-on bar) where users will expect to see them.

Can I add items to Firefox's menus in my add-on?

No you cannot. You can add items to the context menu, but not the main menu.

How can I customize my widget's context menu?

That's not currently possible.

My add-on needs to prompt the user to select a file. Is there a module in the SDK to help me with this?

Not in the core set, but you can find a external file selection module in the Additional Modules page.

Interacting With the Web

Why can't my add-on code access web content directly?

The Mozilla platform is moving towards a model in which it uses separate processes to display the UI, handle web content, and execute add-ons.

This will improve the responsiveness of the UI, application stability, and performance, especially on multi-core machines.

In this architecture the main add-on code will run in the add-on process and will not have direct access to any web content.

Although this separation isn't enforced as of Firefox 5, the SDK is designed to be forward compatible with the change, so that when it happens you won't need to rewrite add-ons written using the SDK.

What's a content script?

A content script is a script that runs in the context of a web page. If you need to interact with web content in your add-on, you will use a content script to access and manipulate web content.

Content scripts don't share an execution context with add-on code, so code in a content script can't directly access variables and functions in the add-on code or vice versa. Instead, you communicate between content scripts and add-on code using a message-passing scheme.

I have a panel hosting some content, and it has a content script associated with it. Whenever the panel's location changes the content script stops working, and gives me this error: "ERR_DESTROYED, "The page has been destroyed and can no longer be used." How can I fix this?

The best workaround for this is to load the panel's document in an iframe, and change that. Then the panel's content scripts will continue to work.

How can I run a content script in the context of the currently active tab?

Use tab.attach().

How can I assign a value in a content script to a variable in my main add-on script?

You might try to do something like this:

var a = 1; 

var pageMod = require("page-mod"); 
 pageMod.PageMod({ 
 include: "*", 
 contentScriptWhen: "ready", 
 contentScript: "a = 2;"
});

This isn't going to work, because the content script ""a = 2;"" is running in a different context to the main script, and can't see the declaration of a. You'd need to pass the value as a message to the add-on script, and do the assignment in there:

var a = 1; 

var pageMod = require("page-mod"); 
 pageMod.PageMod({ 
 include: "*", 
 contentScriptWhen: "ready", 
 contentScript: "self.postMessage(2);", 
onAttach: function onAttach(worker) {
  worker.on("message", function(data) {
    a = data;
    });
  }
});

General Programming

Why doesn't window.alert() work in my add-on?

On the web, JavaScript executes in the context of a web page, and has access to that page's DOM content. This enables you to call functions like window.alert(), and to access the document object. But these are DOM features, not JavaScript features.

The add-on code does not execute in the context of a page, and the DOM is therefore not available. To access the DOM of a particular page, you need to use a content script.

Standard JavaScript APIs, such as Array and JSON, are available to add-on code.

See https://developer.mozilla.org/en/The_DOM_and_JavaScript for a good summary of the difference between the DOM and JavaScript, and this SDK guide for a summary of the APIs that are and are not available to add-on code.

For debugging purposes you can log strings to the console using the global console object.

Can I use XUL in an SDK-based add-on?

Yes. However, some of the features of the traditional XUL-based add-on platform, such a XUL overlays, are not available to SDK-based add-ons because they are incompatible with instant install/removal of add-ons or loading add-ons in separate processes.

Can I use jQuery in my add-on?

Yes, you can. Just add it as another content script. See the 'reddit-panel' example in the SDK.

Can I use other CommonJS modules like node.js in my add-on?

Not yet, although we plan to add this ability as soon as we can.

Can I use SDK modules in a traditional XUL extension?

Not at the moment, although we hope to support this soon.

Is there a Socket API in the SDK?

Not in the core set, but you can find a external sockets module in the Additional Modules page.

What's the local path on disk for my add-on's data directory?

Although the data directory does currently map to a directory on your disk, it's best not to assume that this will continue to be the case. We're planning to stop unpacking .xpis pretty soon (not before 1.0, but soon afterwards, see bug 638742 for details), which means there won't even be a ""local path"" for files in the data/ directory. They'll be inside a ZIP file with an .xpi extension.

The require("self").data.url(name) function will give you a URL that's usable from within the addon itself (e.g. as a content-script), but that involves a mapping function that goes from URLs to resources, and those resources don't have to be real files on disk.

How can I read from/write to a file?

You can use the file module in api-utils. However, if you just need some persistent storage and don't need the data to be available outside your add-on, you can use the simple-storage module in addon-kit.

How can I access data from my add-on's 'package.json' file, such as my add-on's name or version number?

At the moment there isn't a properly supported way to do this.

How can I debug my add-on?

You can run debuggers such as Venkman and Chromebug by:

specifying a profile that has these add-ons installed via the cfx --profiledir option
passing the -venkman or -chromebug argument to Firefox using the cfx --binary-args option:

cfx --profiledir /my/profile/name --binary-args -chromebug run