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. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.
From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).
From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.
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 WebExtensions if they can. See the "Compatibility Milestones" document for more.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
Welcome to the XUL School Tutorial!
This tutorial is meant to be the stepping stone that will turn you into a professional Firefox extension developer in no time. We have poured years of XUL experience into it, providing many solutions for problems extension developers commonly run into.
XUL School was created by Appcoast (formerly Glaxstar), one of the few companies dedicated to building high-quality Firefox extensions. A team of over a dozen XUL developers conformed Glaxstar at the time this tutorial was created, and the combined experiences of years creating Firefox extensions are reflected here.
With this tutorial you'll learn how to develop Firefox extensions. You'll learn how to quickly do the most common tasks in extension development, comparing several different approaches to solve them. In most cases we'll provide code samples that you can easily copy and adapt to your needs, as well as some working example extensions. The tutorial aims to be as brief as possible, often falling back on Mozilla documentation for more detailed information. You can think of it as a quick guide to the expansive world that is the Mozilla platform. Most links in this documentation are meant to be clicked and read.
We'll start with a brief introduction to some key concepts, in case you're not familiar with Mozilla and Firefox.
Mozilla and Firefox
The term Mozilla can be used to refer to several concepts: the Mozilla project, the Mozilla Foundation, the Mozilla Corporation and the old Mozilla browser. Even Firefox is sometimes referred to as "Mozilla". If you're unfamiliar with these terms, it's good that you take some time and learn a little about Mozilla. This will help you understand the culture that surrounds the Mozilla community.
Mozilla has spawned several products and projects, the most notable being the Mozilla Firefox web browser. Firefox is one of the most successful open source projects in history, combining the openness, standards-compliance and sophistication of open source with the focus on user experience and powerful outreach more commonly seen in less open companies.
Version 1.0 of Firefox was released in November 2004, version 2.0 in October 2006, and version 3.0 in June 2008. This tutorial was written after Firefox 3 was released, and has been updated with time. While most of it should still work for creating extensions in Firefox 3 (and even Firefox 2), it is strongly recommended that you aim to support modern Firefox versions, to encourage users to stay up to date with security fixes. A release that is more than 6 months old is likely vulnerable to published security bugs.
Firefox and other Mozilla applications can be seen as composed of two different parts: a user interface layer that is distinct for each project, and a common platform on top of which the interface layer is built. The user interface is built with technology known as XUL, and the platform is known as XULRunner.
XUL
XUL (pronounced "zool") is one of many technologies used for creating Mozilla-based products and extensions. It is only one part of the development landscape, but given that it's practically exclusive to Mozilla, it tends to be used to identify all Mozilla-related development. You'll sometimes read terms like "XUL applications" and "XUL extensions", but rarely will they refer to projects that are exclusively built with XUL. It usually means that the projects were built using Mozilla technologies. Even this project, called XUL School, covers several other technologies such as JavaScript, CSS, XBL and XPCOM.
XULRunner
XULRunner includes the Gecko rendering engine, the Necko networking library, and several other components that provide OS-independent file management, accessibility, and localization, among others. It is this very powerful platform that has allowed such a fast growth of the development community surrounding Mozilla and Firefox.
XULRunner is available in binary form at the XULRunner page, and it is the base for several projects, such as Songbird, Miro and Eudora. There's a very comprehensive list of XULRunner applications in the XULRunner Hall of Fame.
Gecko
The Gecko engine is the part of Firefox used to render web pages and its own user interface. You can identify the level of compatibility of web standards in Gecko-based browsers looking at their User Agent string, which should include the Gecko version. Gecko versions are somewhat independent from Firefox versions, and you can see a mapping of Firefox versions and Gecko versions at the Gecko page. The User Agent String for Firefox at the time of this writing (in US English, Mac OS X) is:
Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:25.0.1) Gecko/20100101 Firefox/25.0.1
The highlighted section is the Gecko version: 25.0.1. You can read and copy the user agent string of any Firefox window, choosing "Help > Troubleshooting Information" from the main menu.
On to the Tutorial
With the basic concepts out of the way, we can now get right into extension development. You are probably still wondering what exactly is an extension, what can it do, and how can you make them. Well, this whole tutorial is devoted to explaining that to you.
Welcome to the world of extension development. Now let's get to it.
This tutorial was kindly donated to Mozilla by Appcoast.