/electron-chrome-extension

Implementation of Chrome extension APIs for Electron

Primary LanguageTypeScript

Electron Chrome Extension

Build Status

Environment

Tested with Electron v4.0.4 - Node v8.9.0 - NPM v5.5.1

Setup

  • Renderer - preload
require('electron-chrome-extension/preload');

For some reasons the navigator user agent is not inherited from the session so you will need to redefine the user agent via the Object.defineProperty method after the import

  • Main
import ECx from 'electron-chrome-extension';

app.on('ready', async () => {
  createWindow();

  // Load Grammarly
  await ECx.load('kbfnbcaeplbcioakkpcpgfkobkghlhen');
});

Connect your application logic

Extensions react to browser events for trigger their own logic. ECx send inner webContents events to extensions subscribers but external events like creating new window, changing tab focus etc should be triggered on your side like this:

// main.js

ipcMain.on('YOUR_EVENT', (...) =>
  ECx.sendEvent({
    channel: 'tabs.onActivated',
    payload: [{ tabId, windowId }],
  })
);

Usage with DevTools extension

⚠️ electron-chrome-extension will break Electron's support for Devtools extensions.

If you wish to use devtools extensions, make sure to add the prelaod on the Session itself:

if (isDev) {
  app.on('session-created', session => {
    session.setPreloads([path.join(__dirname, 'node_modules/electron-chrome-extension/preload')]
  });
}

It is not recommended to have the preload added to Sessions outside developement environnement because it can lead to have extension's code run in priviledged contexts (BrowserWindows with nodeIntegration for instance).

Then install Chrome DevTools extensions with electron-chrome-extension:

import ECx from 'electron-chrome-extension';
// load React Dev Tools
ECx.load('jdkknkkbebbapilgoeccciglkfbmbnfm');

ECx APIs

  • ECx.load(extensionId: IExtension['id']): Promise<IExtension>
  • ECx.unload(extensionId: IExtension['id']): void
  • ECx.setConfiguration(configuration: Configuration = {}): Promise<ECx>
  • ECx.isLoaded(extensionId: IExtension['id']): boolean
  • ECx.isUpToDate(extensionId: IExtension['id']): Promise<boolean>
  • ECx.get(extensionId: IExtension['id']): Promise<IExtension>
  • ECx.sendEvent(event: ExtensionEventMessage): void

Tools

  • Start Playground
$ npm start

You can tweak the playground files at your convenience and extensions would automatically downloaded and clean app data with $ npm run playground:reset

  • Test
$ npm test

We use electron-mocha for run our test suit. Warning (because not explained in the lib): test assertions lives in the renderer, the main remains accessible for IPC calls and Electron Main API calls.

  • Publish
$ npm publish

References

Know supported extensions

as of 05/29/19 with their Chrome WebStore ID

  • Mixmax: ocpljaamllnldhepankaeljmeeeghnid
  • Gmelius: dheionainndbbpoacpnopgmnihkcmnkl
  • Mailtracker: pgbdljpkijehgoacbjpolaomhkoffhnl
  • Boomerang: mdanidgdpmkimeiiojknlnekblgmpdll
  • Clearbit Connect: pmnhcgfcafcnkbengdcanjablaabjplo
  • Grammarly: kbfnbcaeplbcioakkpcpgfkobkghlhen
  • React Developers Tools: fmkadmapgofadopljbjfkapdkoienihi
  • Redux DevTools: lmhkpmbekcpmknklioeibfkpmmfibljd
  • Apollo Client Developer Tools: jdkknkkbebbapilgoeccciglkfbmbnfm