Getting Started with NW.js

What can NW.js do?

NW.js is based on Chromium and Node.js. It lets you call Node.js code and modules directly from browser and also use Web technologies in your app. Further, you can easily package a web application to a native application.

Get NW.js

You can get the latest binaries from official website http://nwjs.io. Or you can also build NW.js binaries yourself by following the instructions in Building NW.js.

Tip

You are recommended to choose SDK build flavor to develop your app, which enables you to use DevTools to debug your app. See Build Flavors for the differences between build flavors.

Write NW.js App

Example 1 - Hello World

This the basic example shows how to write an NW.js app.

Step 1. Create package.json:

{
  "name": "helloworld",
  "main": "index.html"
}

package.json is the manifest file in your app. It is written in JSON format. The main field figures out the first page opened by the NW.js if referenced to an HTML file, "index.html" in this example. And the name field is the unique name used among NW.js apps. See Manifest Format for more details.

Use JS File as Main

You can set JS file as in "main" field as well, like "main.js". Then the JS file will be loaded in the background page on start and no window is opened by default. Usually you can do some initialization and open the window manually later. For example,

// initialize your app
// and ...
nw.Window.open('index.html', {}, function(win) {});

Step 2. Create index.html:

<!DOCTYPE html>
<html>
  <head>
    <title>Hello World!</title>
  </head>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>

This is the normal HTML file. You can use any web technologies supported by latest browsers.

Step 3. Run your app

cd /path/to/your/app
/path/to/nw .

/path/to/nw is the binary file of NW.js. On Windows, it’s nw.exe; On Linux, it’s nw; On Mac, it’s nwjs.app/Contents/MacOS/nwjs.

Drag & Drop on Windows

On Windows, you can drag the folder containing package.json to nw.exe to run your app.

Example 2 - Using NW.js APIs

All NW.js APIs are loaded in nw object globally and can be used directly in JavaScript files. See API References for full list of supported APIs.

This example shows how to create a native context menu in your NW.js app. You can create index.html with following content:

<!DOCTYPE html>
<html>
<head>
  <title>Context Menu</title>
</head>
<body>

<p>'Right click' here to show context menu.</p>

<script>
// Create an empty context menu
var menu = new nw.Menu();

// Add some items with label
menu.append(new nw.MenuItem({
  label: 'Item A',
  click: function(){
    alert('You have clicked at "Item A"');
  }
}));
menu.append(new nw.MenuItem({ label: 'Item B' }));
menu.append(new nw.MenuItem({ type: 'separator' }));
menu.append(new nw.MenuItem({ label: 'Item C' }));

// Hooks the "contextmenu" event
document.body.addEventListener('contextmenu', function(ev) {
  // Prevent showing default context menu
  ev.preventDefault();
  // Popup the native context menu at place you click
  menu.popup(ev.x, ev.y);

  return false;
}, false);

</script>  
</body>
</html>

… then run your app:

cd /path/to/your/app
/path/to/nw .

require(‘nw.gui’)

The legacy way of loading NW.js APIs using require('nw.gui') is also supported. It returns the same nw object.

Example 3 - Using Node.js API

You can call node.js and modules directly from the DOM. So it enables endless possibilities for writing apps with nw.js.

This example shows how to query the OS platform with os module of Node.js. Simply create the index.html file with following content and run it with NW.js.

<!DOCTYPE html>
<html>
<head>
  <title>My OS Platform</title>
</head>
<body>
<script>
// get the system platform using node.js
var os = require('os');
document.write('You are running on ', os.platform());
</script>
</body>
</html>

You could also use the modules installed by npm with NW.js.

Native Node Modules

Native Node modules, built when running npm install, are not compatible with NW.js ABI. To use them, you have to rebuild it from source code with nw-gyp. See Use Native Node Modules for details.

What’s next

See Debugging with DevTools for debugging NW.js apps.

See Package and Distribute for packaging and redistribute your app in production.

See FAQ for issues you may encounter.

See the migration notes, if you are migrating your app from NW.js 0.12 or older versions.

Getting Help

There are lots of useful information on NW.js wiki. The wiki is also open for everyone, and you are encouraged to publish your knowledge on wiki.

You can also ask questions on mail list on Google group or chat on Gitter.

Please report bugs or submit requirements on GitHub to make NW.js more powerful.