Using Node.js, we can create web applications easily. Now, thanks to the node-webkit we can also create desktop apps with it, using a unique combination of HTML5 and Node.
Introduction
The
library combines WebKit engine and Node.js in a unique way. Both WebKit
and Node share the same context, allowing you to write your code like
it’s meant to be executed in a browser, but with the addition of all
Node’s features.
The list of uses is endless. You can create
business apps, text and image editors, games, presentations, admin
panels, etc. Just name the desktop app that you would like to create,
and I can assure you that it will be possible with node-webkit.
In this tutorial, I will show you how to get started by showing you how to create a simple text editor.
Preparation
First,
you have to get the library. Download the version appropriate for your
operating system (the application itself will run on all of them) from github and unzip it wherever you’d like. Now, lets create a basic folder structure. We will have folders for HTML files (.html) and for JavaScript files (.js). Also, create the package.json file in the same directory that the nw executable is in and a node_modules folder to keep the modules we will create.
Package.json
The first thing to do is to fill the required fields in the package.json file. In the case of node-webkit these are name and main (on Github you can find the full list of available package.json
options). The first one is exactly the same as in the case of a plain
Node.js app. The second one should be a (relative or absolute) path to
the main HTML file that will be displayed upon the application starting.
In the case of our example, the package.json file should look like this:
1
2
3
4
{
"name": "simple-text-editor",
"main": "./html/index.html"
}
Now if you run your app using the nw executable, you should see a blank screen like this:
The Main File
Creating
the user interface using node-webkit is no different than creating a
webpage (with the slight difference that you know the rendering engine,
so you don’t have to provide any fallbacks for older browsers, or use
libraries like jQuery – and actually you shouldn’t, because they include
fallback code that will slow down your app). Let’s create an index.html file that we will use:
1
2
3
4
5
6
7
8
9
<!DOCTYPE html>
<html>
<head>
<title>Simple Text Editor</title>
</head>
<body>
</body>
</html>
Let’s
also include (and create) the main JavaScript file that we will use, in
the body, so it will be executed after the DOM is loaded:
1
<scriptsrc="../js/main.js"></script>
Now the only thing that will change when you open the app will be the title.
Let’s Use Some Node
To show you how easily you can use Node.js in node-webkit, let’s read the contents of package.json and print it on the screen. Create the js/main.js file and put the following code in it:
As you can see, the code looks exactly the same as if you were writing it for Node. But then we use document.write to put the file contents on the page. No need to setup any local server.
Now open the app and you should see something like this:
Modules
There is another nice thing about node-webkit; You don’t have to include a series of <script> tags in your HTML if you want to split your code into modules. You can do it just like you do in Node.js – using require. Let’s create a simple module to read file contents to a textarea or write it to a file. Name the file file.js and put it in the node_modules directory. Now put the overall module structure in it:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
varfs = require('fs');
functionFile() {
functionopen(path, document) {
}
functionsave(path, document) {
}
this.open = open;
this.save = save;
}
module.exports = newFile;
As you can see this will be a static class with two public methods – one for opening the files and one for saving them.
The open method will look like this:
Pretty
simple right? The function accepts the path to the file as the first
parameter and puts the file’s contents into the element with an id of
“editor”. We also need to pass the document object to the function because the script is called using Node’s require and it doesn’t have access to the WebKit stuff directly.
The save method is as simple as the previous one:
Now let’s test if everything works. Change the contents of js/main.js to this:
1
2
3
varfile = require('file.js');
console.log(file.open, file.save);
Now if you go to the developer tools console and click the developer refresh
button in the right corner of the window you should see the two
functions from this module logged. This is another useful thing in
node-webkit – your console.log calls are being displayed in the developer tools console, so it’s easier to debug your apps.
Node-Webkit’s File Inputs
Let’s add two file inputs that we will need later:
Notice the nwsaveas
attribute in the second input. It is a special type of input from
node-webkit, that allows the user to select a non-existing file. Both of
the inputs are hidden, because we will only access them from
JavaScript. In node-webkit, file inputs are modified in a way that
allows you to fire a click event on them, so you can open
the file dialog without the user clicking on the input (with no need for
the workarounds like invisible inputs above the button). Now we can
move to the JavaScript.
First, remove the console.log call from the js/main.js file. Now put this code in there:
This code is responsible for showing the Open and Save dialogs. The clickInput
function does the main job here – it simulates the click event on the
input element – in a normal browser, this would be impossible from
security reasons, but here it’s not a security threat at all. Later,
there is a normal keyup event handler that checks if the proper key combination was pressed (Ctrl+O or Ctrl+S) and “clicks” on the inputs. Note that this would also be impossible to achieve in a browser – combinations like Ctrl+O and Ctrl+S are reserved for the browser’s internal use and no event fires when they are pressed (only Firefox fires events for them).
Now press the developer refresh button and you should see the appropriate dialog when you press Ctrl+S or Ctrl+O. They of course do nothing for now.
Creating the Editor
Now, since we will be creating a text editor, we need something to write on. Add the textarea to the HTML:
Thanks
to the module created earlier, the code is really simple. This is also
possible thanks to node-webkit, because in browsers (again for security
reasons) the value of the file input element is set to a fake path –
here it’s the path which was selected. Now open the app (or press the developer refresh button, if you didn’t closed it) and you should have a perfectly working text editor.
Further Enhancements
We
can also do a few other things to make the editor a bit more advanced
and useful. For example, let’s open a new window when a user presses Ctrl+N. First, add this require to the top of the script:
1
vargui = require('nw.gui');
The nw.gui module is a node-webkit’s library related to the user interface (you can read more about this on Node-webkit’s Github). Next add this else if to the document’s keyup listener:
And viola! If you refresh the app, now you can press Ctrl+N to open a new window. This function does differ from the normal window.open though. You can pass various window options as the second parameter. The list of what you can set there is available in the documentation.
Another
thing that may be useful in a text editor is an application menu (the
one that sits under the title bar in Windows/Linux and on the top of the
screen on Mac). In node-webkit it’s pretty simple. First, let’s create
the menu:
1
varmenu = newgui.Menu({ type: 'menubar'});
The type menubar is reserved for the application menu. Now we can add items to it. Let it be a File menu:
1
2
3
4
menu.append(newgui.MenuItem({
label: 'File',
submenu: newgui.Menu()
}));
Now let’s add some items to this menu:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
menu.items[0].submenu.append(newgui.MenuItem({
label: 'New',
click: function() {
gui.Window.open('index.html');
}
}));
menu.items[0].submenu.append(newgui.MenuItem({
type: 'separator'
}));
menu.items[0].submenu.append(newgui.MenuItem({
label: 'Close',
click: function() {
gui.Window.get().close();
}
}));
menu.items[0]
is the first item of our application menu (you can also assign it to a
variable when creating it if you want to). We are appending new items to
its submenu, and each item gets a click callback to handle the click on it. The gui.Window.get method gets the current window, so we can close it when the user selects the Close option in the File menu.
Finally, we can assign the menu to the window:
1
gui.Window.get().menu = menu;
Again, we are using gui.Window.get to get the current window, then we are assigning our menu to its menu
property. Please note, that even though we can assign a different menu
to every window, on OSX (Mac) one app can only have one menu (which is
global for all windows), so if you want your app to be used on Macs, you
should avoid using different menus on different windows.
Now if you open or refresh your app, you should see a system menu under the titlebar:
Packaging the App
Now
if you would like to share your app with other users, you can package
it into one file, so the users can download the node-webkit’s executable
appropriate to their platform and launch your app with it. First, let’s
remove the toolbar that makes the window look like a
browser – it’s nice to have during development, but your users probably
don’t want to see it. We can achieve this by setting window.toolbar to false in package.json, so it looks like this:
1
2
3
4
5
6
7
{
"name": "example-app",
"main": "./html/index.html",
"window": {
"toolbar": false
}
}
Now if you open the app (nothing will change if you just refresh it, package.json is loaded only on startup), you should see the final result: Packaging the app is pretty simple. Just create a .zip
archive with all your assets (all of the files you created, without the
files supplied with node-webkit) and change its extension to .nw.
That’s all. If a user downloads node-webkit and your package, they only
need to put it in the node-webkit’s directory and run the nw executable. Detailed descriptions, with a few more tips, are available on the node-webkit’s github.
Now your editor is ready to be shipped to your users.
Conclusion
As
you can see, node-webkit is a very promising and powerful library. With
frequent updates and fixes, and being supported by Intel, there’s
almost no chance that it will be discontinued, which can sometimes
happen with open source projects.
Share your thoughts about this
project in the comments below. I personally think it’s the best thing
out there if you want to create a desktop application using Node.js and
HTML.
from http://net.tutsplus.com/tutorials/javascript-ajax/introduction-to-html5-desktop-apps-with-node-webkit/
------------------------------------------------------------------ node-webkit
Good performance: Node and WebKit runs in the same thread: Function
calls are made straightforward; objects are in the same heap and can
just reference each other;
<!DOCTYPE html><html><head><title>Hello World!</title></head><body><h1>Hello World!</h1>
We are using node.js <script>document.write(process.version)</script>.
</body></html>
Create package.json:
{"name":"nw-demo","main":"index.html"}
Compress index.html and package.json into a zip archive called app.nw:
$ zip app.nw index.html package.json
This should create a structure like this:
app.nw
|-- package.json
`-- index.html
Download the prebuilt binary for your platform and use it to open the
app.nw file:
$ ./nw app.nw
Note: on Windows, you can drag the app.nw to nw.exe to open it.
Documents
For more information on how to write/package/run apps, see:
We use the node-webkit group as
our mailing list. Subscribe via node-webkit+subscribe@googlegroups.com.
Issues are being tracked here on GitHub.
You can chat with us on IRC in the ##node-webkit channel on irc.freenode.net
