Wilson Mar bio photo

Wilson Mar

Hello. Hire me!

Email me Calendar Skype call 310 320-7878

LinkedIn Twitter Gitter Google+ Youtube

Github Stackoverflow Pinterest

Write and test native desktop apps in JavaScript within Node.JS


Overview

This article aims to enable you to use Electron as 3 use cases: 1) use apps developed in Electron for Windows, Mac, and Linux desktops;
2) test apps developed in Electron,
3) develop Electron apps for desktops.

I want you to feel confident that you’ve mastered this skill. That’s why this takes a hands-on approach where you type in commands and we explain the responses and possible troubleshooting. This is a “deep dive” because all details are presented.

Like a good music DJ, I’ve carefully arranged the presentation of concepts into a sequence for easy learning, so you don’t have to spend as much time as me making sense of the flood of material around this subject.

Sentences that begin with PROTIP are a high point of this website to point out wisdom and advice from experience. NOTE point out observations that many miss. Search for them if you only want “TL;DR” (Too Long Didn’t Read) highlights.

Stuck? Contact me and I or one of my friends will help you.

What is it?

Electron is used to build desktop applications by writing program in pure JavaScript running NodeJs on top of Goggle Chromium run-time.

Electron is open-source software actively maintained by Github engineers.

Github engineers built its Atom text editor using Electron. More precisely, GitHub open-sourced as Electron the “Atom Shell” they used to create Atom.

Use Electron Apps

Desktop apps built ussing Electron include: Slack, Visual Studio Code, LightTable. The Discord chat tool. The GitKraken Git UI. Postman REST tool.

The Brave internet browser.

All these are downloaded and installed like desktop apps built using legacy tools.

nwjs.io (Node Webkit) works in a similar way.

Code sign

  1. Get an Apple Developer Certificate in Keychain Access > My Certificates.

  2. In pack:osx script:

    --sign='Developer ID Application: My Company Ltd (ABCDEFGH10)'
    

On Windows, see http://zed.one/code-signing-a-windows-application.html

Auto-update

  1. Put the installer in a zip file on S3.

    Although auto-upating is built into Electron by https://github.com/Squirrel/Squirrel.Mac

Install https://github.com/maxogden/electron-packager

https://medium.com/@svilen/auto-updating-apps-for-windows-and-osx-using-electron-the-complete-guide-4aa7a50b904c#.rmyoizhfb

Run Electron apps in VMs

  1. Windows virtual machines.

    To enable USB controller that controls the camera, install
    VirtualBox Extension Pack

  2. Linux/Mac Virtual machines.

    https://ubuntu.com/

Install for Dev/Test

  1. Install Node.Js

    Node.js had been used to run web applications for the browser. But it can now build desktop applications instead of web servers because

Test Electron apps in Windows

This blog notes that since Electron’s APIs work at a lower level, it can be used for browser testing in place of PhantomJS.

  1. Add reference to jquery in html page.

  2. use Electron api to communicate between the “backend” side of Electron with the code running on its web view.

SikuliX

