{"id":15930,"library":"webextension-polyfill-global","title":"WebExtension Polyfill Globalizer","description":"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.","status":"active","version":"0.10.1-1","language":"javascript","source_language":"en","source_url":"https://github.com/fregante/webextension-polyfill-global","tags":["javascript","register","global","webpack","parcel","web extension","webext","typescript"],"install":[{"cmd":"npm install webextension-polyfill-global","lang":"bash","label":"npm"},{"cmd":"yarn add webextension-polyfill-global","lang":"bash","label":"yarn"},{"cmd":"pnpm add webextension-polyfill-global","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package wraps and makes available the functionality of `webextension-polyfill`.","package":"webextension-polyfill","optional":false},{"reason":"Provides TypeScript type definitions for the global `browser` object. Required for TypeScript projects.","package":"@types/webextension-polyfill","optional":true}],"imports":[{"note":"This package is imported for its side effects, which register the `browser` global. It does not export any named symbols directly.","wrong":"import { browser } from 'webextension-polyfill-global';","symbol":"Side Effect Import","correct":"import 'webextension-polyfill-global';"}],"quickstart":{"code":"import 'webextension-polyfill-global';\n\n// Now, the 'browser' global API is available\n\nasync function getActiveTabUrl() {\n  if (typeof browser !== 'undefined' && browser.tabs) {\n    try {\n      const tabs = await browser.tabs.query({ active: true, currentWindow: true });\n      if (tabs.length > 0) {\n        console.log('Active tab URL:', tabs[0].url);\n        // Example: Send a message to the active tab's content script\n        await browser.tabs.sendMessage(tabs[0].id, { greeting: 'hello from background' });\n      }\n    } catch (error) {\n      console.error('Error getting active tab URL:', error);\n    }\n  } else {\n    console.warn('WebExtension polyfill or browser API not available.');\n  }\n}\n\ngetActiveTabUrl();\n","lang":"typescript","description":"Demonstrates how to import the polyfill and immediately use the global `browser` API."},"warnings":[{"fix":"Run `npm install webextension-polyfill` alongside `webextension-polyfill-global`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Run `npm install @types/webextension-polyfill -D`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The webextension-polyfill-global import was not executed, or not executed early enough, before attempting to access the `browser` global.","error":"TypeError: Cannot read properties of undefined (reading 'tabs') or 'browser' is undefined"},{"fix":"Install the official TypeScript types: `npm install @types/webextension-polyfill -D`.","cause":"TypeScript compiler cannot find the global type definition for 'browser'.","error":"TS2304: Cannot find name 'browser'."}],"ecosystem":"npm"}