Extension Packaging

This article is in need of a technical review.

Extensions are a form of Installable Bundle which can be downloaded and installed by a user, or provided pre-packaged with an application or by an external program. Extensions use a directory structure which can provide chrome, components, and other files to extend the functionality of a XUL program.

Every extension must provide an install.rdf file which contains metadata about the extension, such as its unique ID, version, author, and compatibility information.

After the extension files and install.rdf have been prepared, there are several ways to prepare an extension for installation: ZIP the extension directory into a user-installable XPI (xpinstall) file, unpack the extension directly into the user's application or profile directory, or register the extension in the Windows registry.

Note: Starting in Gecko 2.0, XPI files are no longer unpacked when extensions are installed. Instead, the XPI itself is placed in the extensions directory, and files are loaded directly out of the package. See Updating extensions for Firefox 4 for details.

Making an extension XPI

An XPI (XPInstall) file is simply a ZIP file containing the extension files, with the install.rdf file at the root of the ZIP. Users can download and install XPI files off a website or from a local file, by opening it or dragging it into the Extension Manager window.

The MIME type recognized by Firefox for XPI files is application/x-xpinstall. Since most HTTP servers are not configured to return this MIME type for the .xpi extension by default, you will probably need to configure your HTTP server. In the Apache HTTP Server, this can be done by adding the following directive to the configuration file or .htaccess:

AddType application/x-xpinstall .xpi

A great way to distribute XPI files intended for public dissemination is using the addons.mozilla.org web site. See Submitting an add-on to AMO for details.

Install extension files directly

If you know the location of the application (if you are installing an extension as part of the application installer, for example), you can install the extension files directly to <appdir>/extensions/<extensionID>. The extension will be found automatically by the extension manager the next time the application is launched.

When using this method you must verify that the file system permissions for the directories and files for the extension are set properly. Otherwise, the Extension Manager may not function properly with the extension or the extension itself may not work properly.

Including add-ons in a customized application

A customized application can include add-ons (including extensions and themes) by placing the unpacked (that is, not the XPI files, but the packages' contents) in the <appdir>/distribution/bundles directory. The directory containing the add-on must be named the same as the ID of the add-on or theme. Add-ons packaged in this way will not be visible to the user.

Register an extension location using the Windows Registry

External installers (such as the Java runtime) may wish to install application integration points as extension even if the application is not yet installed. This can be accomplished on Windows using the registry.

Multi-item extension XPIs

In some cases a single XPI file may wish to install multiple extensions/themes. A special kind of extension XPI called the Multiple Item Package explains how to create this kind of package. (Firefox 1.5/XULRunner 1.8 required.)

Official references for Toolkit API