electron-manager

A complete toolkit for electron applications

Installation

Using npm:

$ npm i @hashedin/electron-manager

Then use it in your app:

import electronManager, { logger } from '@hashedin/electron-manager';
 
electronManager.init();
 
...
logger.init();
 
logger.log('This is a test message...!!!');

Initialization

electron-manager uses process.env.NODE_ENV in various places to determine the node environment. Make sure that NODE_ENV is available in all the processes(both main and renderer). If NODE_ENV is not available, then you can set the mode by using the init method.

init (main + renderer)

Params	Type	Default Value	Description
config	object	{}	electron-manager initial configuration

config

Params	Type	Default Value	Description
isDev	boolean	`process.env.NODE_ENV`	Flag to set the node environment

Modules

Dialog
ElectronUpdater
Ipc
Logger
StorageManager
WindowManager

Dialog

The dialog module is a wrapper module of Electron's dialog module. All the methods that are available in Electron's dialog module are available in electron-manager's dialog module as well. Additionally, it has showCustomMessageBox method to open the message box with a custom UI. This method supports URL as well as windowName to render the custom UI in the message box. Refer windowManager fro more details:

Methods

init (main)

Initialize the dialog module in the main process before using its methods. This helps to initialize all the internal communication channels.

showCustomMessageBox (main + renderer)

Show message box with custom UI. It supports all dialog window options that are supported in the Electron's dialog module. This method is the same as showMessageBox if you are not passing the custom UI properties(name or URL of the window). If you pass the custom UI properties then all the default message box properties will be omitted.

Params	Type	Default Value	Description
parentWindowRef	browserWindow/number/string	undefined	Parent window reference(BrowserWindow, name or id)
options	object	{}	Dialog window options
args	array	[]	list of callback functions

options

Params	Type	Default Value	Description
devTools	boolean	false	Open devTools for the dialog window
url	string	undefined	URL to be loaded inside the dialog window
windowName	string	undefined	Name of the dialog window
windowOptions	object	{}	BrowserWindow options

Note: You can override the default window options using the windowOptions object. You can use all the available BrowserWindow options here.

Use either window name or URL to render the custom UI in the message box. The default window size is 500 X 150. You have to adjust the size explicitly by using windowOptions parameter(pass the proper width and height).

handleButtonClick (renderer)

This method is only available in the renderer process. It is used to handle the button clicks from your custom UI(This method is applicable only if you are using window name or id to render the custom UI). The button index will start from right to left or bottom to top. The callback functions will be called based on the button indexes. It is mandatory to call this method from the button click handlers to avoid unexpected window behavior.

Params	Type	Default Value	Description
buttonIndex	number	undefined	Button index from the right or bottom
data	any	undefined	Data to be passed to the callback functions

import { dialog } from '@hashedin/electron-manager';

...
dialog.init();

// Normal dialog box 
dialog.showCustomMessageBox('home', {message: 'This is a test message box'},(data) => {
  // Handle button click here
});

// OR
dialog.showMessageBox(this.mainWindow, {message: 'This is a test message box'})
  .then((data) => {
    // Handle button click here
  })

