JavaScript: Desktop Applications with NWJS

It’s been an exciting few years for JavaScript; new devices and technologies are pushing the boundaries of what we thought we could do with the language.

For many years my playground was the browser… it wasn’t always a nice playground, it was full of bullies like IE7 and his older brother, the brutal IE6, but with the advent of smartphones and tablets, things started to change, albeit gradually.

After a while it started getting interesting. We went from browser, to mobile browser, to hybrid applications, to native applications, to backend, to cloud collaboration tools, to robotics and desktop applications …all with JavaScript!

But I digress, getting back to the matter at hand… after researching the topic of JavaScript desktop applications a bit and going through a few frameworks I stumbled upon nwjs.io which in their own words:

lets you call all Node.js modules directly from DOM and enables a new way of writing applications with all Web technologies. It was previously known as “node-webkit” project.

NWJS runs on NodeJS and Chromium. I’m going to take a few moments to explain how to set it up, create a build process which will automatically package your app for all supported platforms (Windows, Linux and Mac OS X — 32 & 64-bit) and start developing desktop apps using your favorite frameworks and libraries.

Please keep in mind that at the time of this article, the stable version of NWJS is v0.13.2. We’re also going to need a few other things: NodeJS and Gulp.

1. Download and install NodeJS and NWJS (SDK version)
2. Once NodeJS is installed, you’ll also have access to NPM (node package manager) which is a command line tool that comes bundled with NodeJS. Test if everything works by running node -v and npm -v in a terminal.
3. If you’re on a Mac that has OSX 10.11 El Capitan you might experience a strange behavior where node works but npm doesn’t. Read this article… it should help.
4. You might have noticed that NWJS doesn’t have an installer… that’s OK, just unzip that archive to a location of your choice and add it your system PATH so you can access the nw binary globally. To do that open a terminal and run one of the following commands (make sure you don’t misspell it and enter the correct path to the nwjs folder!):

# windowsset PATH=%PATH%;X:\path\to\nwjs\

# linux & macPATH=$PATH:~/path/to/nwjs

# restart all terminals and test if it's working by runningnw

# if it works, a dummy desktop app will start

At this point you’re done with the main setup. We’ll use Gulp to handle tasks like CSS & JS minification / packaging and distribution so open a terminal and install it (globally — if you don’t have it already) by running:

npm install -g gulp

NWJS is unopinionated with regards to the frameworks and libraries you use to create the desktop app, so you can pick whatever you like. At this point I’d like to provide a link to the nwjs-boilerplate for all you impatient readers:

raduGaspar/nwjs-boilerplate_nwjs-boilerplate - Boilerplate setup for nwjs desktop apps_github.com

The boilerplate is very simple. It has a few dependencies used to package and build the app and a single HTML file (used as the entry/start point) which loads one CSS file and one JS file.

The JS file simply illustrates how to open the developer tools; F12 won’t work here unless you add that functionality into the application yourself, neither will Ctrl+Shift+I. To run the boilerplate execute the following commands in the project folder:

npm install -d # will install npm dependenciesnw . # will run the app

Don’t forget that dot at the end, it tells nw that the package.json it needs in order to run the app is in the current folder; if you don’t add it, you’ll get a default nwjs app running instead.

So let’s break the boilerplate down into its components:

• package.json — this can be generated by running npm init and it’s usually found in applications that make use of npm. In NWJS it has another function: you use it to define application specific parameters like the: window size, application icon, transparency, toolbar, title, position and many others as well as the application entry/start point… in our case that would be main: index.html.
• the devDependencies in package.json are needed for the tasks defined in gulpfile.js.
• gulpfile.js — used to define tasks and automation; in our case we use gulp to read the index.html file and find all CSS and JS files it loads. We then merge and minify/uglify all CSS and JS files, generate a new index.html which loads the resulting CSS and JS assets, create a dist folder which holds all of the files we just created as well as any npm dependencies (we don’t have any in the boilerplate) and the original package.json needed by nw to run.
• package.js —uses nw-builder (a developer dependency npm package) to read all of the files in the dist folder and release the application for all operating systems we defined in the platforms array. As you can see we’re only targeting x64 platforms, but you can add x32 if that’s a requirement.

Please note that at the time of this article, packaging NWJS apps built with v0.13.2 still has bugs and sometimes doesn’t work (hopefully not for long). It does however work fine with v0.12.3. You can change which version to use in package.js.

If you looked closely at package.json we have a command inside scripts called nwjs which calls gulp and node package.js. This will create a dist folder and package your app. Running it from the command line is simple:

npm run nwjs

I also have an actual project for you to look at which uses: NWJS (v0.12.x), AngularJS (1.x), SASS, Compass and NEDB to create a desktop application that manages TV shows. Hopefully this will give you a better understanding of NWJS:

raduGaspar/nwjs-show-tracker_nwjs-show-tracker - A simple interface for tracking tv shows._github.com

Explore for yourselves, be on the lookout for new releases to nw-builder have some fun and see how far you can take it. Don’t forget that you’re developing on Chromium so there’s no need to worry about cross-browser compatibility, if it works for you, it will work for everyone. Happy coding!