Two Types of Scripts

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.

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("Hello there");

In an add-on's main scripts you can't do that, because the add-on code does not execute in the context of a page, and the DOM is therefore not available. If you need to access the DOM of a particular page, you need to use a content script.

So there are two distinct sorts of JavaScript scripts you might include in your add-on and they have access to different sets of APIs. In the SDK documentation we call one sort "add-on code" and the other sort "content scripts".

Add-on Code

This is the place where the main logic of your add-on is implemented.

Your add-on is implemented as a collection of one or more CommonJS modules. Each module is supplied as a script stored under the lib directory under your add-on's root directory.

Minimally you'll have a single module implemented by a script called "main.js", but you can include additional modules in lib, and import them using the require() function. To learn how to implement and import your own modules, see the tutorial on Implementing Reusable Modules.

Content Scripts

While your add-on will always have a "main.js" module, you will only need to write content scripts if your add-on needs to manipulate web content. Content scripts are injected into web pages using APIs defined by some of the SDK's modules such as page-mod and panel.

Content scripts may be supplied as literal strings or maintained in separate files and referenced by filename. If they are stored in separate files you should store them under the data directory under your add-on's root.

To learn all about content scripts read the Working with Content Scripts guide.

API Access for Add-on Code and Content Scripts

The table below summarizes the APIs that are available to each type of script.

API Add-on code Content script
The global objects defined in the core JavaScript language, such as Math, Array, and JSON. See the reference at MDN.

The require() and exports globals defined by version 1.0 of the CommonJS Module Specification. You use require() to import functionality from another module, and exports to export functionality from your module.

If require() is available, then so are the modules supplied in the SDK.
The console global supplied by the SDK.
Globals defined by the HTML5 specification, such as window, document, and localStorage.
The self global, used for communicating between content scripts and add-on code. See the guide to communicating with content scripts for more details.


Document Tags and Contributors

 Contributors to this page: wbamberg, evold
 Last updated by: wbamberg,