From a personal level, I’m a huge fan of Telerik NativeScript. It is a cross platform development framework for building native Android and iOS applications using a single codeset, that code set being JavaScript. I had to put emphasis on the native part because it is one of the only cross platform frameworks that does not use a web view for displaying content. This in turn creates an application that has incredible performance.

Up until now there hasn’t been a good solution for storing data in a NativeScript app. That is until now!

With the help of Telerik and the NativeScript team, I was able to come up with a Couchbase Lite plugin for NativeScript that allows you to leverage the power of NoSQL in your mobile application. When paired with Couchbase Sync Gateway, data can be synchronized between devices and platforms.

We’re going to see what it takes to get started with Couchbase Mobile in your NativeScript app.

The Requirements

There are a few requiements to make this possible.

  • NativeScript 1.7+
  • The Android SDK (if building Android apps)
  • Xcode and a Mac (if building iOS apps)
  • Couchbase Sync Gateway (for sync)

You don’t need to build for both Android and iOS, but it certainly is convenient.

Creating a New NativeScript Project

We’re going to build a simple name list application that synchronizes between devices. To do this, execute the following from a Command Prompt (Windows) or Terminal (Mac and Linux):

Remember, if you’re not using a Mac, you cannot add and build for the iOS platform. Going forward, the Command Prompt or Terminal should use CouchbaseProject as the working directory.

Including the Couchbase Lite SDK

With the project created it is time to include the Couchbase Lite plugin for use. From the Terminal or Command Prompt, execute the following:

This will include the plugin for whatever platforms that have been added to the project.

Developing the Application

With the project created we need to create a few files and directories. Go ahead and add the following:

The above files is where we are going to spend most of our time, but before we jump in, open the project’s app/app.js file and switch out the appropriate line with the following:

This tells the NativeScript application that the list view will be our first view.

Creating the Application Logic

The application logic files are the JavaScript files. One file will drive the logic behind our list view and the other will drive the logic behind our name creation form. Starting with the list logic, open the project’s app/views/list/list.js file and include the following code:

There is a lot happening in the above logic file so we’re going to break it down. First thing we’re doing is including a few JavaScript libraries:

The plugin that was installed must first be imported. All data read from the database will be stored in an observable array. This is so we can subscribe to data changes and bind the data to the UI. Finally the frame is imported so we can navigate to other pages.

To open a particular Couchbase NoSQL database we would execute the following command:

The above command will open the database if it exists or it will create and open the database if it does not exist.

If this is your first time working with NoSQL, the above snippet might look very foreign. It is the creation of a MapReduce view. Instead of writing a SQL statement as seen in SQLite, we’re creating MapReduce views that we can query for data. The above view will return a key-value pair of all documents where the key is the document id and the value is the document itself. This view is going to be called people.

With the view in place, it needs to be queried. This is done through the refresh function. Before getting to the refresh function, notice the final line of the pageLoaded function. This shows that we’ll be binding the personList data to our UI. Let’s look at that refresh function:

Every time we query the list will be reset and re-populated. The view will only be queried when the page loads. We’ll see why further down in this tutorial.

With the app/views/list/list.js file out of the way we can focus on the logic file behind the creation form. Open the project’s app/views/create/create.js file and include the following code:

This file is a lot more lightweight in comparison to the last. Essentially we’re capturing the form elements that we’ve yet to create. When we call the save function it will take the values in the form fields and create the document in Couchbase. No SQL schemas or nonsense to slow you down when it comes to development. One of the major benefits to using NoSQL.

The logic is now complete, for now, and we can move onto the UI.

Designing a Cross Platform UI

The UI code is short and sweet. Remember, our list will only contain information about the users we add. Open the project’s app/views/list/list.xml file and include the following code:

When the page loads, it calls the pageLoaded function. The action bar has a single button for navigating to the create page. Finally the list view will iterate over the personList observable array that was created in the logic file.

When it comes to the create form, there is similarly a small amount of XML code to be included. Open the project’s app/views/create/create.xml file and include the following code:

Again the pageLoaded is called on page load. The action bar has a single button for saving the Couchbase data, and the form contains data that is read via the logic file that we previously created.

We should have a fully functional app that uses Couchbase for storing data. However, as of right now this application is offline only. Data is not being synchronized.

Including Couchbase Sync Gateway for Data Replication

To synchronize the application data between Couchbase Server and other devices, the Couchbase Sync Gateway must be included along with a special configuration file. To keep things simple here, we are not going to go in depth when it comes to a Sync Gateway configuration file. Something like this will suffice:

What matters to us for this tutorial is the code that communicates with the Sync Gateway via our application. We’re now going to revisit the app/views/list/list.js file and include some code in the pageLoaded function. Open the file and include the following:

In the above we are telling our application that we are going to push and pull from the same Sync Gateway that is being run locally. Replications are going to happen continuously in both directions. Then we finally start the process.

With data being uploaded and downloaded we need a way to update the UI when necessary. Previously I mentioned we were only querying one time when the page loads. This is because we’re actually going to use a listener to listen for changes. It is more efficient than continously querying for potentially massive amounts of data. Inside your app/views/list/list.js file, within the pageLoaded function, include the following code:

The goal here is to pick up a change, see if that document already exists in the list, if it doesn’t, add it, otherwise, change it. The function for finding where a document exists in the list can be seen below:

Maybe not the most efficient way to update a list view, but it works for this example.

At this point if you run the Sync Gateway and your application, it should synchronize the data.


You just saw how to create a simple cross platform, native, Android and iOS application that syncs using NativeScript and the Couchbase Lite plugin. Further information about the plugin can be seen on the project’s GitHub page. More on Couchbase Mobile can be seen in the Couchbase Developer Portal.


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. One question: where exactly is the database stored? When I install the NativeScript app and run it, can I access the database file via the file manager (in case I want to make backups, etc.)? Assuming I decide not to use a sync gateway, that is.

    1. Android and iOS store all databases regardless of type in a protected part of the device. The only way to access it would be to have your device rooted or jailbroken.

      1. Ahh, I see. That’s nice to know—I was wondering where the file has mysteriously got to! Thanks for the info :)

Leave a reply