Build a Desktop App With GitHub Electron and Couchbase

So, I've been using Atom by GitHub as my text editor of choice for a little more than a year now. In case you're unaware, it is an open source text editor that runs on GitHub's own Electron platform. To summarize, Electron lets you build cross platform desktop apps using web technologies like HTML, JavaScript, and CSS. Essentially, Electron is for desktop what Apache Cordova is for mobile.

So, where am I going with this? Well, using Electron and various web technologies, we're able to build cross platform desktop applications that sync great with Couchbase Server!

We're going to take a working example I wrote previously and convert it into a stand alone desktop application that you can distribute to Mac, Windows, and even Linux. The example we're looking at in particular is the PouchDB with AngularJS tutorial I wrote. If you haven't already read this tutorial, I recommend you read it here, otherwise you can head straight to the tutorial source code for this guide.

Installing Electron for Development on Your Machine

Before we can bundle our application with Electron, we have to install it on our machine. We'll be using the Node Package Manager (NPM) to install our dependencies so if you haven't already installed Node.js on your machine, please head over to the Node.js website and do so now.

With Node.js installed, run the following from the Command Prompt (Windows) or Terminal (Linux and Mac) to install Electron globally to your machine:

npm install -g electron-prebuilt

If you're on Mac or Linux, you may need to run the command as an administrator. This can be done using sudo only if necessary.

Preparing the Electron Application Container

For the most part, you don't need to make any revisions to your static web application (HTML, JavaScript, CSS) in order to make use of Electron. However, you will need to set up a few files so Electron can understand your project.

Go ahead and create a new directory (maybe on your Desktop) calledCouchbaseProject. Inside this directory, create a main.js and package.json file. Starting with the package.json file, add the following code:

{
    "name"    : "electron-couchbase",
    "version" : "0.0.1",
    "main"    : "main.js"
}

According to the Electron documentation, it is important the main property uses a filename that matches what you created in your project.

Now we can add code to our project's main.js file. Open it and add the following:

var app = require('app');  // Module to control application life.
var BrowserWindow = require('browser-window');  // Module to create native browser window.

// Report crashes to our server.
require('crash-reporter').start();

// Keep a global reference of the window object, if you don't, the window will
// be closed automatically when the JavaScript object is garbage collected.
var mainWindow = null;

// Quit when all windows are closed.
app.on('window-all-closed', function() {
    // On OS X it is common for applications and their menu bar
    // to stay active until the user quits explicitly with Cmd + Q
    if (process.platform != 'darwin') {
        app.quit();
    }
});

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
app.on('ready', function() {
    // Create the browser window.
    mainWindow = new BrowserWindow({width: 800, height: 600});

    // and load the index.html of the app.
    mainWindow.loadUrl('file://' + __dirname + '/public/index.html');

    // Emitted when the window is closed.
    mainWindow.on('closed', function() {
        // Dereference the window object, usually you would store windows
        // in an array if your app supports multi windows, this is the time
        // when you should delete the corresponding element.
        mainWindow = null;
    });
});

To be fair, this main.js code was copied pretty much exactly from the Electron quickstart documentation. You should note that the differences between the two are that my version does not show the Chrome Inspector and that our web files will exist in the public directory of our project.

Coding Our Web Hybrid Desktop Application Using Couchbase and Electron

This is where the magic happens. Remember, I told you we will be using the AngularJS, PouchDB, Couchbase project source code from a previous tutorial. With the CouchbaseProject as our current working directory in the Command Prompt or Terminal, run the following:

git clone https://github.com/couchbaselabs/pouchdb-angularjs-app public

The above command will clone the previous project and rename it as public to accommodate the requirement we set in the main.js file.

Running Our Electron Desktop Application

As of now the project should be runnable. With CouchbaseProject as your current working directory in the Command Prompt or Terminal, run the following:

electron .

With a little bit of luck, it should start running. However, just because our application is running and saving data, it doesn't mean we are synchronizing with Couchbase Server. We actually need to start the Couchbase Sync Gateway.

Running the Couchbase Sync Gateway

The Couchbase Sync Gateway is responsible for syncing to the server from our local application and from the server back down to our local application. It works with mobile applications as well as, in our case, PouchDB inspired desktop applications. The Couchbase Sync Gateway can be downloaded here.

When you cloned the AngularJS/PouchDB project from GitHub, there was also a Sync Gateway configuration file in it. Feel free to use that file for this example. Move it to your desktop, or somewhere outside the application directory and run the following:

/path/to/sync/gateway/bin/sync_gateway /path/to/project/sync-gateway-config.json

You can validate that it is running by visiting http://localhost:4985 from your web browser.

With Couchbase Sync Gateway running, relaunch your Electron application and you should notice it replicating data.

Conclusion

Congratulations! You just built a cross platform desktop application using nothing more than web technologies like HTML, JavaScript, and CSS. What's even better is this desktop application will synchronize with Couchbase Server.

If you want to do further reading on how to deploy this application as a stand-alone binary, it can be found in the official GitHub Electron documentation.