Using Node and Electron to build Desktop Apps: Difference between revisions

From NSB App Studio
Jump to navigation Jump to search
← Older edit
 
(81 intermediate revisions by the same user not shown)
Line 7: Line 7:
== Introduction ==
== Introduction ==


AppStudio now supports the use of a some of the biggest new technologies in the web development world.
AppStudio now supports the use of some of the most important new technologies in the web development world.


[https://nodejs.org/en/ Node.js] is a runtime environment that executes JavaScript code outside the browser. That makes it suitable for writing server side software, which would normally be done in PHP or other languages. It works by having an executable stub which is able to call the V8 JavaScript engine, which powers Chrome.
[https://nodejs.org/en/ Node.js] is a runtime environment that executes JavaScript code outside the browser. That makes it suitable for writing server side software, which would normally be done in PHP or other languages. It works by having an executable stub which is able to call the V8 JavaScript engine, which powers Chrome.
Line 16: Line 16:


[https://electronjs.org/ Electron] is framework which allows for the development of desktop GUI applications. Since it's built on Node.js, it already has the ability to run JavaScript code. It also uses Chrome's browser engine to render the UI using regular HTML. Each Electron app includes the V8 Runtime as well as the Chrome browser. Slack, Github Desktop and WhatsApp are examples of apps built using Electron.
[https://electronjs.org/ Electron] is framework which allows for the development of desktop GUI applications. Since it's built on Node.js, it already has the ability to run JavaScript code. It also uses Chrome's browser engine to render the UI using regular HTML. Each Electron app includes the V8 Runtime as well as the Chrome browser. Slack, Github Desktop and WhatsApp are examples of apps built using Electron.
=== How is this compare to VoltBuilder? ===
VoltBuilder (Cordova) is used to package apps for iOS and Android. Electron is used to package apps for Windows, MacOS and Linux. It's quite reasonable to have one AppStudio project that you use with both VoltBuilder and Electron, letting you build for all 5 platforms.
Nodejs/npm modules are similar to VoltBuilder Plugins. Since they are operating system specific, Cordova Plugins will not work with Electron (and vice versa).


== Tutorial: Make an Electron app ==
== Tutorial: Make an Electron app ==


AppStudio allows you to make normal AppStudio apps (programmed in Javascript or BASIC) into full blown Electron apps. You can distribute these apps as full blown executables, able to run on Windows, MacOS and Linux.
AppStudio allows you to make normal AppStudio apps (programmed in Javascript or BASIC) into full blown Electron apps. You can distribute these apps as regular executables, able to run on Windows, MacOS and Linux.


In this tutorial, we're going to use a module from npm called [https://github.com/devfacet/weather weather-js] to create an app which gets weather data from weather.service.msn.com. It's very convenient: we don't have to figure out the MSN API to use it.
In this tutorial, we're going to use a module from npm called [https://github.com/devfacet/weather weather-js] to create an app which gets weather data from weather.service.msn.com. It's very convenient: we don't have to figure out the MSN API to use it.


You will have to know how to use the command line (Terminal on MacOS, cmd or Powershell on Windows) and have AppStudio 7.2.3 or later installed.
We recommend using AppStudio 8 (or later) with this tutorial.


=== Set up the project ===
=== Set up the project ===
Line 31: Line 37:
https://nodejs.org/en/download/
https://nodejs.org/en/download/


2. Using AppStudio, create a new project called ElectronWeather and save it.
2. Using AppStudio, create a new project called ElectronWeather and save it. (You can also use the ElectronWeather sample with comes with AppStudio by opening it and doing a "Save As" elsewhere, to create a fresh copy. If you do this, several steps below can be skipped - follow the instructions)
 
3. Enter "Weather App" into description in Project Properties.
 
4. In Project Properties, go to the Electron section and open package.json. Modify the "dependancies" line as follows: (Skip this step if you're using the sample).


3. Open a command line window in the newly created ElectronWeather.appstudio folder and type npm init. This creates a file named package.json, which has configuration info for npm and Electron. Use the the defaults, except for entry point:
<pre>
<pre>
$ npm init
  "dependencies": {{
This utility will walk you through creating a package.json file.
    "weather-js": "^2.0.0"
It only covers the most common items, and tries to guess sensible defaults.
  }},
</pre>
 
This includes the [https://www.npmjs.com/package/weather-js Weather-js] Node library from npm.
 
5. To add your own icon, follow these steps. (Skip this step if you're using the sample).
* Put an png file at least 512x512 in your project directory.
* Set VoltBuilder icon(1024) to that icon in Project Properties.
 
=== Add the Weather Code ===
 
1. Add a button to Form1.
 
2. In the Code Window for Form1, paste the following code. You'll notice there is a new function called 'require' in the first line. This function is part of Node.js: it loads the module of that name.


See `npm help json` for definitive documentation on these fields
Since this function is not part of JavaScript, the project will not run in the browser as a normal project would.
and exactly what they do.


Use `npm install <pkg>` afterwards to install a package and
<tabber>
save it as a dependency in the package.json file.
JavaScript=
<syntaxhighlight lang="JavaScript">
var weather = require("weather-js");


Press ^C at any time to quit.
Button1.onclick = function() {
package name: (ElectronWeather.appstudio)  
  weather.find({search: "San Francisco, CA", degreeType: "F"}, weatherFindCallback);
version: (1.0.0)
};
description:
entry point: (electronMain.js)
test command:
git repository:
keywords:
author:  
license: (ISC)  
About to write to /Users/george/ElectronWeather.appstudio/package.json:


{
function weatherFindCallback(err, result) {
   "name": "ElectronWeather.appstudio",
   if(err) {
  "version": "1.0.0",
    NSB.MsgBox(err);
   "description": "",
   } else {
  "main": "electronMain.js",
     NSB.Print(JSON.stringify(result, null, 2));
  "scripts": {
   }
     "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
   "license": "ISC"
}
}
</syntaxhighlight>
|-|
BASIC=
<syntaxhighlight lang="vb.net">
weather = require("weather-js")
function Button1_onclick()
  weather.find({search: "San Francisco, CA", degreeType: "F"}, weatherFindCallback)
End function


Is this OK? (yes) yes
function weatherFindCallback(err, result)
</pre>
  If err Then
    MsgBox(err)
  else
    Print JSON.stringify(result, null, 2)
  End if
End function
</syntaxhighlight>
</tabber>
 
=== Run the App ===
 
Now we're ready to run the app. On the Run menu, choose "Run Desktop App using Electron"
 
'''Some notes'''
* The Chrome Dev Tools window opens by default. We'll need this if we are going to debug the app.
* To turn off the Chrome Dev Tools, set "Chrome Dev Tools" to false in Project Properties.
* The "Electron Security Warning" in the console can be ignored.
 
=== Distributing the App ===
 
We now have a running app. The next step is to package it for distribution. We can make regular executables for distribution on MacOS, Windows and Linux. The packaging has to done on a computer running the OS we are targeting: the MacOS version needs to be build on a Mac, etc.


4. We can now add some libraries from npm to our project. In the same command line window, type the following:
There is more documentation on packaging at https://www.electron.build/. You'll need to pay special attention to code signing requirements.
<pre>
npm install weather-js
npm install electron
</pre>


5. Drag and drop package.json into the Project Explorer window in AppStudio. This adds the file to the project.
On the Run menu, choose "Make Desktop App for Distribution using Electron". If the build fails, look at the log in "About AppStudio" for more information.


6. Create a file called electronMain.js in your project folder, with the following code in it:
When the build is complete, you will find the executable in your project folder, in
<pre>
// Modules to control application life and create native browser window
const {app, BrowserWindow, Menu} = require('electron');
const path = require('path');
const url = require('url');


// Keep a global reference of the window object, if you don't, the window will
electron/ElectronWeather/dist/*
// be closed automatically when the JavaScript object is garbage collected.
let mainWindow;


function createWindow () {
=== Tips ===
  // Create the browser window.
  mainWindow = new BrowserWindow({
  width: 768,
  height: 1004,
  icon:__dirname+'/img/AppStudio.icns',
  title: 'Framework Converter',
  webPreferences: {nodeIntegration: true},
  })
  console.log(__dirname)


  // and load the index.html of the app.
==== Setting Electron Runtime Options ====
  mainWindow.loadFile('index.html')
The operation of Electron apps at runtime can be changed by modifying the electronMain.js module. It's in the Electron section of Project Properties.


  // Open the DevTools.
You can learn more about the options in [[ElectronMain.js]].
  mainWindow.webContents.openDevTools()
 
  // set up the menu
  const menu = Menu.buildFromTemplate(template)
// Menu.setApplicationMenu(menu)


  // Emitted when the window is closed.
==== How to tell if you are running Electron at runtime ====
  mainWindow.on('closed', function () {
<pre>
    // Dereference the window object, usually you would store windows
if (NSB.electron) {
    // in an array if your app supports multi windows, this is the time
  // Code placed in here that would on be run if deployed via Electron
    // when you should delete the corresponding element.
    mainWindow = null
  })
}
}
</pre>


// This method will be called when Electron has finished
==== How to tell if you are running Windows or MacOS at runtime ====
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.on('ready', createWindow)


// Quit when all windows are closed.
<pre>
app.on('window-all-closed', function () {
if (NSB.electron) {
  // On macOS it is common for applications and their menu bar
  if (process.platform === "win32") {
   // to stay active until the user quits explicitly with Cmd + Q
    // Electron Windows
   if (process.platform !== 'darwin') {
   }
     app.quit()
   if (process.platform === "darwin") {
     // Electron MacOS
   }
   }
})
}
</pre>
 
=== Debugging ===


app.on('activate', function () {
# Check the AppStudio Log in 'About AppStudio'. It will have more info.
  // On macOS it's common to re-create a window in the app when the
# To reset the Electron environment, simply delete the electron folder in your project. It will be recreated next time you start your app.
  // dock icon is clicked and there are no other windows open.
# To start your Electron app in a console, open it in the electron folder of your project directory and enter:
  if (mainWindow === null) {
<pre>
    createWindow();
npm start
  }
</pre>
})
# To build your Electron distributable in a console, open it in the electron folder of your project directory and enter:
<pre>
npm run pack
npm run dist
</pre>
</pre>


7. Drag and drop electronMain.js into the Project Explorer window of AppStudio. In the file's properties, set loadType to 'noload'.
=== Make sure your package.json is up to date ===
[[file:Electron1.png]]
 
In Project Properties, under Electron, there is a package.json property. Make sure it is up to date.


=== Add the Weather Code ===
The current settings are:
<pre>
  "electron": "^31.2.0",
  "electron-builder": "^24.13.3",
  "npm": "^10.8.2"
</pre>
 
=== Troubleshooting ===


=== Set up the Deploy ===
If your Electron apps are not running, you may have version mismatches in your electron folder. To resolve these, delete the folder (it's in your project directory). Next time you run, AppStudio will recreate it using the latest versions of everything.


10. Set deploy option to a local path - something like local-deploy
You may need to recreate the package.json used by Electron. To do so, exit AppStudio. Open {projectname}.appstudio in your project folder. Delete the electronPackage line and restart AppStudio.


11. deploy to it.
==== Reinstalling Electron ====
If the above steps do not help, you may need to redo your installation of the toolchain. It can be thrown off by mismatches in version numbers. Here is how to do a complete reinstall:


12. open a command window in local-deploy/ElectronWeather
# uninstall node (Use the Windows Installed Apps uninstaller)
# uninstall AppStudio
# delete C:\Program Files\nodejs (if it is there)
# delete C:\Program Files\NSB AppStudio (if it is there)
# delete the electron folder in your project
# reboot
# install latest version of node
# install AppStudio
# delete electron folder from your app if present
# build again


13. npm install
==== Turn on Developer Mode (Windows) ====


14. npm start - the app should run
Users report that changing this setting helps in cases where executables are not being created.


15. Add a button to Form1
In Windows Settings, in “System > For Developers”, set “Developer Mode - Install from any source, including loose files” to on.  


16. Add this code to Form1.
[[File:Screenshot 2024-08-26 at 10.47.06 AM.png]]
weather = require("weather-js")
function Button1_onclick()
  weather.find({search: "San Francisco, CA", degreeType: "F"}, weatherFindCallback)
End function


function weatherFindCallback(err, result)
==== Install electron-builder-libraries ====
  if err Then
    MsgBox(err)
  else
    Print JSON.stringify(result, null, 2)
  End if
End function


17. Add this to extraheaders:
Users report that changing this setting helps in cases where executables are not being created.
<!-- Electron -->


=== Run the App ===
You can download the installer for this here:
https://github.com/electron-userland/electron-builder-binaries/releases

Latest revision as of 21:22, 30 September 2024

  • Node.is
    Node.is
  • Node Package Manager
    Node Package Manager
  • Electron
    Electron

Introduction

AppStudio now supports the use of some of the most important new technologies in the web development world.

Node.js is a runtime environment that executes JavaScript code outside the browser. That makes it suitable for writing server side software, which would normally be done in PHP or other languages. It works by having an executable stub which is able to call the V8 JavaScript engine, which powers Chrome.

npm is a repository of code which can be used with Node.js. It's included when you download Node. There is a huge number of packages available - over 750,000 at last count. You can include these packages in your Node project to add functionality. It might be for convenience: there are a lot of libraries which are much easier to include in your project than to write yourself. It might be for functionality: the modules can implement features which would not be available in the browser.

An example of a convenient library would be Lodash which adds hundreds of additional functions to JavaScript. A missing feature library would be fs-extra which allows full access to the file system.

Electron is framework which allows for the development of desktop GUI applications. Since it's built on Node.js, it already has the ability to run JavaScript code. It also uses Chrome's browser engine to render the UI using regular HTML. Each Electron app includes the V8 Runtime as well as the Chrome browser. Slack, Github Desktop and WhatsApp are examples of apps built using Electron.

How is this compare to VoltBuilder?

VoltBuilder (Cordova) is used to package apps for iOS and Android. Electron is used to package apps for Windows, MacOS and Linux. It's quite reasonable to have one AppStudio project that you use with both VoltBuilder and Electron, letting you build for all 5 platforms.

Nodejs/npm modules are similar to VoltBuilder Plugins. Since they are operating system specific, Cordova Plugins will not work with Electron (and vice versa).

Tutorial: Make an Electron app

AppStudio allows you to make normal AppStudio apps (programmed in Javascript or BASIC) into full blown Electron apps. You can distribute these apps as regular executables, able to run on Windows, MacOS and Linux.

In this tutorial, we're going to use a module from npm called weather-js to create an app which gets weather data from weather.service.msn.com. It's very convenient: we don't have to figure out the MSN API to use it.

We recommend using AppStudio 8 (or later) with this tutorial.

Set up the project

1. Download and install Node. (This also installs npm.)

https://nodejs.org/en/download/

2. Using AppStudio, create a new project called ElectronWeather and save it. (You can also use the ElectronWeather sample with comes with AppStudio by opening it and doing a "Save As" elsewhere, to create a fresh copy. If you do this, several steps below can be skipped - follow the instructions)

3. Enter "Weather App" into description in Project Properties.

4. In Project Properties, go to the Electron section and open package.json. Modify the "dependancies" line as follows: (Skip this step if you're using the sample). 

  "dependencies": {{
    "weather-js": "^2.0.0"
  }},

This includes the Weather-js Node library from npm.

5. To add your own icon, follow these steps. (Skip this step if you're using the sample).

  • Put an png file at least 512x512 in your project directory.
  • Set VoltBuilder icon(1024) to that icon in Project Properties.

Add the Weather Code

1. Add a button to Form1.

2. In the Code Window for Form1, paste the following code. You'll notice there is a new function called 'require' in the first line. This function is part of Node.js: it loads the module of that name.

Since this function is not part of JavaScript, the project will not run in the browser as a normal project would. 

var weather = require("weather-js");

Button1.onclick = function() {
  weather.find({search: "San Francisco, CA", degreeType: "F"}, weatherFindCallback);
};

function weatherFindCallback(err, result) {
  if(err) {
    NSB.MsgBox(err);
  } else {
    NSB.Print(JSON.stringify(result, null, 2));
  }
}


weather = require("weather-js")
 
function Button1_onclick()
  weather.find({search: "San Francisco, CA", degreeType: "F"}, weatherFindCallback)
End function

function weatherFindCallback(err, result)
  If err Then
    MsgBox(err)
  else
    Print JSON.stringify(result, null, 2)
  End if
End function

Run the App

Now we're ready to run the app. On the Run menu, choose "Run Desktop App using Electron"

Some notes

  • The Chrome Dev Tools window opens by default. We'll need this if we are going to debug the app.
  • To turn off the Chrome Dev Tools, set "Chrome Dev Tools" to false in Project Properties.
  • The "Electron Security Warning" in the console can be ignored.

Distributing the App

We now have a running app. The next step is to package it for distribution. We can make regular executables for distribution on MacOS, Windows and Linux. The packaging has to done on a computer running the OS we are targeting: the MacOS version needs to be build on a Mac, etc.

There is more documentation on packaging at https://www.electron.build/. You'll need to pay special attention to code signing requirements.

On the Run menu, choose "Make Desktop App for Distribution using Electron". If the build fails, look at the log in "About AppStudio" for more information.

When the build is complete, you will find the executable in your project folder, in

electron/ElectronWeather/dist/*

Tips

Setting Electron Runtime Options

The operation of Electron apps at runtime can be changed by modifying the electronMain.js module. It's in the Electron section of Project Properties.

You can learn more about the options in ElectronMain.js.

How to tell if you are running Electron at runtime

if (NSB.electron) {
  // Code placed in here that would on be run if deployed via Electron
}

How to tell if you are running Windows or MacOS at runtime

if (NSB.electron) {
  if (process.platform === "win32") {
    // Electron Windows
  }
  if (process.platform === "darwin") {
    // Electron MacOS
  }
}

Debugging

  1. Check the AppStudio Log in 'About AppStudio'. It will have more info.
  2. To reset the Electron environment, simply delete the electron folder in your project. It will be recreated next time you start your app.
  3. To start your Electron app in a console, open it in the electron folder of your project directory and enter:
npm start
  1. To build your Electron distributable in a console, open it in the electron folder of your project directory and enter:
npm run pack
npm run dist

Make sure your package.json is up to date

In Project Properties, under Electron, there is a package.json property. Make sure it is up to date.

The current settings are: 

  "electron": "^31.2.0",
  "electron-builder": "^24.13.3",
  "npm": "^10.8.2"

Troubleshooting

If your Electron apps are not running, you may have version mismatches in your electron folder. To resolve these, delete the folder (it's in your project directory). Next time you run, AppStudio will recreate it using the latest versions of everything.

You may need to recreate the package.json used by Electron. To do so, exit AppStudio. Open {projectname}.appstudio in your project folder. Delete the electronPackage line and restart AppStudio.

Reinstalling Electron

If the above steps do not help, you may need to redo your installation of the toolchain. It can be thrown off by mismatches in version numbers. Here is how to do a complete reinstall:

  1. uninstall node (Use the Windows Installed Apps uninstaller)
  2. uninstall AppStudio
  3. delete C:\Program Files\nodejs (if it is there)
  4. delete C:\Program Files\NSB AppStudio (if it is there)
  5. delete the electron folder in your project
  6. reboot
  7. install latest version of node
  8. install AppStudio
  9. delete electron folder from your app if present
  10. build again

Turn on Developer Mode (Windows)

Users report that changing this setting helps in cases where executables are not being created.

In Windows Settings, in “System > For Developers”, set “Developer Mode - Install from any source, including loose files” to on.

Install electron-builder-libraries

Users report that changing this setting helps in cases where executables are not being created.

You can download the installer for this here: https://github.com/electron-userland/electron-builder-binaries/releases

Retrieved from "https://wiki.appstudio.dev/index.php?title=Using_Node_and_Electron_to_build_Desktop_Apps&oldid=11623"