Sunday, February 17, 2019

Desktop Support - Electron

Electron

Now that we have a stable framework with mobile build capabilities it is time to introduce Electron into the mix. Electron provides us with build scripts to package our SPA for desktop installations across Windows, Mac and Linux operating systems. It also allows us to add OS specific functionality like right click context menus, printing, etc. to our desktop builds.

Just to recap a little. Our Aurelia SPA framework reduces a (possibly) very complex web application into a nice tidy package, consisting of a handful of html, css and javascript files that can be run as a website in any browser. Cordova can use the Aurelia build as source to produce installable packages for Android and IOS mobile devices. Electron can use the Aurelia build to produce installable packages for Windows, Mac, and Linux desktops. This is the "Holy Grail" we have been chasing for quite some time now. A single simple javascript framework that can be packaged and installed in most of our modern day environments be it desktop or mobile!

Let's get started. First we will add Electron to our project.
  1. Open a command prompt in the root folder of our project.
  2. Run command 'nvm use 10.14.0'
  3. Run command 'npm install electron --save-dev'
We do not need to install Electron globally like we did with Aurelia and Cordova. We install Electron as a development dependency which means it is not included in the Aurelia build bundled scripts. Since Electron is basically a builder (same as Cordova) it is not relevant to the deployed application, therefore not included in the Aurelia build.

Next we will create a skeleton Electron project. Unfortunately Electron does not have a 'new' command to create a skeleton like Aurelia and Cordova. Fortunately the skeleton only requires a new directory, a couple of files, and some small changes to our existing project.
  1. Create a new folder in the project root named app
  2. Create a new file in app directory called package.json
  3. Edit the file with the following code

  4. Create a new file in app directory called main.js
  5. Edit the file with the following code or download it here


  6. Create a new file in app directory called index.html
  7. Edit the file with the following code

  8. Our new directory should look like this

  9. Open package.json located in the project root in your editor.
  10. Add the following at the bottom of the file

That's it! We are ready to run our Electron skeleton project.
  1. Open command prompt
  2. Run command 'npm start' 
  3. An Electron window should open and display the skeleton app

Don't confuse this with our Aurelia 'Hello World' app. This is a new Electron app that we just introduced into our project.

Let's recap again. There is a lot going on now and it is easy to loose track of what we are doing.
  • The Aurelia app is launched with 'au run --watch' command in the root directory
  • The Aurelia file watchers automatically push changes to the Cordova app
  • The Cordova app is launched with 'cordova run (browser/android/ios)' command in the www directory
  • The Electron app is launched with 'npm start' command in the root directory
NOTE: The Electron app is launched using a npm script that we defined in the package.json file. This is necessary because Electron is not installed globally. It is possible to add additional npm scripts for all of our tasks to create a set of standard commands that we could use to manage builds in our project if you find that remembering the various commands becomes cumbersome. 


Next ... we need to be able to build our Electron app into installable packages for desktops.

Electron Builder

To build our app into installable packages we will use the Electron-Builder package.
  1. Open a command prompt in the project root.
  2. Run command 'npm install electron-builder --save-dev'
The builder requires some image resources to use when creating the installable package. You can read more about it here.
  1. Create a new directory called build in the root of the project.
  2. Open a browser to https://iconverticons.com/online/
  3. Upload splash.png (your original artwork file) from the res folder.
  4. Download the ico, icns and 256x256 png files created by the converter
  5. Rename the ico file to icon.ico and save it in the build directory
  6. Rename the icns file to icon.icns and save it to the build directory
  7. Rename the png file to background.png and save it to the build directory
  8. Your build directory should now look like the following


We also need to add some build instructions to the package.json file in the project root
  1. Open package.json from project root in your editor
  2. Add the following node

     
  3. Add the following instruction to the "scripts" node

We are now ready to build our Electron app. Remember, we are building the Electron skeleton project we just created. The next blog will deal with pushing the Aurelia app into the Electron app using the same process we did for the Cordova app.
  1. Open a command prompt in the project root
  2. Run command 'npm run dist'

  3. You will see a new dist directory appear in the project that contains the build we just performed

The 'applewood Setup 0.1.0.exe' file is our installable package for Windows desktops.
Go ahead and install it and click the desktop icon to open the app!


If you open the Windows Control Panel and go to Programs and Features you will see the app installed as a normal Windows software package. Sweet !!!!!


We also need to do a little housekeeping.
  1. Open .gitignore file in the editor
  2. Add the following

This will prevent the dist folder from being saved in your source repository.


NOTE: You may have noticed that to run the electron project we entered 'npm start' however to build the project we used 'npm run dist'. NPM comes with some built in aliases and start is one. The command 'npm start' is equivalent to 'npm run start'. You can read more here.


Now it's time to swing over to the Mac and test our build for the Mac desktop.

NOTE: If you have been following along on a Windows machine make sure you have committed your changes to the project repository and then retrieve the latest code from your repository using GIT on your Mac.

  1. Open a terminal window
  2. Run command 'nvm use 10.14.0'
  3. Run command 'npm install' to download the electron packages.
  4. Run command 'npm start'
  5. We should see our electron app open

  6. Run command 'npm run dist'  to build our installable package

  7. Inspect the dist folder

  8. Double click the 'applewood-0.1.0.dmg' file to install it.
  9. You should see the standard installer box appear. Drag the applewood icon into the Applications folder.

  10. Open Launchpad and you will see your installed app icon

  11. Double click the icon to run it.
We now have successfully added an Electron skeleton to our project and built an installable package for both Windows and Macs from a single code base!

Next up - we will integrate our Aurelia project into the Electron project.

Time for a rest and a cold one!


No comments:

Post a Comment