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. Developers have the choice of working in an online hosted environment with the Add-on Builder (Beta) or locally through a command line interface with the Add-on SDK.

General

What is the Add-on Builder (beta)?

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 and Add-on Builder (Beta)?

These tools 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 tools are 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. Add-on SDK and Add-on Builder-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 Add-on SDK and Add-on Builder implement 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 Add-on 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 add-ons created with the Add-on SDK and Add-on Builder?

Add-ons created with the Add-on Builder or the Add-on SDK are restartless by default, meaning users can install and remove add-ons built with these tools instantly, without interrupting their browser experience through 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, add-ons built with these tools 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 and Add-on Builder (Beta) that I could with a XUL-based add-on? Should I rewrite my XUL-based add-on now?

You can do nearly everything with an Add-on SDK and Add-on Builder 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 Builder / SDK-based add-ons because they are not compatible with restartless add-ons. Instead, you have to use DOM manipulation.

Add-on Builder and the Add-on SDK are 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 version 1.0 of the Add-on SDK and the Add-on Builder (Beta), one of our top priorities is to help developers migrate from XUL-based add-ons to Builder/SDK based add-ons, so implementing advanced add-ons will become 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 Add-on SDK and Add-on Builder 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 Add-on Builder (Beta) and Add-on 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 Add-on Builder (Beta)?

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

What are the system requirements for the Add-on 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.

Will the Add-on SDK be fully integrated into Firefox?

The Add-on SDK is a separate product from Firefox, and there are no plans to integrate its functionality directly into Firefox. However, the Add-on 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 Add-on SDK and Add-on Builder based add-ons?

No. Users only need to install the SDK/Builder 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 are Builder/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 Add-on SDK and Add-on Builder.

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 Add-on SDK and Add-on Builder (Beta) don'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 provide a module for this in future releases of the Add-on SDK and Add-on Builder.

Why can't I create Firefox toolbars using the Add-on SDK / Add-on Builder (Beta)?

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 Add-on SDK and Add-on Builder (Beta), 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 Add-on Builder (Beta) / Add-on 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, Add-on SDK and Add-on Builder are designed to be forward compatible with the change, so that when this happens you won't need to rewrite add-ons written using the Add-on SDK / Add-on Builder.

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 Add-on SDK / Add-on Builder 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 Builder / 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 Add-on 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 Add-on SDK / Add-on Builder modules in a traditional XUL extension?

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

Is there a Socket API in the Add-on 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:

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

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