webextension-browser-proxy allows extensions written with standardized (https://browserext.github.io/browserext/) Promise based WebExtension API to work without modification in Chrome/Chromium. The latter use a callback based API.
You can download directly polyfill.js or you can clone this repo and check signauture's commit. Public Key from https://raffaeleflorio.github.io or https://pgp.mit.edu).
Then you have to include polyfill.js before any browser APIs are used.
For background scripts or content_scripts add polyfill.js entry in manifest.json:
// ...
"background": {
"scripts": [
"path/to/polyfill.js",
"background_script1.js",
"background_script2.js",
// ...
]
},
"content_scripts": [{
// ...
"js": [
"path/to/polyfill.js",
"content_script1.js",
"content_script2.js",
// ...
]
}]
// ...For HTML files include it with script tag before any script that use browser API is used:
<!DOCTYPE html>
<!-- ... -->
<script src="path/to/polyfill.js"></script>
<script src="other_script1.js"></script>
<script src="other_script2.js"></script>
<!-- ... -->
</html>Then you can use Promise based API.
It has been tested on Chrome/Chromium browser, with these Promise based extensions:
- qubes-url-redirector
- Mozilla WebExtension examples (some extensions aren't compatible because of some Firefox specific APIs)
polyfill.js is an IIFE. It defines browser as Proxy of chrome ([0]). Furthermore it adds a isPolyfilled property to the browser object.
The Proxy handles three cases when a browser's property (or nested object's property) is accessed ([1]):
- If the property is an object, it returns a Proxy with
handler([4]) as handler. - If the property is a function, it returns a function ([2]) (read below).
- Otherwise it returns the target property.
The returned function try to calls the target function in this way:
- If the target function accepts a callback, it returns a Promise resolved by [3].
- If the target function accepts (or not) some parameters, it returns the target function returned value.
[0] = polyfill.js#L46
[1] = polyfill.js#L2
[2] = polyfill.js#L7
[3] = polyfill.js#L14
[4] = polyfill.js#L5