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, JavaScrpt, 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:

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

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) called CouchbaseProject. Inside this directory, create a
main.js and package.json file. Starting with the package.json file, add the following

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

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

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:

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:

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:

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.


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.


Posted by Nic Raboy, Developer Advocate, Couchbase

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in Java, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Apache Cordova. Nic writes about his development experiences related to making web and mobile development easier to understand.


  1. what address do i use from electron to tell sync-gateway the data is coming from? In the app you used localhost:9000. Is that true when i distribute my app to team?

    1. I am using couchbase at my office with sync-gateway. the app on laptops in windows with electron.

    2. Well, an Electron application is not considered a web application. You shouldn\’t have cross origin resource sharing (CORS) issues. You just need to make sure the Electron application points to your Sync Gateway.


      1. thank you for your response, i have your angular app pre-electron syncing with couchbase sync-gateway. Are you saying that when i add these additions above we expect it to still sync?

        also the console is showing that jquery is misssing??

        1. Yes, just bundle the application in Electron. jQuery is missing because I didn\’t add it. I didn\’t add it because I wasn\’t using Bootstrap features that used it. You can ignore it.


      2. I got it working, all of this troubleshooting i miss a line that i commented out. Thank you so much. your tutorials are very helpful. i also follow your other tutorials. thanks

        1. No problem :-)

  2. any idea whats going on here?

    2016-04-28T22:55:47.375-04:00 Changes+: Notifying to check for _changes feed termination
    2016-04-28T22:55:47.375-04:00 Changes: MultiChangesFeed done
    2016-04-28T22:55:48.294-04:00 HTTP: #040: GET /test-database/_changes?timeout=25000&style=all_docs&feed=longpoll&since=5&limit=96&_nonce=1461898548292
    2016-04-28T22:55:48.294-04:00 Changes+: Int sequence multi changes feed…
    2016-04-28T22:55:48.294-04:00 Changes: MultiChangesFeed({*}, {Since:5 Limit:96 Conflicts:true IncludeDocs:false Wait:true Continuous:false Terminator:0xc820875a40 HeartbeatMs:0 TimeoutMs:25000 ActiveOnly:false}) …
    2016-04-28T22:55:48.294-04:00 Changes+: MultiChangesFeed: channels expand to channels.TimedSet{\”!\”:channels.VbSequence{VbNo:(*uint16)(nil), Sequence:0x1}, \”*\”:channels.VbSequence{VbNo:(*uint16)(nil), Sequence:0x1}} …
    2016-04-28T22:55:48.294-04:00 Changes+: MultiChangesFeed waiting…
    2016-04-28T22:55:48.294-04:00 Changes+: Waiting for \”test-database\”\’s count to pass 7

    1. I don\’t see anything out of the ordinary. What is and isn\’t it doing? A little more context would be helpful.


      1. I\’m probably misunderstanding something. The contents I posted is my terminal output when I run:

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

        And then relaunch the app with electron .

        In the browser window of http://localhost:4985, it just has some version information.

        {\”ADMIN\”:true,\”couchdb\”:\”Welcome\”,\”vendor\”:{\”name\”:\”Couchbase Sync Gateway\”,\”version\”:1.2},\”version\”:\”Couchbase Sync Gateway/1.2.0(79;9df63a5)\”}

        There\’s nothing there or in my app to suggest I am syncing records. If I put two records in my app (name, email, etc) I don\’t see it on http://localhost:4985. Should I see it there?

        What should I see when I attempt to validate that it is running by visiting http://localhost:4985 from the web browser? I\’m probably missing one thing or a lot of things. Thanks for any hints.

        1. You probably want to use port 4984, rather than 4985.

          Let me know if that corrects the issue for you.


          1. Thanks for your reply. I\’m going to have to look into this when I have more time. I tried both ports you listed (one is admin the other is not). Neither replicated data from the application. It could be an issue with my mac or silly oversight that will take a while to figure out.

  3. I have tried your example locally on my mac, it worked fine as expected, now If I were to compile my electron app and use on some other mac or windows machine, what should be the changes required so that all the users can have a different set of data buckets and they can use the app individually.

    1. You wouldn\’t be giving each user their own bucket. Instead you should use the authentication features baked into sync gateway for read and write permissions.

      Then you can have a full fledged app with many users

  4. […] years ago I wrote about using Couchbase in a desktop application using AngularJS 1.0 and Electron, but with technology there might as well have been dinosaurs in that time period. A lot has changed […]

  5. […] above may look familiar for two reasons. One I took it from a previous post I wrote on Electron and two, it came pretty much straight from the Electron documentation. Our […]

Leave a reply