Editor’s Note: As some of you may know, the node-webkit project was rebranded “nw.js” because they are now using io.js and Chromium. This article was written long before that change. We’re working on a new article with updates examples for you, but much of the content below still applies!

Web applications are useful, but there are some cases where it’s not desirable or necessary to host an application on a remote server. As HTML5 provides low-level functionality to modern browsers, such as the ability to read and write files, it’s now possible to create offline, single-page, JavaScript applications using a web browser as a platform.

While browser-based unhosted applications present some interesting possibilities, such as the ability to deploy your application on multiple operating systems, there are some significant limitations.

When using browsers one’s control of the user interface is limited. Some interface elements, such as pull-down menus, can’t be customized and there is usually no way to hide the browser’s address bar programatically.

Another potential issue with web applications in general is variance between browsers and browser versions. As HTML5 is still evolving, special care needs to be taken to ensure that everything works in all major browsers.

Last, but not least, most browsers are configured to be secure against malicious content. The same origin policy, for example, is enforced by default, preventing a site on one domain from making an AJAX call to another.

Enter Node-WebKit

The node-webkit project, which was created at Intel and open sourced in 2011, is an attempt to take the pain out of offline single-page application development.

The project provides a WebKit browser that has been extended with the the ability to control user interface elements normally off-limits to web developers. The browser’s security configuration is relaxed, assuming that the application code you’re runnning is trusted. And, most interestingly, the browser integrates Node.js, allowing node-webkit applications to leverage a wide array of functionality other than what HTML5 APIs provide.

Now that you’ve got an idea what node-webkit is and what it’s useful for, let’s talk about how to install it.

Installation

node-webkit can be installed on Windows, OS X, and Linux. node-webkit, like Node.js, is easy to install. The “Downloads” section on the project’s Github page supplies a number archives containing ready-to-run node-webkit binaries and software libaries they depend on.

Once you’ve download the appropriate archive, you’ll need to locate the node-webkit binary. The Linux binary’s filename is nw. The Window binary’s filename is nw.exe. In the OS X version, which comes packaged as an application bundle, the binary is in the Contents/MasOS folder and the filename is node-wekit (for example /path/to/node-webkit.app/Contents/MacOS/node-webkit).

To install node-webkit, simply put the folder containing your node-webkit binary in a convenient place.

Creating a simple application

node-webkit applications are created in a similar fashion to conventional Node web applications. An application directory is created in which application resources — such as HTML, CSS, JavaScript, and media — are placed.

As with Node, a package.json file is used to describe the application.

In the package.json file, an element “main” specifies the first HTML page that node-webkit should display: “index.html” for example. As with a conventional single page application, the “main” HTML file must include necessary JavaScript and CSS.

The package.json file is also used to configure the properties of node-webkit’s default window. Below is an example of a node-webkit package.json file:

In the window specification height, width, and whether the address bar should be included can be set. node-webkit applications can even be put into a full-screen “kiosk” mode, preventing users from exiting into the host operating system.

Using Node Functionality

Including Node functionality in your application is fairly straightforward. As with conventional Node applications, Node modules can be installed using [npm]. A markdown module, for example, could be installed using the following command:

node-webkit can include any module in your application’s node_modules directory by using a “require” statement, as the example below shows.

Now that you’ve learned the basics of application creation, let’s look at how your can package your application, enablnig you to run it yourself or distribute it to others.

Packaging Your Application

Packaging is very simple: you need only create a ZIP archive. To do so use a GUI archiving tool or, if using the OS X or Linux command-line, enter the following from within your project directory:

After zipping your application, you should rename it, giving it the extension .nw to indicate that it’s a node-webkit application. The zipped application can be executed using the node-webkit runtime. For example:

To make distribution easier, stand-alone node-webkit applications can be created. This means that application end users don’t need to install node-webkit, or even know what it is. Check out the project’s wiki page for details.

Example Applications

If node-webkit sounds like something you’d like to play with, the nw-sample-apps project provides a number of example applications you can learn from and experiment with.

If you run into difficulties, a Google Group exists for questions and discussion about the technology. Have fun with node-webkit!