webextension-polyfill
A lightweight polyfill library for Promise-based WebExtension APIs in Chrome.
What is webextension-polyfill?
WebExtension `browser` API Polyfill is a JavaScript library that provides a Promise-based interface for WebExtension APIs, allowing developers to write extensions that work seamlessly on Chrome and Firefox. It polyfills the standardized `browser` API in Chrome, enabling the use of modern async/await patterns and eliminating callback hell. The library ensures cross-browser compatibility while maintaining a minimal footprint.
Extension developers building cross-browser web extensions who want to use the modern Promise-based WebExtension API. It's particularly useful for teams targeting both Chrome and Firefox with a single codebase.
Developers choose this polyfill because it provides a standardized, future-proof API surface, reduces code complexity by replacing callbacks with Promises, and is officially maintained by Mozilla with robust browser support. It eliminates the need to write browser-specific code for basic API interactions.
Overview
A lightweight polyfill library for Promise-based WebExtension APIs in Chrome
Use Cases
Best For
- Writing Chrome extensions using Firefox's Promise-based `browser` API
- Developing cross-browser extensions with a single codebase
- Modernizing legacy Chrome extensions with async/await patterns
- Simplifying extension code by eliminating callback nesting
- Ensuring compatibility with the W3C Browser Extensions standard
- Integrating WebExtension APIs with module bundlers like webpack
Not Ideal For
- Extensions targeting only Chrome with no Firefox compatibility needs, as the polyfill adds unnecessary overhead
- Projects relying heavily on Chrome-specific APIs not part of the WebExtension standard, which the polyfill doesn't cover
- Teams that prefer or require callback-based APIs without Promises, since the polyfill enforces Promise usage and drops callback support
- Developers needing polyfills for experimental or non-standard browser extension features, as it focuses solely on the W3C standardized API surface
Pros & Cons
Pros
Replaces Chrome's callback pattern with a consistent Promise-based interface, enabling modern async/await syntax and reducing code complexity, as demonstrated in the README examples.
Officially supports Chrome and Firefox with automated tests, and unofficially works on Opera and Edge (>=79), allowing a single codebase for multiple browsers.
Acts as a NO-OP on Firefox where the `browser` API is native, minimizing performance impact and ensuring seamless integration, as stated in the supported browsers section.
Works with webpack, browserify, and ES6 modules, facilitating modern development workflows, with detailed setup instructions in the README.
Compatible with community-maintained type definitions like @types/webextension-polyfill, enhancing developer experience with auto-completion and type safety.
Cons
Does not polyfill API methods or options missing on Chrome but available on Firefox, requiring extensions to implement runtime feature detection and additional workarounds, as explicitly noted in the philosophy.
The Promise-based APIs do not support callback parameters, which can break existing Chrome extension code that relies on callbacks, a known limitation documented in the README.
Only wraps APIs listed in the metadata file; unrecognized methods remain callback-based, potentially causing inconsistencies and requiring manual handling.
Requires explicit injection for dynamically-loaded content scripts via separate executeScript calls, adding complexity compared to static manifest declarations.
Frequently Asked Questions
Related Projects
ExtPayThe JavaScript library for ExtensionPay.com — payments for your browser extensions, no server needed.
webext-options-syncHelps you manage and autosave your extension's options.
More…WebExtension packages for every need
redux-webextRedux for WebExtensions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.