Getting Started with Firefox Extensions

New Addons should use WebExtensions.

Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

Starting from Firefox 53, no new legacy add-ons will be accepted on (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

What's a Firefox Extension?

Extensions add new functionality to Mozilla applications such as Firefox and Thunderbird. They can add anything from a toolbar button to a completely new feature. They allow the application to be customized to fit the personal needs of each user if they need additional features, while keeping the applications small to download.

Taken from the Extensions page.

As described in the quoted text, an extension is a small application that adds something new to one or more Mozilla applications. This tutorial focuses on extensions for Firefox, but the same (or very similar) principles apply to creating extensions for other applications such as Thunderbird, Seamonkey, and Flock.

It is also worth noting that there are differences between the definition of extension and add-on. All extensions are add-ons, but add-ons can also be themes, plugins, or language packs. This tutorial is about extension development, but themes and language packs are developed in a very similar way. Plugins are entirely different, and they will not be covered here. You can read more about plugins and their development in the Plugins page.

Firefox provides a very rich and flexible architecture that allows extension developers to add advanced features, customize the user's experience, and completely replace and remove parts of the browser. The Mozilla Add-ons repository (AMO) holds an extensive number of extensions with a wide variety of functions: content filtering (AdBlock Plus, NoScript), web application interaction (Delicious Bookmarks, eBay Companion) and web development (DOM Inspector, Firebug). These are very advanced and complex extensions, and you'll learn most of what it takes to create extensions like these.

Extensions now exist in 3 different forms: Add-ons SDK extensions (also known as Jetpacks), bootstrapped extensions and traditional extensions. If you're only getting started developing add-ons, the Add-ons SDK provides a great way to quickly create simple ones and build on them. This tutorial focuses on traditional extensions, which are created differently. Bootstrapped extensions are a step above traditional ones in complexity, so you should go through this tutorial before giving them a try.

We'll begin the tutorial by analyzing a very simple extension.

The Hello World Extension

Our sample extensions and this tutorial in general are meant for modern versions of Firefox, but most of it works on older versions too.

We'll now begin with a basic "Hello World" extension. Let's start by installing it. Click on the link below.

NOTE: This extension is unsigned. Starting with Firefox 43, extensions need to be signed by Mozilla before they can be installed in Firefox. Unsigned add-ons can still be installed in Developer Edition, Nightly, and ESR versions of Firefox, after toggling the xpinstall.signatures.required preference in about:config.

Install Hello World

Click the above link and then click "allow" in the pop-up bubble. You should see another pop-up telling you that you are installing an unverified add-on. Click "install". After the extension is installed, you'll be asked to restart Firefox. Installing, uninstalling, enabling and disabling add-ons require a restart to complete, with the exception of NPAPI plugins, Add-ons SDK extensions and bootstrapped extensions. This is an important point to keep in mind if you're building an extension that manipulates other extensions or themes.

After installing, look at the main Firefox window and see if you notice anything different.

Did you see it? There's a new menu on the main menu, labeled "Hello World!".

If you open the menu and then the menu item below, you'll see a nice alert message (for some definitions of 'nice'). Click on the OK button to close it.

That's all the extension does. Now let's take a closer look at it.

Extension Contents

You may have noticed that the extension file you installed is named xulschoolhello1.xpi. XPI (pronounced "zippy") stands for Cross-Platform Installer, because the same installer file can work on all platforms Firefox supports. XPIs are simply ZIP files, but Firefox recognizes the XPI extension and triggers the installation process when an XPI file is loaded.

To look into the XPI file you need to download it first, not install it. If the server triggers an install when clicking on a link or button, what you need to do is right click on the install link, and choose the Save Link As... option.

Decompress the XPI file in a convenient location. Issue the following command to unzip the file on Linux or Mac OS X:

unzip xulschoolhello1.xpi -d xulschoolhello1

On Windows, you can change the file extension from xpi to zip, or open the file directly, then unzip it, using a ZIP tool.

You should see the following directory structure:

  • xulschoolhello1
    • chrome.manifest
    • install.rdf
    • content
      • browserOverlay.xul
      • browserOverlay.js
    • skin
      • browserOverlay.css
    • locale
      • en-US
        • browserOverlay.dtd

That's lots of files for something so simple! In the next section, we'll inspect these files and see what they do.

This tutorial was kindly donated to Mozilla by Appcoast.