electron-boilerplate

Most Electron apps have the same boilerplate code for their main process. This module is an attempt to provide reusable main process code via a plugin architecture.

For example, with the following code in your main Electron entry point:

const { ElectronBoilerplate } = require('electron-boilerplate');

ElectronBoilerplate
  .standardConfiguration()
  .run('optional/path-to/index.html');

The standard configuration automatically:

• Looks in a couple of places for index.html if it wasn't provided
• Sets the UserModelId from the userModelId property in package.json or a reasonably sensible default
• When not in dev mode, sets a minimal menu on macOS and removes the menu on Windows and Linux
• Persists the position and dimensions of BrowserWindows
• Ensures BrowserWindows are not created on displays that are have been disconnected since last run
• Ensures a single instance, caters for the Mac open-file event and notifies the renderer of new instances
• Adds hooks so protocol client handlers and global keyboard shortcuts can be registered form the renderer
• Adds a hook so files can be dragged out of the renderer into Explorer/Finder
• Prevents Ctrl+Click (Cmd+Click on Mac) on links from opening new BrowserWindows
• Prevents Electron from opening files that are dropped into BrowserWindows
• Prevents keyboard/mouse/trackpad/touchscreen from zooming in BrowserWindows
• Starts the main BrowserWindow
• Offers a shortcut for opening modal BrowserWindows from the renderer or main process

Alternatively, you can selectively enable the built in features you require via use or call standardConfiguration and override the defaults using use and remove.

const { ElectronBoilerplate, BuiltIn } = require('electron-boilerplate');

const ourMenu = new Menu();

ElectronBoilerplate
  .standardConfiguration()
  // Use a specific menu
  .use(BuiltIn.setDefaultMenu(ourMenu))
  // Specify default dimensions
  .use(BuiltIn.rememberWindowPositions(1000, 800))
  // Remove this plugin as want to allow zooming
  .remove(BuiltIn.stopWindowFromZooming());
  // Run optionally takes BrowserWindowOptions param
  .run('path-to/index.html', {
    minWidth: 800,
    minHeight: 650
  })

These features are built on a common API so you can create your own reusable plugins. See the base monorepository for details of the plugin API.

There are currently two additional plugins which can be installed separately:

• @electron-boilerplate/titlebar - Renders color titlebars on Windows and macOS
• @electron-boilerplate/sentry - JavaScript and native crash reporting using elctron-sentry

When your renderer and UI framework have finished loading, the built in features can be accessed like this:

const { ElectronBoilerplate } = require('electron-boilerplate')

ElectronBoilerplate.newInstance(args => {
  // Hook this as late as you like and you'll still get the
  // first args passed into the app on any platform
});

ElectronBoilerplate.defaultProtocolClient('example', url => {
  // When your app is called via the example:// URI scheme,
  // you'll get notified here. `url` has `example://` stripped.
});

ElectronBoilerplate.globalShortcut('CommandOrControl+X', () => {
  // notifications when global keyboard shortcut
});

// Start drag-out event for a specific file with an icon
ElectronBoilerplate.dragOutStart('path/to/file.txt', pngIconArray);

// Create a modal window and apply our defaults
ElectronBoilerplate.createModal('modal-one', 'index2.html'));

TODO

• Add CI build with Spectron tests