Building web applications and mobile applications that share the same data is often thought of as a challenging task. How do you design your web application to fit with your mobile application and visa-versa? What happens when you want to use Couchbase to sync your data between mobile devices in real-time, but also have it available in a web browser?

There are several ways to accomplish this task with Couchbase, but we’re going to explore one of my personal favorites in this particular guide. We’re going to use a server side SDK for querying data and a RESTful API for writing data.

The Requirements

For this particular example we’re going to be using Node.js, but it really doesn’t matter which language you use as long as there is a Couchbase Server SDK available. The requirements for this project include the following:

  • Couchbase Server 4.1+
  • Couchbase Sync Gateway 1.3+
  • Node.js 4.0+

From a component perspective, Couchbase Server will house all of our data. In addition, it will be responsible for the heavy lifting involved with querying. We will not be writing directly to Couchbase Server from the Node.js SDK, but instead we’ll be using Couchbase Sync Gateway. Sync Gateway will save the data to Couchbase Server and pass it between mobile devices. Node.js will be the web application layer.

We won’t be building a mobile application in this particular example, but a mobile application would communicate to Sync Gateway and be used in a similar fashion. Mobile applications do not communicate directly with Couchbase Server.

Configuring Couchbase Server and Couchbase Sync Gateway

Before the application can be developed, both Couchbase Server and Couchbase Sync Gateway need to be installed and configured.

Download Couchbase Server for your operating system and proceed to its installation, making sure that the query (N1QL) service is enabled. For this example I’m going to be using a Couchbase bucket called example, but feel free to call it whatever you want.

With the example bucket created, a N1QL index must be added to allow querying of the data. From the Query Workbench or CBQ, execute the following:

Query Workbench is available in Couchbase Server Enterprise Edition, but the command line tool CBQ is available in both additions.

At this point Couchbase Server is ready to go.

Download and install Couchbase Sync Gateway for your operating system. Sync Gateway itself won’t be configured, but we’ll have a project configuration file that looks like the following running:

Call the above file sync-gateway-config.json and store it in your project. Essentially we are telling Sync Gateway that we want to connect to a particular Couchbase Server cluster and use the bucket example. Because we’ll be using RESTful requests from the same machine we need to allow CORS on port 3000.

To keep things simple, the synchronization logic will allow all documents to be passed around with no read or write rules.

Creating the Web Application

We’re not actually running Sync Gateway yet, but both Couchbase Server and Sync Gateway are ready for use. Now we can focus on creating our Node.js project.

The project itself is going to be a very simple example. We’re going to create a RESTful API with two endpoints, one for creating data and one for listing data. The catch here is that one endpoint will query Couchbase Server with the Node.js SDK directly and one endpoint will write data to Couchbase Sync Gateway via the Sync Gateway RESTful API.

Before we get ahead of ourselves, let’s start creating the project.

Creating a New Project and Bootstrapping the Code

Because we’re using Node.js, everything will be accomplished from the Command Prompt (Windows) or Terminal (Mac and Linux). Using one of these, execute the following:

The above command will create a new package.json file for our project. All of our project dependencies will be stored in this file.

Next execute the following to obtain all the dependencies that we need:

We’re going to use couchbase for communicating with our database, express for Express Framework, body-parser for accepting body data in requests, and request for making HTTP requests from within Node.js, not to Node.js.

At this point we can start bootstrapping the application.

Create a file called index.js within the project. We are going to use it for our entire application. In larger or production applications you might consider breaking it up into more precise files for maintainability, but for this example it is fine.

Open index.js and include the following imports:

The dependencies that we had earlier downloaded have now been imported into the project. However, they have not been initialized.

The above lines initialize Express Framework, prepare N1QL within the application, and enable the acceptance of JSON and URL encoded data within requests bodies.

While N1QL is pretty much good to go, we haven’t connected to the server cluster or opened our bucket. This can be accomplished through the following:

Again, we are using a bucket that I’ve named example in a previous step.

Finally, as the last part of our project bootstrapping, we can start serving the application:

When running, the web application will be accessible from http://localhost:3000 in a web browser and elsewhere.

Adding the Couchbase Node.js SDK and RESTful Sync Gateway Logic

Like mentioned previous, this application is going to remain simple so it is easy to understand. We are only goine to have two endpoints, one that uses the Couchbase Server SDK, and one that uses the Sync Gateway RESTful API.

These two endpoints will look like the following:

Starting with the /list endpoint we have the following code:

When a GET request is made to this endpoint a N1QL query will be executed against Couchbase Server. This query will get the type, firstname, and lastname properties of every document in the particular bucket as long as those documents have a type property that equals person. If there is an error, return an error to the user, otherwise return the data that was retrieved.

The next endpoint makes use of HTTP requests within Node.js. Before jumping right into the endpoint, it might make sense to create a helper method for making these requests:

The above method will make a POST request against a particular URL, passing in a JavaScript object as the body. If successful, the response will be returned, otherwise an error.

The makePostRequest method can be seen in action in the following:

In the above code, when a POST request is made against the /create endpoint, we first check to make sure certain properties exist in the body, otherwise we throw an error. If they exist we make use of the makePostRequest method, passing in the URL from the Sync Gateway RESTful API documentation.

At this point, if successful, the data will be saved from Sync Gateway to Couchbase Server and passed around to all connected devices.

The Full Application Source Code

In case you’d like to see the entire application put together, the source code can be found below:

We’re going to explore running this application in the next step.

Running the Application

There are a lot of moving pieces in this particular example. We have a Node.js application, Couchbase Server, and Couchbase Sync Gateway. Down the line you’ll probably have a mobile application as well.

The first thing we want to do is launch Sync Gateway and have it connect to our already running Couchbase Server cluster. Execute the following from your command line:

With Sync Gateway running you can run the Node.js application by executing:

The application should now be accessible on http://localhost:3000 at the particular endpoint paths.


You just saw one possible way of bringing your Couchbase Mobile and Couchbase Server applications together. While we didn’t actually create a mobile application in this guide, we used all the components that would make it possible as a final step. We created a Node.js application that used both the Couchbase Server Node.js SDK and Couchbase Sync Gateway.


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. Hi sir,

    We would like to use your approach but there is one consideration that we came accross. It is offline cases for mobile devices. Since it couldn’t make a call, then how could we overcome this problem? Should we write changes to couchbase lite then whenever internet is available, make api call to our server?

    Secondly, you mentioned that there are other possible approaches to use couchbase mobile & couchbase server. Could you briefly give information about that?


    1. You won’t have to worry about the edge cases with Couchbase mobile because by default Couchbase Lite will communicate with Sync Gateway whenever an internet connection is available.

      With Node and Couchbase Lite communicating with Sync Gateway, all will be good.

      When Couchbase 5.0 releases, you won’t have to communicate in this fashion as it will all be baked into the SDKs.

      1. So, in our case if internet is up, then it makes a call to app server which gets that request and communicate with sync gateway. On the other hand, if internet is gone, mobile app inserts data to its own local couchbase lite. Whenever an internet connection is available, the syncing operations is handled and we keep the data.


Leave a reply