Getting Started with Web Extensions - Web Extension Tutorial

Alright let’s get started with our web extension

And what could be a better place to start than checking the documentation from Chrome

If you visit developer.chrome.com you can read everything about Chrome extensions

Let’s look at the Get Started Guide I won’t read all this but immediately jump into the manifest

The manifest file

Manifest JSON is the configuration of our web extension and it tells the browser about our extension’s name what permissions we are requesting what files are we using and a lot of other things

You know what Let’s create our own

I’ll create my project and let’s add the manifest.json file in the root of our project

Now I’ll just copy the default values from the developer page

Let’s see what’s there

The version is 3 Chrome announced Manifest version 3 a couple of years ago and by now they only accept extensions that follow this version 3 pattern

You don’t really need to worry much about earlier versions because whatever we are building will follow the latest standards and all the documentations are explaining this

The name is obvious with the name of our extension so let me change it to tabnotes

The version number is 1.0.0 and the description should be well this will be a simple Chrome extension with a popup because that’s all I’m going to do now

To do that well we can look here Popup with permission

It says “Action default popup equals popup.html”

So why don’t I just paste it here

And permissions let’s add it although I don’t need the active tab either

{
  "manifest_version": 3,
  "name": "TabNotes",
  "version": "1.0.0",
  "description": "A simple Chrome extension with a popup",
  "action": {
    "default_popup": "popup.html"
  },
  "permissions": []
}

Okay I have a manifest.json and I’m talking about popup.html so let me create that too

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>TabNotes Popup</title>
</head>
<body>
  <h1>TabNotes</h1>
</body>
</html>

Looking good

So I have the bare minimum and it seems like I defined popup.html in the manifest.json and I created the file

Testing your extension

Now let’s see how can I test my very minimal extension

Well if you go to extensions manage extensions which by the way if you use it frequently you can remember the path chrome://extensions

Then you can turn on developer mode

I don’t know if you have ever noticed that it’s here but this little toggle gives you super user privileges

And you see there is a button now called load unpacked

I can open my extension tabnotes and select

And boom here we have our extension

It’s extremely basic

It has the name the version number I didn’t add any icon and the description plus an ID

I also pinned the extension here when you click on the puzzle icon which let me just pin it

And indeed when I click on the icon of the extension it opens the popup TabNotes

You can congratulate yourself

You created the very first working version of a Chrome extension

It wasn’t that hard was it

Adding a background script

But of course having a plain popup is quite useless

Let’s go a step further and do something that only Chrome extensions can do such as detecting which tab is open

To do that we will start working with background script or service workers

In my manifest reference I click on background

And I can see that there is this additional part called background

I can call it service worker but why not call it background

And just create the file

And in this file I can set up listeners to any kind of browser events

In this case it will be when a tab is changed

So chrome.tabs.onActivated.addListener

And it’s an async function with activeInfo which contains all the information about the tab that has been activated

Now let’s fetch the tab

Call this tab equals await chrome.tabs.get

Don’t worry if these don’t make sense because throughout the course we will come back to everything

I just want to show you what a background script is

Let’s log Tab activated

It’s this simple

chrome.tabs.onActivated.addListener(async (activeInfo) => {
  const tab = await chrome.tabs.get(activeInfo.tabId);
  console.log('Tab activated:', tab);
});

And I have the background JS service worker so I can come back to my extension

Now I make changes so I click on the refresh button to reload my extension

And look I have something new showing up

Inspect service worker

Again this is only visible because I have the developer mode enabled

I click on it

And I have DevTools

I’m used to seeing DevTools but this one is a bit special because look it shows it’s logging from background JS

Okay so what happens if I click on various tabs

Let’s say I open Wikipedia

Oh look at that

I logged out every single tab change and the details of that tab change such as an ID of a tab which is actually what I used when I was retrieving the information

Permissions

Now when an extension is working with tabs it must request special permissions from the users so they can be well informed when they are installing your extension

To do that we need to add the permissions in the manifest JSON

Here I can just add tabs

{
  "manifest_version": 3,
  "name": "TabNotes",
  "version": "1.0.0",
  "description": "A simple Chrome extension with a popup",
  "action": {
    "default_popup": "popup.html"
  },
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["tabs"]
}

When you check the extension’s details you can see what permissions are required by this Chrome extension written in a way that’s easy to understand for the end users

Debugging

Now we saw that we can open the DevTools for the background script but can we do the same for the popup

Of course it’s even simpler

You just open the popup and just like you’re used to in your regular browser right-click and inspect

As you can see we’re inspecting chrome-extension://the ID of the extension/popup.html

The problem

Now writing extensions as we did is a little bit painful because every time we make a change in the code base we need to refresh the extension which is obviously not the most comfortable way to work on a code base

Also this is very Chrome specific

However Chrome and Firefox and Safari and Edge are sharing the same code base

So theoretically we should be able to build an extension for all other browsers at the same time

I say theoretically because if you noticed in the background script I’m referring to chrome.tabs.onActivated

So this is very Chrome specific

But luckily there is a tool out there that can help us with cross browser extension development

So we only need to code it once and we can distribute it to many platforms

Plus we get a lot of nice additions during the development process

Chrome docs

Before we move on I want to guide you again to the Chrome extension documentation which is truly amazing

You can read a lot of guides read about APIs references permissions and they also built a lot of sample extensions

So if you want to learn about I don’t know cookies you can filter down and check cookie clearer and the whole code base on GitHub

What’s next

You built your first extension It has a popup and a background script

The current setup works but it’s not optimal for real development

Next we’ll improve this with modern tooling