WebExtension Polyfill Globalizer

0.10.1-1 · active · verified Tue Apr 21

webextension-polyfill-global is a utility package designed to make Mozilla's `webextension-polyfill` readily available as a global `browser` object within web extensions, even when using bundlers like Webpack or Parcel. It addresses a known issue where the upstream `webextension-polyfill` can be challenging to import as a true global polyfill, often requiring manual `import()` calls or complex bundler configurations. This package simplifies that process by directly making the polyfill globally accessible upon import. The current stable version is 0.10.1-1. As a wrapper, its release cadence is typically tied to updates in the core `webextension-polyfill` or improvements in its global registration mechanism, though it has seen consistent maintenance. Its key differentiator is its singular focus on providing a simple, fire-and-forget global registration for the browser API, streamlining development for extension authors who prefer the `browser` global over explicit imports everywhere.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'tabs') or 'browser' is undefined
```
cause The webextension-polyfill-global import was not executed, or not executed early enough, before attempting to access the `browser` global.

fix Ensure `import 'webextension-polyfill-global';` is at the very top of your entry file (e.g., background.js, popup.js) or any script where the global `browser` object is needed.
```
TS2304: Cannot find name 'browser'.
```
cause TypeScript compiler cannot find the global type definition for 'browser'.

fix Install the official TypeScript types: `npm install @types/webextension-polyfill -D`.

Warnings

gotcha This package is primarily a wrapper for `webextension-polyfill`. Ensure `webextension-polyfill` is installed in your project, as this wrapper expects its functionality to be available.
Fix: Run `npm install webextension-polyfill` alongside `webextension-polyfill-global`.
gotcha When using TypeScript, you need to install `@types/webextension-polyfill` as a dev dependency to get global type definitions for the `browser` object, even though this package provides the runtime global.
Fix: Run `npm install @types/webextension-polyfill -D`.
gotcha The purpose of this package is to make `browser` available globally. If your project explicitly imports `browser` from `webextension-polyfill` (e.g., `import { browser } from 'webextension-polyfill';`), this package might create redundancy or conflict if not managed carefully. Choose one approach.
Fix: Decide on a single strategy: either use this package for a global `browser` object and avoid explicit imports, or manage `webextension-polyfill` imports directly without `webextension-polyfill-global`.

Install

npm install webextension-polyfill-global npm
yarn add webextension-polyfill-global yarn
pnpm add webextension-polyfill-global pnpm

Imports

Side Effect Import
wrong:
```
import { browser } from 'webextension-polyfill-global';
```
correct:
```
import 'webextension-polyfill-global';
```
This package is imported for its side effects, which register the `browser` global. It does not export any named symbols directly.

Quickstart

Demonstrates how to import the polyfill and immediately use the global `browser` API.

import 'webextension-polyfill-global';

// Now, the 'browser' global API is available

async function getActiveTabUrl() {
  if (typeof browser !== 'undefined' && browser.tabs) {
    try {
      const tabs = await browser.tabs.query({ active: true, currentWindow: true });
      if (tabs.length > 0) {
        console.log('Active tab URL:', tabs[0].url);
        // Example: Send a message to the active tab's content script
        await browser.tabs.sendMessage(tabs[0].id, { greeting: 'hello from background' });
      }
    } catch (error) {
      console.error('Error getting active tab URL:', error);
    }
  } else {
    console.warn('WebExtension polyfill or browser API not available.');
  }
}

getActiveTabUrl();

view raw JSON →