10 Tips about WebExtension

In this article, we forego detailed introduction of WebExtension to share some tips about how to get started developing a browser extension using WebExtension.

What is WebExtension?

WebExtension is a cross-browser system for developing extensions in modern browsers like Google Chrome, Opera and MS Edge.

We are encourage people to leverage WebExtension in your extension development. It’s growing rapidly, supports lots of new APIs and is highly compatible with Google Chrome!

Here is our top ten tips for WebExtension and browser extension development:

1. Browser Extension Structure

A browser extension consists of three main parts: Popup, Content script and Background scripts.

• Background scripts: A long-running program. It will be executed once after extension loaded and stay loaded until the extension is uninstalled.
• Content scripts: For enhancing the current web page. Browser extensions allow you to inject Javascript/CSS for specific web pages.
• Popup: Clicking the icon in the top right corner of the browser will open up this popup menu

Remember to read Anatomy of an extension before you start to develop with WebExtension :)

2. Browser compatibility

Please keep this document handy when you are developing with WebExtension.

Currently, lots of APIs are not compatible for all supported browsers. When you are using any APIs, please understand the compatibility for each browser.

3. Permissions

It’s one of the important parts in browser extension development. There’re a lots of APIs or functions that need permissions, such as cookies, storage, tabs etc.

You can configure permissions using the permission key in the manifest.json.

4. Promise-based API

Actually, Promise is supported in most of WebExtension APIs, for example:

browser.tabs
  .query({currentWindow: true, active: true})
  .then((tab) => { ... }, (error) => { ... });

However, the above code can’t work on Google Chrome. But don’t worry, webextension-polyfill can save your life!! Most people use it to leverage Promise-based APIs in Google Chrome.

About the usage of this polyfill, Mozilla recommends that you can either include it in the HTML or use browser.tabs.executeScript to inject it. Anyway, you can still use it in a modern way:

$ npm install webextension-polyfill --save

Then, in the entry of scripts:

global.browser = require('webextension-polyfill');

5. Content scripts

There’s a common question by people developing with Content scripts for the first time.

Can I use third party libraries in the Content scripts which are already used in the web page without resulting in conflicts?

The answer is Yes definitely. You can use any libraries in the Content scripts, absolutely independent from web page.

There’re two way to inject your script into web page:

• Declaratively: Use the content_scripts key in the manifest.json
• Programmatically: Use tabs.executeScript API

6. Storage

As we know, we have localStorage or even the sessionStorage. However, we don’t encourage using localStorage for extension development. Instead, WebExtension has a storage system that is similar to localStorage. If the data you want to store is about extension, save them via browser.storage.local.

Reference: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage

7. Don’t forget localization

WebExtensions offer an i18n system for you to easily internationalize your extension.

Just create respective local dirs in the _locales folder in the root:

-_locals
    |-en
    | └-messages.json
    |-ja
    | └-messages.json
    └-id
      └-messages.json

Then define your message in the messages.json:

{
  "extensionName": {
    "message": "Hello Extension",
    "description": "Extension Name"
  }
}

Finally, get the message in your program:

browser.i18n.getMessage('extensionName'); // It's synchronize call!!

The i18n system not only gives you a simple way to customize the different localizations but also internationalizing the manifest.json or dealing with locale-dependent CSS. You can check this if you are interested to learn more.

8. Google Analytics Integration

You can use GA or any third party tool to collect some data. However, if you want to inject and use GA scripts in Content scripts, it’s not allowed in browsers by default. There’s still a workaround, but we will discuss it another time.

Anyway, you can also call the GA APIs in the Background scripts:

There’s not too much concern when you call GA APIs or other third party services in the Background scripts so that you can use browser.runtime.sendMessage to notify there’s an action in the Content scripts or Popup, then send a request to GA in Background scripts.

9. WebExtension with React/Redux

This tip can be another post on its own in the future. In this section, we will highlight two points you may care about:

About Redux

There are two libraries you can use to leverage Redux in browser extension development: react-chrome-redux and redux-webext. However, both libraries still use chrome namespace instead of browser, which means they do not follow WebExtension standards.

After investigation, we prefer to use react-chrome-redux for two reasons:

• They are open to change to WebExtension, react-chrome-redux#65
• Architecture is much simpler than redux-webext

About Popup

There are two things you should know:

• The popup script will be executed every time the popup opens
• The popup HTML will be preserved after popup close.

If you use React.js and based on above points, the componentWillMount must be called every time when popup open. Make sure you are careful when component mounting. In addition, you can consider cleaning specific DOM elements in componentWillUnmount to prevent users from seeing the previous residual contents when they open popup the next time.

10. Debugging

Debug Content scripts

It’s every easy to debug the content scripts because content scripts will be injected into the web page, so you can debug it just like how you debug the web page!!

Debug Background scripts

In the Chrome, open chrome://extensions, find your unpacked extension and click the “background page” link

In the Firefox, open about:debugging, find your unpacked extension and click the “Debug” link

Debug Popup

You can right click on the popup menu to enable the dev tool, but popup menu usually close when focus out so that you may feel annoying about that.

Don’t worry, there’re quick way to debug it:

For the Chrome, go to:

chrome-extension://{EXTENSION_ID}/{POPUP_HTML_PATH}

You can find the EXTENSION_ID like the following red block:

For the Firefox, it got little different, we highly recommend you to read this document.

Conclusion

There are lots of tips about WebExtension we can share later. In near future, we will have another posts to introduce how we integrate develop WebExtension with React/Redux.

Anyway, start to use WebExtension in your browser extension development in 2018!!