Skip to content
Promises for chrome JavaScript APIs used in extensions and apps.
Branch: master
Clone or download
Latest commit ad5813f Jan 23, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
e2e-app Fix system permission requests Apr 2, 2018
e2e-pup
test
type-definitions
.gitignore Add typescript definitions. Fixes #11 Sep 17, 2017
.travis.yml Change protractor to puppeteer Mar 18, 2018
LICENSE
README.md
bower.json
chrome-promise.d.ts Fix type definitions for nested apis. Fixes #14 Sep 25, 2017
chrome-promise.js Fix not finding window in some webpack configurations Jan 23, 2019
constructor.d.ts
constructor.js Use chromep instance by default and prioritize CommonJS Apr 6, 2018
index.d.ts
index.js
package.json
tsconfig.json Add typescript definitions. Fixes #11 Sep 17, 2017
watch.js Add typescript definitions. Fixes #11 Sep 17, 2017
yarn.lock Update sinon-chrome and fix tests May 26, 2018

README.md

chrome-promise

npm version build status

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.

Installation

Use npm

npm install chrome-promise

Or yarn

yarn add chrome-promise

Or 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';

Compatibility

It supports Chrome 34 or higher, but it should work in older versions. Create an issue if it doesn't work for your version.

Examples

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);
});

Options

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.

Notes

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"

Synchronous-looking code

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.

Alternative libraries

You can’t perform that action at this time.