@hashedin/electron-manager

2.0.1 • Public • Published

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

Copyright (c) 2010-2020 | © HashedIn Technologies Pvt. Ltd.

Package Sidebar

Install

npm i @hashedin/electron-manager

Weekly Downloads

3

Version

2.0.1

License

MIT

Unpacked Size

107 kB

Total Files

6

Last publish

Collaborators

  • abahl
  • hashedin-admin
  • sanoop.jose
  • seshaabhishek