Node Webkit – Build Desktop Apps with Node and Web Technologies10 min read

Getting Started with Node Webkit apps

Looking for a real time implementation? Check : Node Webkit powered Dashboard application

In this post, we will see how to build cross OS desktop apps using Node js and Web technologies. We will take a look at building and running a simple node webkit app and then expand on it by adding different features like platform services, node modules etc.

You can find the code for the examples in this post here.

So, let us get started.

Contents

What is node webkit

node-webkit is an app runtime based on Chromium and node.js. You can write native apps in HTML and JavaScript with node-webkit. It also lets you call Node.js modules directly from the DOM and enables a new way of writing native applications with all Web technologies.

It’s created and developed in the Intel Open Source Technology Center.

Setting up node webkit

To build a desktop app using node webkit, we will need to get the prebuilt binaries. Then we will pass our application to the node webkit lib to run the app.

Navigate to the downloads section and pick a copy depending on your OS. Now, create a new folder named myNodeWebkitApps and unzip the download here. To keep things simple, rename the unzipped folder to nw.

Hello node webkit

Now, we will build a “hello world” app. Create another folder named helloWorld inside myNodeWebKitApps folder. The folder structure so far would be

Screen Shot 2014-07-12 at 11.13.12 am

Next, open a terminal/prompt inside the helloWorld folder and run

npm init

and fill it up like

Screen Shot 2014-07-12 at 9.30.05 pmThis will generate a standard package.json file. To run a node webkit app, you need only 2 properties

  1. main – The first file that needs to be executed when the app is launched
  2. name -The name of the package. This must be a unique, lowercase alpha-numeric name without spaces. It may include “.” or “_” or “-” characters. It is otherwise opaque.

As we have mentioned in the package.json, our starter file would be index.html. Create a new file named index.html at the root of helloWorld folder and open it up in your favorite editor. We will be displaying “Hello Node Webkit” in a header tag as the final output. Add the below code to index.html

That is all we need to run our app.

Run the application

To run the application, we need to zip (not rar or 7z) files (not the folder itself) and rename the file to app.nw.

Note : The nw app name SHOULD be in lowercase.

Back to the helloWorld folder, select the files (index.html and package.json) and zip them. Now rename the file to app.nw. The file structure inside helloWorld folder would be

Screen Shot 2014-07-12 at 12.20.19 pmIf you are on a Mac, you can navigate back to the nw folder and launch the node-webkit.app and you will see

Screen Shot 2014-07-12 at 12.22.02 pmclick on open and you will see the default welcome page. Close the app. Now if you go back to the helloWorld folder, you should see that the OS has recognized the type of the app.

Screen Shot 2014-07-12 at 12.09.31 pm
 Now, click on app.nw and you will see Screen Shot 2014-07-12 at 12.11.18 pm

If you are running on a Windows machine, you need to execute the below command. Make sure you are running the command from inside the helloWorld folder

../nw/nw.exe app.nw

and you should see

win_hw

As you can see, we have a frame and toolbar on top as it is with any browser. And if you click on the gear icon next to the address bar, the dev tools would open and you can debug the app as you would any other web page.

Simple and easy right?

Note : If you are using Sublime text for your development, you can check this to debug the apps without the hassle of zipping and renaming. But for this post, I will be manually doing all the above steps to run the app.

You can also notice that once you launch the app, it starts behaving like a desktop application. In Mac, you can see the global menu reflecting the current active app

Screen Shot 2014-07-12 at 12.38.28 pm

Some more config options

node webkit provides 2 more sets of configurations that can control the app. First we will take a look at the window object.

In our hello node webkit app, if you would like to get rid of the address bar, you can set the toolbar property to false. To test this, open up package.json and update it as

To run the app, we need to follow the same steps we did earlier again. select the files (index.html and package.json) and create a new zip file. And then rename the zip file to app.nw. Just to keep track of old changes, I will rename the older nw file as v1. The file structure would be Screen Shot 2014-07-12 at 12.45.04 pm

Now, launch app.nw and you should see

Screen Shot 2014-07-12 at 12.48.38 pmAs you must have seen by now, you can resize the window too. You can control that by setting

And also, you can notice that the window can be resized to a ridiculously small size. You can control the width/min_width/max_width and height/min_height/max_height like

You can also control the position where the app opens when launched. You can open the app in the center or at the position of the mouse. The config for that would be

You can explore more options here.

Apart from the window, we can also control webkit options too. You can select if you want to load flash/external plugins or Java applets or enable page cache. The updated package.json would look like

You can compress the files, change the extension from zip to nw and launch the app. The above settings will not have an impact on our current “Hello World” app.

Adding Native features

Menu bar

Now, we have a fair feeling that our app can function like a desktop app, lets us make it more desktop-ish. If you did notice, our hello world app has a native minimize, maximize, un-maximize and close buttons. If you want, you can get rid of those by setting frame : false  in the windows config in package.json. This will remove the buttons and the title bar. Now, you can write your own components and add event listeners to it. You can find more info on that here.