TODO: Investigate use of open-source Sikulix (formerly at http://sikulix.com) maintained by Raimund Hocke aka RaiMan.

  1. Create a folder such as

    
    cd ~
    mkdir SikuliX
    cd Sikulix
    

    This runs 64-bit Java on Windows, Mac, and Linux.

  2. Download into the folder setup file
    https://launchpad.net/sikuli/sikulix/1.1.0 file
    sikulixsetup-1.1.0.jar (2015-10-07)

    Alternately, download the nightly build from:
    http://nightly.sikuli.de file
    sikulixsetup-1.1.1.jar (2016-10-10 for macOS Sierra 10.12, etc.)

    This is built from https://github.com/RaiMan/SikuliX-2014

    SikuliX2 at https://github.com/RaiMan/SikuliX2 is not yet ready.

  3. From a Terminal invoke the jar

    cd ~/Sikulix
    java -jar sikulixsetup-1.1.0.jar

  4. Select Java or JPython or JRuby.

  5. Temporarily open another Terminal to install Jython using Homebrew:

    brew install jython

    The response:

    ==> Downloading https://homebrew.bintray.com/bottles/jython-2.7.0.sierra.bottle.
    #######################################################                   77.6%^######################################################################## 100.0%
    ==> Pouring jython-2.7.0.sierra.bottle.tar.gz
    🍺  /usr/local/Cellar/jython/2.7.0: 3,546 files, 131.7M
    

    Verify whether you can enter the interpreter:

    jython

    The response:

    Jython 2.7.0 (default:9987c746f838, Apr 29 2015, 02:25:11) 
    [Java HotSpot(TM) 64-Bit Server VM (Oracle Corporation)] on java1.8.0_102
    Type "help", "copyright", "credits" or "license" for more information.
    
    Get out of Jython:
    
    
    exit()
    
    
    
  6. Return to the installer to click Setup.

    This downloads sikulixlibsmac.jar.

It uses OpenCV to identify objects in screen prints Tesseract for OCR.

http://sikulix-2014.readthedocs.io/en/latest/#

Gitter

https://answers.launchpad.net/sikuli

Develop Electron apps

To create Windows desktop app was complicated before Electron. One needed Visual Studio and several libraries.

Install Sample App

  1. Install Sample app

    
    git clone https://github.com/electron/electron-quick-start
    cd electron-quick-start
    

    PROTIP: Electron provides the API hooks that manipulate native operating system functionality. Much like what Apache Cordova does for native mobile devices.

    But you may be better to clone and view source from among boilerplates created by the electron community.

  2. Install node module dependencies:

    pwd
    npm install –save-dev electron-prebuilt -D

    ”–save-dev” saves installation in the present working directory (project folder).

    This detects what operating system it is running on and installs for it to avoid having to build Electron from source (at https://github.com/electron/electron/).

  3. List node_modules folders

    
    cd node_modules
    ls -al
    

    This shows 154 files taking up 5,236 MB.

    drwxr-xr-x  154 mac  staff  5236 Oct 14 03:35 .
    
  4. View main.js

    PROTIP: In Electron, the process that runs package.json’s main script is called the main process. The script that runs in the main process can display a GUI by creating web pages.

    To ensure memory for a window is garbage collected when it is closed: “mainWindow = null”

    “app.on” functions from the app module controls the application lifecycle.

  5. Start sample app

    npm start

    As with all Node.js, the npm start command reads package.json, which specifies start by invoking script “electron .”.

    The response is:

    > electron-quick-start@1.0.0 start /Users/mac/gits/electron/electron-quick-start
    > electron .
    

    A desktop window pops up:

    The text is:

    Hello World!
    We are using node 6.5.0, Chromium 53.0.2785.113, and Electron 1.4.3.
    

    The left pane is what end-users see.

    PROTIP: Electron uses web pages as its GUI, controlled by JavaScript.

  6. View index.html

    process.versions.node refers to a process because each web page in Electron runs in its own process, called the renderer process.

    At the bottom of the file:

      <script>
     // You can also require other files to run in this process
     require('./renderer.js')
      </script>
    

    Each require statement invokes a different Chrome renderer process.

  7. View renderer.js

    // This file is required by the index.html file and will
    // be executed in the renderer process for that window.
    // All of the Node.js APIs are available in this process.
    

    In renderer JavaScript files are where Electron APIs are called to access native operating system functionality such as the Copy/Paste Clipboard Buffer, System Tray, Task bar, Take a screenshot, Webcam, Access File system, Network, Notifications, etc.

    Each process uses Node.JS pub-sub API event emitter module IPC (Inter-Process Communications). (at https://github.com/electron/electron/tree/master/docs).

    This illustrates Electron Fundamentals</a> by Jake Trent

Sample Sound Machine App

This blog describes a more sophisticated Electron app.

  1. Install Sound Machine app

    
    git clone https://github.com/bojzi/sound-machine-electron-guide
    cd sound-machine-electron-guide
    git checkout 00-blank-repository
    

    PROTIP: Electron provides the API hooks that manipulate native operating system functionality. Much like what Apache Cordova does for native mobile devices.

  2. Begin from a blank repository:

    
    git checkout 00-blank-repository
    

    The response:

    Cloning into 'sound-machine-electron-guide'...
    remote: Counting objects: 107, done.
    remote: Total 107 (delta 0), reused 0 (delta 0), pack-reused 107
    Receiving objects: 100% (107/107), 3.37 MiB | 291.00 KiB/s, done.
    Resolving deltas: 100% (26/26), done.
    
  3. Obtain the precompiled version of Electron in your app:

    npm install electron –save-dev </pre>

    (Previous to v1.3.1 on August 16. 2016, this was called electron-prebuilt) See http://electron.atom.io/blog/2016/08/16/npm-install-electron

    The response begins:

    > electron@1.4.3 postinstall /Users/mac/gits/electron/sound-machine-electron-guide/node_modules/electron
    > node install.js
     
    sound_machine@0.1.0 /Users/mac/gits/electron/sound-machine-electron-guide
    

    This is followed by a long list of node modules.

  4. List node_modules folders

    ls node_modules -al

    Scroll up to the top to see 154 files taking up 5,236 MB.

    drwxr-xr-x  154 mac  staff  5236 Oct 14 03:35 .
    
  5. Run the app:

    npm start

    ERROR:

    App threw an error during load
    Error: Cannot find module 'app'
     at Module._resolveFilename (module.js:455:15)
     at Function.Module._resolveFilename (/Users/mac/gits/electron/sound-machine-electron-guide/node_modules/electron/dist/Electron.app/Contents/Resources/electron.asar/common/reset-search-paths.js:35:12)
     at Function.Module._load (module.js:403:25)
     at Module.require (module.js:483:17)
     at require (internal/module.js:20:19)
     at Object. (/Users/mac/gits/electron/sound-machine-electron-guide/main.js:3:11)
     at Module._compile (module.js:556:32)
     at Object.Module._extensions..js (module.js:565:10)
     at Module.load (module.js:473:32)
     at tryModuleLoad (module.js:432:12)
    </pre>
    
    To kill the process, press control+C on the Mac.
       
    
    

Create base app code

If you prefer to start from scratch:

  1. Create your app folder (replacing my-demo with your own name)

    
    mkdir my-demo
    cd my-demo
    npm init -y
    

    This creates a package.json file.

  2. Edit package.json

    “start”: “electron .”

  3. Create main.js file

Get Build Tools

  1. Get Awesome

    https://github.com/sindresorhus/awesome-electron

    Useful resources for creating apps with Electron

  2. Istall app builder

    npm install electron-packager rimraf -D

    The -D cleans out the target folder before re-build.

    https://github.com/electron-userland/electron-packager

    To access Chromium’s Content API, Electron uses the libchromiumcontent shared library that includes the Chromium Content module and all of its dependencies. This means a powerful machine is not needed to build Electron.

  3. Install reload

    npm install electron-reload –save

    This detects changes and reloads the UI.

  4. Add to main.js

    require(“electron-reload”)(__dirname)

    NOTE: Ignore the error message “The app cannot be found.”

CSS Formatting

Electron does not use web dev frameworks such as Angular, Ember, or React because it targets native desktop.

PROTIP: There is no “responsive” layout in Electron apps to adopt a different layout when the window is reduced in size. Menu columns on the left stay the same width. So for speed, exact control, and to avoid framework churn, Electron does not use CSS frameworks such as Bootstrap or Foundation because does not need cross-browser responsive grid system.

Make Electron App

Access your laptop’s camera and microphone to capture a video.

Within the vendor folder, the example uses the “Seriously.js” library for “real-time, node-based video effects compositor for the web built with HTML5, Javascript and WebGL” (from seriouslyjs.org at https://github.com/brianchirls/Seriously.js by Brian Chirls)

Package Native App

  1. Define app icon.

    SVG Image File

  2. Define build step in package.json based on options defined in
    https://github.com/electron-userland/electron-packager

    
    "scripts":{
      "build": "rimraf Photobombth-* && electron-packager . --platform=darwin,win32,linux --arch=x64 --icon=app",
      "start": "electron ."
    }
    

    The –platform parameter specifies to create build files for all 3 platforms (darwin is for Mac).

  3. Run the build:

    npm run build

Start binaries

  1. In a child_process_demo.

Manipulate windows

Learning Resources

  1. Electron docs provides details.

  2. Electron Fundamentals by Jake Trent (@jaketrent, jaketrent.com, GitHub) shows how to add an icon to the System Tray, Clipboard Buffer, take a Screenshot, obtain Git status.

  3. Electron Playbook 1h 38m 2 Mar 2016 by Rob Conery (@robconery, rob.bigmachine.io GitHub). Rob created RED:4 website.

    This course shows how to make use of Handlebars text templating, Jade view engine, Photon for layouts on Mac.

https://medium.com/developers-writing/building-a-desktop-application-with-electron-204203eeb658#.l2n6jmbi3

More on front-end styling

This is one of several topics:

  1. Text Editors
  2. Markdown text for GitHub from HTML
  3. 508 Accessibility

  4. JAM Stack Website Project Plan
  5. HTTP/2 Transition Project Plan
  6. Static websites
  7. Jekyll Site Development

  8. Website styles
  9. Website Styling

  10. Email from website
  11. Search within Hyde format Jekyll websites
  12. Windows Tile Pin Picture to Website Feed

  13. Data Visualization using Tableau