← 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)

Sharing data in extensions

Options for storing and accessing extension data across different web pages and domains:

1. Pass data between contexts using sendMessage (action > background, etc.)
   • ⚠️ Data does not persist, so only good for temporary information
2. Set/get data locally in the browser
   • ⚠️ Data persists but only available to the user
   • localStorage (e.g. Web Storage API) ⚠️ requires using background
   • chrome.storage (a.k.a. browser.storage) ✅ built for extensions
3. Send/receive from a remote server
   • ⚠️ Most difficult, but can be seen by everyone

localStorage vs. chrome.storage

localStorage

Saving extension data with localStorage is different than saving from a web page.

• ⚠️ Content scripts must use sendMessage to send data to background to store
• ⚠️ Data must be serialized / deserialized using JSON.stringify()
• ✅ Easy to view with Dev Tools (Background > Application > Local Storage)
• ⚠️ Synchonous (large amounts of data can create latency)
• ❌ Data will not persist if users clear browsing history and data for privacy reasons
• ❌ Data you store from your extension content scripts is attached to the user's current web domain.

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

• Examples: tally-api/storage

chrome.storage

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

(async function(){ // async iife wrapper
	let obj = { abc: 123 }
	await chrome.storage.local.set(obj).then(() 
		=> console.log("Value is set") );
	chrome.storage.local.get(["abc"]).then((result) => {
		console.log(results) //-> { abc: 123 }
	});	
});	

• Examples: omundy/sample-extension-web-tools

chrome.storage

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 and chrome.storage namespaces. You can fix it with

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

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).

FAQ > Accessing pages

• Content and background pages have a chrome:// URI