Nutritious Polygonal Meatball

    @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.

    Install

    npm i @hashedin/electron-manager

    DownloadsWeekly Downloads

    2

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    107 kB

    Total Files

    6

    Last publish

    Collaborators

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