Your first extension

Writing the extension

In a suitable location, such as the Documents directory, create a directory named borderify, then navigate to it. You can do this using your computer's file explorer or command line terminal.

Understanding how to use the command line terminal is a handy skill for software development. If you need help getting started with the terminal, check out the Command line crash course.

Using the terminal, create the directory like this:

mkdir borderify
cd borderify

manifest.json

Using a suitable text editor, create a file called "manifest.json" under the "borderify" directory. Give it this content:

{
  "manifest_version": 2,
  "name": "Borderify",
  "version": "1.0",

  "description": "Adds a red border to all webpages matching mozilla.org.",

  "icons": {
    "48": "icons/border-48.png"
  },

  "browser_specific_settings": {
    "gecko": {
      "id": "beastify@mozilla.org",
      "data_collection_permissions": {
        "required": ["none"]
      }
    }
  },

  "content_scripts": [
    {
      "matches": ["*://*.mozilla.org/*"],
      "js": ["borderify.js"]
    }
  ]
}

• The first three keys (manifest_version, name, and version) are mandatory and contain basic metadata for the extension.
• description is required in Safari, otherwise it's optional. However, it's a good idea to set this property, as it's displayed in the browser's extension manager (for example, about:addons in Firefox).
• icons is optional, but recommended: it enables you to specify an icon for the extension.
• browser_specific_settings is required by Firefox.
  • The gecko property provides addons.mozilla.org and Firefox with extra configuration information about the extension.
    • id defines a unique identifier for the extension. This property must be declared to publish the extension on addons.mozilla.org (AMO).
    • data_collection_permissions provides information on whether the extension collects and transmits personally identifiable information. This property must be declared to publish the extension on addons.mozilla.org (AMO). This example doesn't collect or transmit any data.

So far, these manifest.json keys have been providing information about the extension. The next key, content_scripts, starts to define the extension's functionality. This key tells Firefox to load a script into web pages whose URL matches a specific pattern. In this case, the extension is asking Firefox to load a script called "borderify.js" into all HTTP or HTTPS pages served from "mozilla.org" or any of its subdomains.

• Learn more about content scripts
• Learn more about match patterns

icons/border-48.png

Firefox identifies extensions by an icon in various parts of its interface, such as the toolbar and add-ons manager (about:addons). Firefox uses a default icon unless you provide one. As you move into publishing extensions, an icon is a helpful way for users to identify your extension.

The example's manifest.json tells Firefox that an icon is at "icons/border-48.png".

Create the "icons" directory under the "borderify" directory. Save an icon there named "border-48.png". You could use the one from the example, which is taken from the Google Material Design icon set and used under the terms of the Creative Commons Attribution-ShareAlike license.

If you choose to supply an icon, it should be 48x48 pixels. You could also supply a 96x96 pixel icon, for high-resolution displays, and if you do this, specify it as the 96 property of the icons object in manifest.json, like this:

"icons": {
  "48": "icons/border-48.png",
  "96": "icons/border-96.png"
}

Alternatively, you can supply an SVG file, which Firefox automatically scales as needed. (Tip: If you're using SVG and your icon includes text, use your SVG editor's "convert to path" tool to flatten the text, so that it scales with a consistent size and position.)

Learn more about specifying icons

borderify.js

Finally, create a file called "borderify.js" under the "borderify" directory. Give it this content:

document.body.style.border = "5px solid red";

Firefox loads this script into the pages that match the pattern given in the content_scripts manifest.json key. The script has direct access to the document, just as scripts loaded by the page itself do.

Learn more about content scripts

Trying it out

First, double-check that you have the right files in the right places:

borderify/
    icons/
        border-48.png
    borderify.js
    manifest.json

Installing

In Firefox, open the about:debugging page, click This Firefox, then Load Temporary Add-on, and select any file in your extension's directory.

The extension now installs and remains installed until you restart Firefox.

Alternatively, you can run the extension from the command line using the web-ext tool.

Testing

Now, visit a page under https://www.mozilla.org/en-US/, and you see a red border around the page.

Try experimenting: edit the content script to change the border color, or do something else to the page content. Save the content script, then reload the extension's files by clicking Reload in about:debugging. You see the changes right away.

Learn more about loading extensions

Packaging and publishing

For other people to use your extension, you need to package it and submit it to Mozilla for signing. To learn more, see "Publishing your extension".

What's next?

Now you've had an introduction to the process of developing an extension for Firefox:

• Write a more complex extension
• Read more about the anatomy of an extension
• Explore the extension examples
• Find out what you need to develop, test, and publish your extension
• Take your learning further