Chrome API using promises.
Note: I'm no longer adding features to this library (only bug fixing). You can check other alternative libraries at the end of this file.
Use npm
npm install chrome-promiseOr yarn
yarn add chrome-promiseOr download chrome-promise.js file.
You can include it in your HTML like this:
<script src="chrome-promise.js" data-instance="chromep"></script>Or you can use ES2015 import statement:
import chromep from 'chrome-promise';It supports Chrome 34 or higher, but it should work in older versions. Create an issue if it doesn't work for your version.
Use local storage.
chromep.storage.local.set({foo: 'bar'}).then(function() {
alert('foo set');
return chromep.storage.local.get('foo');
}).then(function(items) {
alert(JSON.stringify(items)); // => {"foo":"bar"}
});Detect languages of all tabs.
chromep.tabs.query({}).then((tabs) => {
const promises = tabs.map(tab => chromep.tabs.detectLanguage(tab.id));
return Promise.all(promises);
}).then((languages) => {
alert('Languages: ' + languages.join(', '));
}).catch((err) => {
alert(err.message);
});If you are testing with node, you can provide a mock for the chrome API (sinon-chrome is a good choice) using the constructor.
const ChromePromise = require('chrome-promise/constructor');
const chrome = require('sinon-chrome');
const chromep = new ChromePromise({ chrome });The constructor accepts an options parameter with the following properties:
-
chrome: the chrome API object. By default (or when null or undefined are used), it is the 'chrome' global property. -
Promise: the object used to create promises. By default, it is the 'Promise' global property.
This library is not a replacement of the chrome api.
It should be used only for functions that have a callback.
// this returns a rejected promise (because a callback is added to getManifest)
chromep.runtime.getManifest();
// this works
chrome.runtime.getManifest();When there's a callback with multiple parameters, the promise will return an array with the callback arguments.
chromep.hid.receive(4).then(function(args) {
const reportId = args[0];
const data = args[1];
console.log(reportId, data);
});
// Using babel or chrome >= 49
chromep.hid.receive(4).then(([reportId, data]) => {
console.log(reportId, data);
});Only APIs that are enabled in the manifest will be available in the ChromePromise instance.
If the API is undefined, first check the permissions in the manifest.json of your project.
// manifest.json
{
"permissions": [
"tabs"
]
}
// main.js
console.log(typeof chromep.tabs) // "object"
console.log(typeof chromep.bookmarks) // "undefined"If you are using babel or chrome ≥ 55, you can use async/await to achieve this.
async function main() {
await chromep.storage.local.set({foo: 'bar'});
alert('foo set');
const items = await chromep.storage.local.get('foo');
alert(JSON.stringify(items));
}
main();
// try...catch
async function main2() {
try {
const tabs = await chromep.tabs.query({});
const promises = tabs.map(tab => chromep.tabs.detectLanguage(tab.id));
const languages = await Promise.all(promises);
alert('Languages: ' + languages.join(', '));
} catch(err) {
alert(err);
}
}
main2();If you are not using babel and you need to support chrome ≥ 39, it can be done with generator functions. Using the methods Q.async and Q.spawn from the Q library, the previous examples can be rewritten as:
Q.spawn(function* () {
yield chromep.storage.local.set({foo: 'bar'});
alert('foo set');
const items = yield chromep.storage.local.get('foo');
alert(JSON.stringify(items));
});
// try...catch
Q.spawn(function* () {
try {
const tabs = yield chromep.tabs.query({});
const promises = tabs.map(tab => chromep.tabs.detectLanguage(tab.id));
const languages = yield Promise.all(promises);
alert('Languages: ' + languages.join(', '));
} catch(err) {
alert(err);
}
});
// promise.catch
Q.async(function* () {
const tabs = yield chromep.tabs.query({});
const languages = yield Promise.all(tabs.map((tab) => (
chromep.tabs.detectLanguage(tab.id);
)));
alert('Languages: ' + languages.join(', '));
})().catch(function(err) {
alert(err);
});You can also use the co library instead of Q.