Now, we will try and add a few menu items to our app. I will add a few random menu items, to showcase the feature.

Open index.html in your favorite editor and add the below code

To build a menu, we will be using the nw.gui  module. As you can read from the name, it holds all the node webkits’s GUI modules. We will use the Menu()  to create an empty menu and using MenuItem() , we will add sub-menus to it.

We will need to write different code for Mac and Windows, so the Menu bars look native-ish.

Mac : In index.html, below the comment “menu logic goes here”, add the code

Windows : In index.html, below the comment “menu logic goes here”, add the code

Next, to enable debugging, open package.json and set {toolbar : true}. Save all the files, zip, rename and launch the app.

On Mac,

Screen Shot 2014-07-12 at 1.55.00 pm

And when you click on the menu links, you will see the alerts.

On Windows

win_hw_2

As with any menu, you can add sub menus too.

Mac : Update the script in index.html to

Windows : Update the script in index.html to

And when you save and launch the app, you should see

Screen Shot 2014-07-12 at 2.15.19 pmon Mac and on Windows

win_hw_2

If you are facing issues, you can throw in a debugger;  command in the js code. And when the app is running, you can click on the gear icon and inspect the same in dev tools.

Screen Shot 2014-07-12 at 2.24.18 pm

Simple right? You can check out Menu and Window Menu docs to get more information.

Tray

We can make our app behave like a “Tray” app (on Mac)

Screen Shot 2014-07-12 at 9.40.54 pmor Windows

win_hw_2

You can update the script in index.html with (both Mac and Windows)

You can read more about Tray apps here.

Clipboard

You can get the contents of the clipboard using the  Clipboard.get(). Add the below code to index.html after the tray setup.

And when you zip and launch the app, you should see the clipboard text alerted.

Screen Shot 2014-07-12 at 2.54.49 pm

You can read more about platform services here.

Using Node Modules

We can also leverage the power of the existing node modules to build desktop apps. For example, if you want your app to have a local persistence, you can use a node module named diskDB. This will create a local JSON file which you can manage with a MongoDB like API.

Let us build a sample settings page using diskDB and node webkit. Create a new folder inside myWebKitApps and name it diskDBApp. Open terminal/prompt here and run

npm init

Next, run

npm install diskdb --save

This will download the diskdb and required files. The final package.json would look like

Next, create a new folder named appPersistence at the root of the diskDBApp folder, where we store the JSON files locally.

Now, we create index.html file at the root of diskDBApp and open it in your favorite editor. Update the file like

The above code uses diskDB API to create a settings file and store the data. Then we will use the find()  to return all the settings and display the data. SImple and easy right?

To run the app, zip all the folders and files and rename the app as diskDBApp.nw. And when you launch the app, you will see

Screen Shot 2014-07-12 at 3.51.06 pm

win_hw_2

Very powerful right? You can use other node package as you need them.

Note : Not all node modules work well on all platforms.

Distribute the App

So far, we have zipped and ran the app locally. For the app to run, we need to have the node-webkit executable available (duh!). This is one of the ways of distributing the app, in case the end users of the app are familiar with node webkit.

Another way of distributing the app is to share your app with the nw executable. You can read more about that here.

Another option is to use node-webkit-builder. I found node-webkit-builder more reliable while generating cross platform executable. We will be leveraging Gulp to perform this task for us. At the root of the diskDBApp, create a new file named GulpFile.js and add the below contents.

Next, we will install the required dependencies. Run

npm install --save-dev gulp gulp-util node-webkit-builder

Now run

gulp nw

This will launch the build task and generate the required installer.

Screen Shot 2014-07-12 at 4.30.23 pmAfter the task is completed, you will see a new folder named build, which will consist of the installer

Screen Shot 2014-07-12 at 4.32.41 pm

Do notice the size of the app (~90 MB).

If the build is not working as expected on Windows, you can try nodebob.

First, you need to clone the nodebob repo. CD  into myNodeWebkitApps folder and run

git clone https://github.com/geo8bit/nodebob.git nodebob

Next, navigate to  myNodeWebkitApps\nodebob\app folder and delete all its contents. Now, copy only the below from myNodeWebkitApps\diskDBApp folder

  • appPersistence folder
  • node_modules folder (with only diskDB inside it)
  • index.html
  • package.json

into myNodeWebkitApps\nodebob\app folder.

Back to nodebob folder, Execute (double click) on build.bat and in a few seconds,  the build would be completed. You can navigate to myNodeWebkitApps\nodebob\release folder to see the installer generated. It will be named as nw.exe.

You can launch it and it should display the setting from the JSON file.

App Security

As you already know, we are distributing a zip file that consists of our logic and assets. There may be times, when you would like to protect your app’s logic and assets. You can achieve the same using V8 snapshots. More info here.

Hope you got a decent idea on how to build Desktop apps using Node Webkit.


Thanks for reading! Do comment.
@arvindr21