Chrome Extensions For Beginners

Getting started with manifest v3

Photo by Firmbee.com on Unsplash

Chrome extensions are awesome tools that can be used to extend one's experience within the Chrome browser. A few weeks ago I got curious about how to create my own Chrome extension and started working on creating my own extension. I wrote about how I go about approaching that project here if you want to check it out. It turns out that the process was much easier than I thought it would be. In fact, you can set up a chrome extension right now within a couple of minutes (it wouldn’t be able to do anything of course).

One thing that tripped me up when I started getting my hands dirty with the project was the fact that Chrome migrated to the v3 manifest whereas a quick search on YouTube will direct you to video tutorials a couple of years old which would be using v2. Although they are very similar, there are a few distinctions that I had to navigate. This guide will give you an overview of how to get started with Chrome Extension development which I wish was available to me when I got started.

In this article I will cover:

• The manifest file — How do I make a Chrome extension?
• Service workers — How do I run background processes?
• Content scripts — How does my extension interact with the current page
• Popup scripts — How can the user interact with my extension?
• Message passing — How do you tie the service worker, content script, and popup together to a cohesive extension application
• Permissions — Why do I keep getting permissions errors?
• Debugging — Why is my console log not working?
• How to navigate the API documentation — What am I even looking at?

The anatomy of a Chrome extension

The manifest file: creating your first Chrome extension
The manifest file is the most important file of this whole operation. Below is a sample manifest.json that Chrome uses to build out your extension.

{
 “name”: “Extension Name”,
 “description”: “Extension description”,
 “version”: “1.0”,
 “manifest_version”: 3,
 “background”: {
     “service_worker”: “background.js”
 },
 “permissions”: [“storage”, “activeTab”, “scripting”],
 “action”: {
 “default_popup”: “popup.html”
 },
 “content_scripts”: [
     {
       “matches”: [“http://localhost:3000/”],
       “js”: [“contentScript.js”]
     }
 ],
 “icons”: {
     “16”: “/images/get_started16.png”,
     “32”: “/images/get_started32.png”,
     “48”: “/images/get_started48.png”,
     “128”: “/images/get_started128.png”
 },
 “options_page”: “options.html”
}

Note that all the other file paths referenced in the manifest should be in the same directory as the manifest file.

This file defines the regular metadata about the extension such as name, description, version number, and icon images as you would expect. Note that the manifest version here is 3. With this, you have all you need for a Chrome extension.

To load your extension to Chrome type chrome://extensions into your search bar and turn on developer mode on the top right of the page.

Click on load unpack and navigate to your project folder (that includes that manifest file and click open) in the windows pop up

Congrats, you have created your first chrome extension.

The scripts: making your extension interactive

After you have created a bare bone basic extension, you will want to give some functionalities to it by running custom javascript.

Service workers

“background”: {
   “service_worker”: “background.js”
}

A service worker is simply a javascript file that is listening to events in the background.

Service workers are the biggest change from the v2 to the v3 manifest which replaces background processes. Background processes were often used to keep a long-term memory in a variable for convenient global access anywhere within the browser.

The catch with service workers is that they are only running when they are called upon and go offline as soon as there is no work left to do. This means that you cannot expect to store a global variable in a service worker and call on it later on. This encourages developers to create event-based extensions and is probably Google’s effort to keep the RAM-hungry Chrome at bay.

The majority of apps should be able to take advantage of this event-based system and using the Chrome storage API for long-term information.

Content scripts

“content_scripts”: [
  {
    “matches”: [“http://localhost:3000/"],
    “js”: [“contentScript.js”]
  }
]

You can also create scripts that get run on specific pages. From this code snippet, the script contentScript will only run if the user navigates to localhost:3000. The official doc outline extensively the different site match patterns here

This is useful, for example, in the case where you have your own website and want to run a script to manage your user experience. One of the things that I used this for is to store global variables inside a pinned tab as a workaround for the background script replacement.

Popup

“action”: {
   “default_popup”: “popup.html”
}

The pop-up is an interface that users use to interact with your extensions. You can look at it as the front end of your extension which is rendered on screen when the user clicks on the extension’s icon on the top right of the Chrome browser. Within the HTML file, you can use scripts as you normally would any other HTML files.

One thing to keep in mind is that script gets unmounted as soon as the popup closes therefore don’t try to store information that you may need long term.

By now you must be asking, but how can you use the popup to interact with the web page? Well, that is where message passing comes in.

Message passing

Since each instance of the extension script runs in a separate process, you need to utilize the messaging API to communicate between scripts. Below is the outline of the architecture.

Source: Chrome API Doc

To find more details on messaging, reference the message passing API documentation. An example code snippet of sending from a content script goes something like this.

chrome.runtime.sendMessage({greeting: “hello”}, (response) => { 
   // handle the response 
   console.log(response);
});

Within the service worker script, you need to intercept this message which looks something like this.

chrome.runtime.onMessage.addListener((request, sender, sendResponse) =>{ 
     // handle the message here
     // respond to the sender
     sendResponse({message: “success”}); 
});
```

Permissions
Another important thing about Chrome extensions is that you must define a permissions parameter for your application. You can access information such as the name or id of the currently active tab through the chrome API. However, by default, you do not have permission to access any of the Chrome API for security reasons and you must define specific permissions you want your extension to be able to use. How do you know which permission you need? Well, I will cover that in the documentation reference section later.

Debugging
Debugging works slightly differently when you are developing the extension. Normally you would inspect the current page that you are on, however, the Chrome script is run within their own separate processes and therefore have their own inspectors.

For service workers, find the inspector on the chrome extensions page.

Content scripts are run on the page itself therefore it logs to the regular page inspector.

To find popup scripts, right-click on the extension icon and inspect it.

Navigating the doc

There are 2 areas within the official doc that I find myself referencing all the time in the Chrome extension doc.

First is the core concept section in which you can find more in-depth information about the other sections that are in this article such as content scripts and message passing. It is also worth noting that each script type may only have direct access to a few specific chrome APIs which can be found near the top of the doc page.

If you need to use a non-accessible Chrome API from a script, use the message passing capabilities to pass a message to a script that would have access to the API you need to use.

The second highly referenced section is the API reference. Whatever you need to do to the browser, just search through this page first to see if there are direct methods for what you are trying to do. As an example, in my extension, I wanted to create a new tab from the popup menu. I would navigate to the tabs API documentation.

On the API page, you will first see the manifest section in which you can find the permissions you need to include in the manifest file to use the API.

In the Summary section, you will be able to find all the methods available within this API. Here, create seems to be what I needed so I would click on that to navigate to the section. Here, you can find all the parameters that you can pass into the method call and custom types are defined for you either directly below or as a link to somewhere within the page.

Conclusion

This article is in no way an extensive resource for Chrome extension development. What I talked about here are just some of the things I believe would be helpful for a complete beginner to get started with Chrome extension development. I hope you find this article helpful and don’t hesitate to share in the comments what you will be creating.

Links

Chrome extension doc: https://developer.chrome.com/docs/extensions/mv3/