// Custom UI
dialog.showCustomMessageBox('home', {
  windowName: 'exitPopup',
  windowOptions: {
    width: 450,
    height: 200,
    title: 'Exit'
  }
},(data) => {
  // Handle Ok button click here
},(data) => {
  // Handle cancel button click here
};

// exitPopup
import { dialog } from '@hashedin/electron-manager';

...
const ExitWindow = () => {
  const handleButtonClick = (index) => {
    // Button click custom code here...

    dialog.handleButtonClick(index); // This is mandatory
  }

  return (
    <div>
      {/*Exit popup UI code here...*/}
      <button onClick={()=>handleButtonClick(1)}>Cancel</button>
      <button onClick={()=>handleButtonClick(0)}>Yes</button>
    </div>
  );
}

Note: It also supports all Electron dialog methods such as showOpenDialogSync, showOpenDialog, showSaveDialogSync, showSaveDialog, ...etc

ElectronUpdater

ElectronUpdater module is used to update the application from existing version to newer versions. It can be used in both the main process as well as the renderer process. The electronUpdater is a lightweight module in electron-manager which helps to update the application in production mode.

Note: Please use electron-builder for the build configuration. Code-signing is required for ElectronUpdater to build the application else we need to disable the appropriate flags stated by the electron-builder.

Example for basic configuration required for generic providers

 "publish": {
   "provider": "generic",
   "url": "please add the published url"
 }
 ...
 //disable the Code-signing using the below flags
 win {
   "verifyUpdateCodeSignature": false
 },
 mac{
   "identity": null
 }

Methods

init (main) The ElectronUpdater module has to be initialized in the main processes.

import { electronUpdater } from '@hashedin/electron-manager';

...
electronUpdater.init();

autoUpdate (main + renderer) autoUpdate method downloads and installs the available updates.

electronUpdater.autoUpdate()

checkForUpdates (main + renderer) checkForUpdates method checks if any new updates are available and returns a promise. If any update is available checkForUpdates resolves the promise, then we can make our own callbacks like showing windows or dialogue.

electronUpdater.checkForUpdates()
.then(() => {
 // your own callback if update available
});

downloadUpdates (main + renderer) downloadUpdate method downloads the updated application and returns a Promise with the downloaded location of the new version. Custom logic can also be added as required to run/show after download and before installing it.

electronUpdater.downloadUpdates()
.then((path) => {
 console.log(path); // Prints location of the new version downloaded;
 // Custom logic can be added here.
 ...
 electronUpdater.installUpdates();
});

Note: This method just downloads the updated version but won't install it. Please use the installUpdates method to install the application. If we don't install after the update it will ask to install the application after closing the current running application.

installUpdates (main + renderer) installUpdates method installs the updated version. It quits the application and installs the new version.

electronUpdater.installUpdates();

cancelUpdate (main + renderer) cancelUpdate method cancels the downloading of the application.

electronUpdater.cancelUpdate();

Ipc

Ipc provides communication channels within the Electron application. It is a wrapper over the Electron's communication modules ipcMain and ipcRenderer.

Methods

init (main)

Initialize the ipc module in the main process before using its methods. This helps to initialize all the internal communication channels.

sendToAll (main + renderer)

You can send a message across the application using the sendToAll method. In main process, it will send the message to all open webContents. In renderer process, it will send the message to all open webContents(including the sender) as well as to the main process.

Params	Type	Default Value	Description
channel(*)	string	undefined	Channel name
args	any	undefined	list of arguments

import { ipc } from '@hashedin/electron-manager';

...
ipc.sendToAll('CHANNEL_1', 'This a test string');

// In the receiver end
...
ipc.on('CHANNEL_1', (evt, message) => {
  console.log(message);
});

sendToWindow (main + renderer)

This method can be used to send a message to a particular window from both main and renderer processes.

Params	Type	Default Value	Description
windowRef(*)	string/number	undefined	Name or id of the target window
channel(*)	string	undefined	Channel name
args	any	undefined	list of arguments

Note: You can pass either id or name of the window as windowRef. Window name will work only if you create the target window using electron-manager's windowManager module(windowManager.createWindow()). Window id should be a number

import { ipc } from '@hashedin/electron-manager';

...
ipc.sendToWindow(1, 'CHANNEL_1', 'This a test string');

// In renderer window
...
ipc.on('CHANNEL_1', (evt, message) => {
  console.log(message);
});

sendToWebview (main + renderer)

You can send a message across the webviews in the application using the sendToWebview method.

Params	Type	Default Value	Description
channel(*)	string	undefined	Channel name
args	any	undefined	list of arguments

import { ipc } from '@hashedin/electron-manager';

...
ipc.sendToWebview('CHANNEL_1', 'This a test string');

// In the receiver end
...
ipc.on('CHANNEL_1', (evt, message) => {
  console.log(message);
});

request (renderer)

Like ipcRenderer.invoke but the handler funtion will be on a different renderer process instead of main process.

Params	Type	Default Value	Description
channel(*)	string	undefined	Channel name
args	any	undefined	list of arguments

respond (renderer)

Like ipcMain.handle but the handler will be on a renderer process to handle an invokable IPC from an another renderer process.

Params	Type	Default Value	Description
channel(*)	string	undefined	Channel name
listener(*)	function	undefined	Listener function

// Renderer process 1
import { ipc } from '@hashedin/electron-manager';

...
ipc.request('CHANNEL_1', 'This a test input')
  .then((result) => {
    console.log(result);
  })
  .catch((err) => {
    console.log(err);
  })

// Renderer process 2
import { ipc } from '@hashedin/electron-manager';

...
ipc.respond('CHANNEL_1', (evt, data) => {
  console.log(data);

  return new Promise((resolve) => {
    setTimeout(() => {
      resolve('This a test output')
    }, 5000);
  })
})

Logger

Logger module helps to log all kinds of entries to both console and file. It can be used in both the main process as well as the renderer process. The logger is a lightweight module in electron-manager which helps to debug the application in development as well as in production.

Note: It is possible to have a different set of configurations for both main and renderer. In case there are multiple renderer processes in the application, then the logger module also has to be initialized in each module wherever required. Also, there can be different sets of configurations for each renderer process. If there is no custom configuration for renderer processes, then the main process configuration would be extended to all renderer processes.

Methods

init (main + renderer)

The logger module has to be initialized in respective processes with a relevant set of configuration options. Since there can be multiple renderer processes in an electron application, the logger module also can be set up for all the processes based on user preferences.

Params	Type	Default Value	Description
cleanLogs	boolean	true	Clean log files periodically
handleLocalConsole	boolean	false	Override local console statements in logger
logFolderPath	string	`userData/logs`	Application logs folder path
logPeriod	number	7	Logfile's lifespan in days
setFileHeader	boolean	true	Add file header in each log file
writeToFile	boolean	true	Write log entries into a system file

Note: userData The directory for storing your app's configuration files, which by default it is the appData directory appended with your app's name.

import { logger } from '@hashedin/electron-manager';
 
...
logger.init({
  cleanLogs: false
 logPeriod: 10
});

error (main + renderer)

logger.error('This is an error message!');

info (main + renderer)

info method is a proxy of console.info.

logger.info('This is an info message!');

log (main + renderer)

log method is a proxy of console.log.

logger.log('This is a log message!');

warn (main + renderer)

warn method is a proxy of console.warn.

logger.warn('This is a warning message!');

StorageManager

The StorageManager is used to store the application data into the disk storage. The default storage location would be the AppData folder of the installed application.

Methods

init (main)

Initialize the module in the main process.

Params	Type	Default Value	Description
config	object	{}	storageManager initial configuration

config

Params	Type	Default Value	Description
storageLocation	string	`app.getPath('userData')`	Default storage location

Note: You can create storage files in custom locations by setting location property in the individual configurations.

createStorage (main + render)

Params	Type	Default Value	Description
config	object	{}	Storage configuration

The configuration can be of type array or object. If you have multiple storages then pass the configuration as an array of objects. For single storage, it will take an object as a valid parameter.

config

Params	Type	Default Value	Description
extension	string	'json'	Storage file extension
initialState	any	{}	Initial state/data
location	string	`userData`	Storage location
name(*)	string	undefined	Storage name

Note: Storage name should meet all OS level validations

// Main process
import { storageManager } from '@hashedin/electron-manager';
...
storageManager.init();
 
...
storageManager.createStorage([
 {
   name: 'settings',
   extension: 'json',
   initialState: {}
 },
 {
   name: 'firstRunLock',
   extension: 'LOCK'
 }
])

read (main + render)

Read data from the file storage.

Params	Type	Default Value	Description
storageName(*)	string	undefined	Storage name

import { storageManager } from '@hashedin/electron-manager';
 
...
storageManager.read('settings')
 .then((data) => {
   console.log('StorageManager | Read : Success', data)
 })
 .catch((err) => {
   console.error('StorageManager | Read : Error', err)
 })

write (main + render)

Write data to the file storage.

Params	Type	Default Value	Description
storageName(*)	string	undefined	Storage name

import { storageManager } from '@hashedin/electron-manager';
 
...
storageManager.write('settings', {systemSettings: false})
 .then((data) => {
   console.log('StorageManager | Write : Success', data)
 })
 .catch((err) => {
   console.error('StorageManager | Write : Error', err)
 })

WindowManager

WindowManager can be used for creating and managing windows in an Electron application. WindowManager internally handles the environmental changes so that environment-specific configurations are not required. This module will handle the following use-cases:

Creating new windows
Open window using both URL and static file path
Maintaining parent-child relation

Methods

init (main)

Init method is only available on the main process. The window-manager will take the same set of configurations in both main and renderer processes.

Note: window-manager uses the node environment variable(process.env.NODE_ENV) to determine the development environment. Make sure that the process.env.NODE_ENV is set properly in all the processes. Also, you can set the isDev flag using the electron-manager configuration.

Params	Type	Default Value	Description
config	object	{}	WindowManager initial congigurations

config

Params	Type	Default Value	Description
enableDevTools	boolean	false	Enable devTools for both `development` and `production`
windowUrlPath	string	`process.env.ELECTRON_START_URL`	HTML file path for static pages(served from local)

DevTools will be disabled in production by default. You can enable it by setting enableDevTools. This flag will only enable the devTool option in windowManager. For opening the devTools, proper options in createWindow configurations are required to be passed.

You can either set the environment variable process.env.ELECTRON_START_URL or set it on windowManager init method windowUrlPath.

createWindow (main + renderer)

This method is an alternative for new BrowserWindow({}), the default way of creating a window on the Electron world. createWindow returns the newly created window instance back.

Params	Type	Default Value	Description
config	object	{}	Window configurations

config

Params	Type	Default Value	Description
devTools	boolean	true/false	The default value will be true in dev mode, false in production
name	string	`window_{windowId}`	Name of the window
options	object	{}	BrowserWindow options as per the Electron documentation(BrowserWindow)
url	string	undefined	The URL that has to be loaded in the newly created window

Note: Either name or url is mandatory to load the webContent in the newly created window. If the new window is using a hosted URL to load the content then pass the URL in url param. If it is a static file then, make sure that the window name is matching with the HTML file specified in the windowUrlPath.

import { windowManager } from '@hashedin/electron-manager';
 
...
const win = windowManager.createWindow({
  devTools: true,
  url: 'https://www.example.com',
  options: {
    height: 400
    width: 600,
  }
});

getWindow (main + renderer)

Get the window instance using the window name or id. Passing window id to this function is the same as calling BrowserWindow.fromId(). If there are multiple windows with the same name then it will return the first occurrence.

Params	Type	Default Value	Description
windowRef(*)	number/string	undefined	Name or id of the window

getWindows (main + renderer)

Get a list of window instances using the window name or id. windowRef argument is optional. Calling this function without any arguments will return a list of all opened window instances. windowRef is a filter option. The return value will be filtered based on the filter option.

Params	Type	Default Value	Description
windowRef	number/string	undefined	Name or id of the window

getWindowId (main + renderer)

Get window id using window name.

Params	Type	Default Value	Description
windowName(*)	string	undefined	Name of the window

getWindowIds (main + renderer)

Returns a list of IDs of the windows with the given window name. Calling this function without any arguments will return the IDs of all open windows

Params	Type	Default Value	Description
windowName	string	undefined	Name of the window

getWindowName (main + renderer)

Returns the name of the window using it's id.

Params	Type	Default Value	Description
windowId(*)	number	undefined	Id of the window

getWindowNames (main + renderer)

Returns the names of all opened windows.

import { windowManager } from '@hashedin/electron-manager';
 
...
const windowNames = windowManager.getWindowNames();

console.log('Window Names:', windowNames);

closeWindow (main + renderer)

Close the window using the winow name or id.

Params	Type	Default Value	Description
windowRef(*)	number/string	undefined	Id od name of the window

destroyWindow (main + renderer)

Destroy the window using the winow name or id.

Params	Type	Default Value	Description
windowRef(*)	number/string	undefined	Id od name of the window

License

Licensed under MIT

@hashedin/electron-manager

electron-manager

A complete toolkit for electron applications

Installation

Initialization

Modules

Dialog

Methods

ElectronUpdater

Methods

Ipc

Methods

Logger

Methods

StorageManager

Methods

WindowManager

Methods

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@hashedin/electron-manager

electron-manager

A complete toolkit for electron applications

Installation

Initialization

Modules

Dialog

Methods

ElectronUpdater

Methods

Ipc

Methods

Logger

Methods

StorageManager

Methods

WindowManager

Methods

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads