How to develop a web extension for browsers?

Introduction

The web extension is a software plugin that you install into your web browser (e.g. Chrome, Firefox, and Edge) to enhance its primary functionalities. As its name suggests, web extension inherits most of the web technologies such as (1) Website Content Manipulation — allowing you to change, remove, and add content for the website, (2) Local Database Storage — allowing you to save any data on the user’s computer, and even (3) Geolocation Tracking — allowing you to track the user’s geolocation with x-y-z coordinates.

Refer to the complete list here: https://developer.chrome.com/docs/extensions/mv2/declare_permissions/

With so many technologies involved, learning web extension development may seem like a daunting task. It is actually not difficult at all. If you have learned programming languages such as HTML and Javascript before, you already know 70% of web extension development. The remaining knowledge gap that you have to bridge is to understand its core concepts (i.e. inner-workings).

Setting the context

To guide you through this tutorial, I will be using my open-source project (Removeit) as the primary reference. Removeit is a web extension that allows users to delete any HTML element from the website using the shortcut key (ctrl + alt + click), and undo any changes from the menu. I have chosen this project, as it covers all the core concepts for web extension development, allowing readers to glean greater insights and understanding of this subject.

Refer to the complete source code here: https://github.com/ohyicong/removeit-chrome-extension

The following figures show you the core functionalities of Removeit.

Figure 1: Shows how to delete the “Doctor John” panel from the website.

Figure 2: Shows that the “Doctor John” panel has been deleted.

Figure 3: Shows how to undo the changes.

Understanding the core concepts

For starters, there are 4 core concepts that you need to understand before diving into web extension development.

(1) Manifest: This is a JSON file that allows you to specify the basic information for your web extension. Some of the common information that you should include are the manifest version, name, logo, scripts, and permissions.

Choosing the right manifest version is an important step, as it determines your development methodology and web supportability. There are currently three manifest versions and here are their current status: 1 (deprecated), 2 (stable), 3 (beta). For this article, I will be using manifest version 2 as version 3 is still in its infancy and lacks supportability for many essential functions and web browsers. I will do an article on manifest version 3 subsequently once it has been stabilised.

Here is a snippet of the manifest.json file for this web extension:

{
  "manifest_version": 2,
  "name": "removeit",
  "version": "0.1.3",
  "description": "Remove html elements from your browser.",
  "icons": { "128": "./images/remove_it_logo.png" },
  "browser_action": {
    "default_popup": "popup.html"
  },
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["js/jquery-3.5.1.min.js", "js/jquery-ui.min.js", "content.js"]
    }
  ],
  "permissions": ["storage", "tabs", "webNavigation"]
}

(2) Popup: This is an HTML + Javascript file included in most web extensions that serves as a menu page for users to interact with your program. It is located at the top right-hand corner of the browser and activated through a mouse click.

For this web extension, the popup is responsible to track the number of HTML objects removed from the webpage and allow users to undo the changes where necessary.

Figure 4: Shows the popup menu

(3) Content: This is a Javascript file that allows your program to interact with the user’s web page. It inherits all the important web technologies such as DOM manipulation and event listeners, allowing you to listen to user interaction and change web content accordingly.

For this web extension, the content script is responsible to listen to the “ctrl + alt + click” event and delete the selected HTML object.

Figure 5: Shows how to delete the “Doctor John” panel from the website.

(4) Background: This is a Javascript file that listens to browser events such as the user interacting with the URL bar, opening or closing the browser tab, and updating to the browser data storage.

For this web extension, the background script is responsible to listen for any changes to the database and update the badge notification to show the number of removed HTML objects.

Figure 6: Shows the number of removed HTML objects from the web page.

Architecture

After understanding the core concepts, let’s see how they can interact with each other to create a comprehensive web extension.

As mentioned in the previous section, all the core components are technically isolated as shown below.

Figure 7: Shows how the core components are working in insolation

To allow the various core components to talk to each other, we have to use the message API.

Figure 8: Shows how the core components can interact with each other with the Message API

Now let us do one example.

For the “undo” function, it involves clicking the “undo” button on the popup menu and send a message to the content script to update the user’s web page. The following are the code snippets to enable this communication.

On the popup menu script, it will send a “undo” message to the content script:

//function to undo last removed item
$("#undoButton").click(() => {
  if (numberOfRemovedElement > 0) {
    chrome.tabs.query(query, (tabs) => {
    chrome.tabs.sendMessage(tabs[0].id, { action: "undo" });
  });
}});

On the content script, it will have a message listener to respond to the “undo” message:

//listen to message from popup.js
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action == "undo") {
    console.log("content.js undo clicked");
    //undo removed element
    undoElement();
    //save removed elements to storage
    setRemovedElementsToStorage();
  } 
});

You will be able to achieve the following result!

Conclusion

By understanding all these concepts, you will be able to create your own web extension! Go on and make an impact on the world :)

If you are unsure how to use the code, you can refer to my Youtube video here.