Building Browser Extensions

Browser Extensions, at their best, can be pretty awesome. They can add powerful functionality to web browsers.

In the past if one wanted to support multiple web browsers one had to write multiple extensions. These days things have coalesced towards a single system called WebExtensions.

On this page I hope to collect and simplify what most of us need to know to create a WebExtension.

The WebExtensions API

The WebExtensions API provides a large number of ways to hook into web browsers. We’ll focus only on some of the most commonly used APIs (and the ones I’m most interested in) but you can find a full WebExtensions API reference on MDN.

You’ll also want to take a look at the compatibility chart on MDN to see which browsers have implemented which portions of the API.

  • alarms – Schedule code to run.
  • bookmarks – Create bookmarks, retrieve existing, edit, remove, organize, etc.
  • browserAction – Add a button to the browser toolbar.
  • browserSettings – Allows overriding a number of global browser settings.
  • browsingData – Allows for clearing data such as the cache, cookies, downloads, local storage, etc.
  • commands – Listen for the user executing commands you have registered.
  • contentScripts – Dynamically add/remove scripts to be inserted into pages.
  • cookies – Get, set, and monitor cookies.
  • events – Interact with certain browser events.
  • extension, extensionTypes – Utilities relating to the extension.
  • find – Find text in web page.
  • history – Interact with browser history.
  • i18n – Functions to help with internationalization.
  • identity – Integrates with OAuth2 providers.
  • management – Manage installed add-ons.
  • menus (aka contextMenus) – Allows for modifying browser menus.
  • notifications – Displays OS level notifications.
  • omnibox – Customize behavior of omnibox.
  • permissions – Request additional permissions at runtime.
  • runtime – Allows communicating within one’s extension, to other extensions, and with native applications.
  • search – Executes search with specific search engine.
  • sessions – Allows one to list and restore tabs and windows.
  • sidebarAction – Get and set properties of an extension sidebar.
  • storage – Store, retrieve, and monitor data.
  • tabs – Interact with browser tabs.
  • webNavigation – Add event listeners to the various stages of navigating.
  • webRequest – Add event listeners to the various stages of HTTP requests.
  • windows – Interact with browser windows.

Other APIs include clipboard, contextualIdentities, devtools (.inspectedWindow, .network, .panels), dns, downloads, idle, pkcs11, privacy, proxy, theme, topSites, types, and so on.

The Google Angle

Unfortunately, Google is a bit rogue on the WebExtensions front. You’ll need to use Mozilla’s polyfill to ensure the extension works in Chrome without changes.

You could design the extension to work with Chrome since Mozilla understands the Chrome API calls. This latter method isn’t ideal from a standardization perspective.


Example Code

Helper Code

  • webext-options-sync – Stars: 61 – Updated: 6/2020 – Reviewed: 6/2020
    • Allows one to easily set (for options) defaults, add auto-load/save, and sync between browsers.
  • TinyWebEx – Stars: 6 – Updated: 2/2020 – Reviewed: 6/2020
    • Logging, syncing, localizing, etc. helpers for extensions.
  • UI Code for Chrome Extensions – Stars: 99 – Updated: 6/2018 – Reviewed: 6/2020
    • For options/settings page.
  • Options Page for Chrome Extensions. – Stars: 48 – Updated: 10/2018 – Reviewed: 6/2020
    • Aids in creating a options page for an extension.

Starters / Boilerplate

Open Source Extensions

See our separate page with a lengthy list of open source extensions to learn from, use, and/or contribute to.


See our separate page on building extensions with React.