← Learn Javascript

Browser Extensions

Tutorials, references, and tips for cross-browser extension development

About Extensions

• Browser extensions are software that add features to a web browser.
• A browser extension is built using HTML, CSS, and Javascript.
• Extensions can use special features of the browser to add useful or even playful functions.
• Follow one of the tutorials below to learn how to build extensions.

Tutorial > Browser Blowup Tutorial

An introduction to browser extensions, starting with the basics and building up to an extension that can detect web trackers and explode web pages.^*

• 0-Introduction (md) - What are browser extensions?
• 1-Hello World! (md) - Write HTML/CSS/JS to create your first extension
• 2-Architecture (md) - Extension architecture, scripts, debugging
• 3-DOM (md) - Browser actions, assets, explosion animation
• 4-Explosion (md) - Report trackers in the console, wrapping up

Tutorial > MDN Web Docs Tutorial

1. What are extensions?
2. Your first extension
3. Anatomy of an extension
4. Building a cross-browser extension
5. Example Extensions (Github)
6. Content scripts

Tutorial > Advanced

• Setting up Chrome Extensions for use with ES6 - Webpack, testing, modules
• Use chrome.storage and storage APIs to persist states across multiple pages.

Sample Browser Extensions

• omundy/sample-extension-messages
• omundy/sample-extension-observer
• omundy/sample-extension-github-tools
• sneakaway-studio/explode-the-web
• sneakaway-studio/stop-slide-scrolling
• sneakaway-studio/tally-extension
• mdn/webextensions-examples

Documentation

• Chrome Getting started guide
• Chrome download, Chrome Web Store, Developer Console, API Reference
• Chromium download
• Firefox Addons Store, Developer Hub, Documentation
• Opera Opera Store, Developer portal
• Brave (publish on Chrome Web Store)

Cross-browser compatibility

• Porting a Google Chrome extension
• Mozilla > Chrome incompatibilities
• Mozilla > Browser support for JavaScript APIs

Publishing

See links above for platforms.

Packaging

1. Zip extension files
   • Chrome: Zip the extension/ directory
   • Firefox: Zip only files inside the extension/ directory
2. Remove hidden files from the Firefox version (see this page for details)
3. Upload to respective web stores (see above)

Working with storage

For an extension to store data that can persist across different web pages and domains you have two options: Use a remote server, or store it locally in the browser.

Web Storage API

• While window.localStorage is easy to use with JS in your own pages, saving data with an extension is different.

Anything you store from your extension content scripts is shared with (and attached to) the user's current web domain. So...

• ✅ Easy to view with Dev Tools (Application > Local Storage)
• ❌ Data does not persist across web pages; attached to the specific domain

Alternately, from an extension background script....

• To share data across different web pages using localStorage you must use messaging between your content and background pages (manifest v3 requires all backend scripts to use service workers), which have a chrome:// URI (thus linked to the extension, not the domain).

• ⚠️ Difficult to view with Dev Tools

• ⚠️ Browser extension ✅ service workers can store data (but content scripts require messaging)

Additionally, for extension development, keep in mind that:

• ⚠️ Data must be serialized / deserialized using JSON.stringify()
• ⚠️ Synchonous (large amounts of data can create latency)
• ❌ Data will not persist if users clear browsing history and data for privacy reasons

Example

localStorage.setItem('myObject', JSON.stringify({"message":"hello"}));

browser.storage and chrome.storage

chrome.storage lets extensions to store data in a location that isn't accessible to normal web pages.

• Can be used from (both!) Browser extension ✅ content scripts and ✅ service workers
• ✅ Asynchronous (Promise-based)
• ✅ Data will persist if users clear browsing history and data for privacy reasons

One caveat, in Chrome, JavaScript APIs are accessed under the chrome namespace. In Firefox and Edge, they are accessed under the browser namespace. But, Firefox supports both the chrome and browser namespaces. You can fix it with

if (typeof browser === "undefined") {
	var browser = chrome;
}

Here is an example of chrome.storage

let obj = { message: 123 }
chrome.storage.local.set({obj})
let results = chrome.storage.local.get('abc')
console.log(results)
//  { message: 123 }

Development

Quick method

1. From chrome://extensions open the service worker for your extension
2. In DevTools, run the following in the console chrome.storage.local.get(console.log)

For ongoing development

1. Install https://github.com/jusio/storage-area-explorer
2. Get your extension id at chrome://extensions
3. Open chrome-extension://<your_extension_id>/manifest.json

IndexedDB

Another option - complex to use unless you have a go-between
https://github.com/localForage/localForage

FAQ & Tips >

FAQ > Is there a hot reload tool for extension development?

Yes! See this StackOverflow answer https://stackoverflow.com/a/56380458/441878

FAQ > What web browsers should I target?

There are many web browser brands, but most are based on just three browser engines "types".

• Blink (part of the Chromium project) is used by Google Chrome, Opera, Brave, and Microsoft Edge
• Gecko used by Firefox
• Webkit used by Safari (and several others including Google Chrome and Firefox for iOS)

FAQ > What are some notable examples of browser extensions?

• Add-Art source
• Catblock source
• Adblock source

FAQ > Issues with CSS and browser extensions

CSS from web pages will affect ("pollute") display properties in your extension, often messing up your own styling. For example, if this rule is set on a page your extension then html that you show in the content scripts will inherit it:

p { color: red; }

FAQ > Issues with CSS and browser extensions

These tips help ensure your code won't inherit other styles (listed in increasing potential to protect your own):

• Use uncommon class and id names. This works unless the styling rules are applied very broadly (like above).
• Wrap all your code within a unique class or id.
• Use !important on all your rules.
• If all else fails, explicitly set a default for every property in your extension.

#uniquePrefix p { color: black !important; }

FAQ > Common Errors and Issues

Uncaught Error: Extension context invalidated.

The error, Uncaught Error: Extension context invalidated, can occur when you update an in-development extension and then interact with a web page without refreshing the page to get the newly updated extension. The issue is that the (now outdated) content scripts injected and running on the page have attempted to access an extension that no longer exists (since it was updated).