Recently, we published a series of articles on the topic of using Couchbase Lite in a React Native application. In this tutorial, you’ll take it one step further and use the recommended Couchbase Lite Module for React Native (available as an npm module). You will add the necessary Couchbase Lite code to complete the Login and List Screens for a simple Todo Application. By the end of the tutorial, you will have covered the following core concepts:

  • Creating, deleting a database and documents within it.
  • Using Couchbase Views to display List documents by date.
  • Replications with Basic Authentication.
  • Creating Sync Gateway Users and using a Sync Function.


  • Node.js 4.0 +
  • Xcode 7 or higher
  • An iOS simulator or device running iOS 9 or higher

Getting Started

To save some time, I’ve already put together a starter project which contains all the UI code. Go ahead and download it to your preferred directory and unzip the content. Then, from the project directory install the dependencies:

If it’s not already the case, also make sure to have the React Native CLI globally installed:

Next, start the React Native daemon:

Open the Xcode project at ios/UntitledTodoApp.xcodeproj and run it in the simulator or device from Xcode. You should see both screens:

Notice that the Log Out button doesn’t take you back to the LogIn Screen and nothing is displayed in the ListView. Don’t worry, you will fix that in the next section :) Remember to enable LiveReload using the Cmd+D shortcut (and Chrome Debugging might be handy at times).

Local Persistence with Couchbase Lite

The starter project already contains the React Native Couchbase Lite Module (you can follow the repo instructions to use it in another React Native project). In this section, you will learn how to instantiate a new manager, database and persist documents locally.

Create a new file in src/database.js and paste the following:

The code does the following:

  1. Import the manager and ReactCBLite objects from the module using the de-structuring assignment syntax in ES6.
  2. Start the Couchbase Lite Listener which serves an HTTP REST API that you will use later.
  3. Instantiate a manager instance passing the URL of the embedded server and the desired database name.
  4. Export the object so it can be used throughout the application life-cycle.

Now you can turn your focus to components/Login.js. Add a require statement to use the database object from the previous step:

This component has two input fields and a button, for now you're not going to check if the user exists because Sync Gateway isn't up and running yet. However, you'll need to bootstrap the local database before opening the List View. Replace the body of _onLoginButtonPressed with the following:

Here, you’re creating the database and then registering a design document with a view to query documents by their created_at property.

Next, open Lists.js and require the database object once more:

In the render method, notice the 2 variables leftButtonConfig and rightButtonConfig that are used in the NavigationBar component in the return statement. They correspond to the Log Out and New buttons. The click handlers don’t do anything though so you will change that right away. In the handler field of the object literal leftButtonConfig add:

You’re simply deleting the database (and all the documents and potential replications in progress with it) and then returning to the LogIn View.

Next, in the handler for the rightButtonConfig add:

In this case, you’re displaying an alert dialog to enter the new list title and then persisting it to the database (with the owner field set to the logged in user and created_at field as the current timestamp).

Next, below the getInitialState method add the following to query the persisted documents:

Here’s the breakdown of what is happening:

  1. _redrawListView is a private method that queries the lists view and updates the datasource to display the new rows (if any) on the screen.
  2. In componentWillMount you’re using the setInterval to check for new documents periodically and update the UI.
  3. Stop the interval method when the component unmounts (i.e. when returning to the LogIn View).

Create a new list and open http://localhost:5984/myapp/_design/todo/_view/lists in your browser. You must provide admin for the username and pass for the password. The JSON response should look like this:

To display them on the screen you will use the ListView component. It has two mandatory attributes:

  • dataSource to provide the data: you can pass this.state.dataSource.
  • renderRow takes a function that returns a View object given a list item.

You’re missing the method to draw the row, below render, add a renderRow method with the following:

The desired data is held in the value field and you’re displaying the title and owner fields in Text elements. Back in the return statement of the render method, add the ListView below the NavigationBar component like so:

Persist documents and notice the screen updating itself:

Sync Gateway Configuration

In this section, you will use Sync Gateway to introduce bi-directional synchronization and server-side user authentication so multiple users can log in. First, download Sync Gateway from here and in the root directory of the project, create a new file named sync-gateway-config.json with the following JSON:

A few important things to note here are:

  • The GUEST mode is disabled (in fact, it’s the case by default) so any unauthenticated requests will be treated as unauthorized and return a 401 status code. For that matter, 4 different users have been created (with names moderator, laura, james, adam). The user named moderator has access to all channels.
  • The Sync Function routes a document to a channel named after the owner field and grants the owner access to that channel.

So, in theory, the moderator should see all List documents where as the other users will see their own List documents only.

Start Sync Gateway from the command line:

In Login.js, update the _onLoginButtonPressed as follow:

Here’s what is happening:

  1. Construct the URL of the remote database (in this case it’s a Sync Gateway database) and set the name/password JSON fields in the request body.
  2. Use the POST /_session endpoint to check the name/password with Sync Gateway.
  3. If the credentials are valid, create the database and once that’s done kick off continuous push/pull replications and register a design document with a view to query document by their created_at property.
  4. If the credentials are invalid, display an alert window.

Run the application and login as different users. If possible, run the app on two devices to observe the continuous replication and different read permissions for the moderator:


In this tutorial, you learnt how to use the React Native Couchbase Lite module to build a simple Todo application where multiple users can log in.

The final project can be found on GitHub.

Feel free to share your feedback, findings or ask any questions in the comments below or in the forums. Talk to you soon!


Posted by James Nocentini, Technical Writer, Mobile, Couchbase

James Nocentini is the Technical Writer in charge of the documentation for Couchbase Mobile. Previously, he worked as a Developer Advocate and before that as a front-end developer for HouseTrip. He also enjoys writing Android tutorials for in his spare time.

One Comment

  1. Hi james,
    it seems that this tutorial is obsolete by now, as

    import {manager, ReactCBLite} from ‘react-native-couchbase-lite’

    returns undefined for ReactCBLite.
    Could you please update or point to any actual tutorial where CBL operations from JS perspective are described in such a clean and comprehensive way as you did in this post?

Leave a reply