Webextension polyfill for cross-browser compatibility

In the last post, we got our Timekeeper webextension to work in the background, but doing so made it incompatible with Chrome. Chrome APIs are a little different from Firefox’s browser APIs. In this post we will get our extension working on both Chrome and Firefox using a polyfill.

The webextension-polyfill#

From the Github repository’s README:

This library allows extensions that use the Promise-based WebExtension/BrowserExt API being standardized by the W3 Browser Extensions group to run on Google Chrome with minimal or no changes.

Thank you once again, Mozilla!

Adding the polyfill library to our project#

As the extension we are building is quite simple, merely including the polyfill JS file should suffice. Download the browser-polyfill.js file from unpkg.com .

  • Add the file to the src/ folder.
├── background
│   └── index.js
├── browser-polyfill.js
├── icons
│   ├── icon-48.png
│   └── icon-96.png
├── manifest.json
└── popup
    ├── index.html
    ├── main.js
    └── styles.css
  • Include the file in a <script> tag in popup/index.html. This will load the polyfill in the popup.
     <button class="bg-pink" id="btn-resume">RESUME</button>
     <button class="bg-black" id="btn-reset">RESET</button>
   <script type="application/javascript" src="../browser-polyfill.js"></script>
   <script src="./main.js"></script>
  • Add the file to the background scripts in manifest.json. We need to polyfill every part of the extension separately.
     "default_popup": "popup/index.html"
   "background": {
     "scripts": [

The complete code is available in the 03-polyfilled folder of the same repo . Our webextension is complete. In the next post we will improve our webextension development workflow and look into bundling, linting and packaging.