Skip to content
Promises for chrome JavaScript APIs used in extensions and apps.
Branch: master
Clone or download
Latest commit ad5813f Jan 23, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
e2e-app Fix system permission requests Apr 2, 2018
.gitignore Add typescript definitions. Fixes #11 Sep 17, 2017
.travis.yml Change protractor to puppeteer Mar 18, 2018
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.js Use chromep instance by default and prioritize CommonJS Apr 6, 2018
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


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.


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


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.{foo: 'bar'}).then(function() {
  alert('foo set');
}).then(function(items) {
  alert(JSON.stringify(items)); // => {"foo":"bar"}

Detect languages of all tabs.

chromep.tabs.query({}).then((tabs) => {
  const promises = => chromep.tabs.detectLanguage(;
  return Promise.all(promises);
}).then((languages) => {
  alert('Languages: ' + languages.join(', '));
}).catch((err) => {


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)

// this works

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": [

// 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{foo: 'bar'});
  alert('foo set');
  const items = await'foo');

// try...catch
async function main2() {
  try {
    const tabs = await chromep.tabs.query({});
    const promises = => chromep.tabs.detectLanguage(;
    const languages = await Promise.all(promises);
    alert('Languages: ' + languages.join(', '));
  } catch(err) {

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{foo: 'bar'});
  alert('foo set');
  const items = yield'foo');

// try...catch
Q.spawn(function* () {
  try {
    const tabs = yield chromep.tabs.query({});
    const promises = => chromep.tabs.detectLanguage(;
    const languages = yield Promise.all(promises);
    alert('Languages: ' + languages.join(', '));
  } catch(err) {

// promise.catch
Q.async(function* () {
  const tabs = yield chromep.tabs.query({});
  const languages = yield Promise.all( => (
  alert('Languages: ' + languages.join(', '));
})().catch(function(err) {

You can also use the co library instead of Q.

Alternative libraries

You can’t perform that action at this time.