This post was originally published atbam blog

Live sync in React Native with CouchDb

Intro

In this tutorial I will show you how to create a live game with data updating on multiple devices.

Let's start with something fun and basic! A game in which two people will be able to play together online. Let's make a liveRock - Paper - Scissors game. I've already programmed ithere so we can focus straight away on the cool stuff 😄.

This is a perfect opportunity to see how to build live data syncs in a mobile app with CouchDb. You'll of course be able to exploit these two technologies in many more use cases but this is a good way to start.

Thanks to CouchDb we don't need to build any backend! By the end we'll have a React Native app connected to a local CouchDb database. This basic game will help us concentrate on the essentials parts: the live sync & update on our React component. Feel free to explore the components to understand how it's displayed. Let's start!

1. Overview

Rock-Paper-Scissors

What exactly will our online game be able to do?

The famous and popular Rock-Paper-Scissors will be played by two people who will join the game thanks to its id. Other users will also be able to participate and join as spectators. After each round, the app will update the game and at the end display the final score.

Here a quick demo of what a player will see.

First steps are to clone therepo and simply run the commandyarn.

What is CouchDb

Before getting deeper into the app, let's dive into the technology behind it.

CouchDb

CouchDb is a NoSQL database accessible via a RESTFUL API. The singularity of CouchDb is that data is immutable. Each update of a document (NoSQL data) is a new document linked to its previous versions by a common_id. So, like in git, a historic tree can be made listing all the modifications of a document. Each update modifies the property_rev like_rev: 12-ad32d26. This is the version of the document (_rev is forrevision 🤫).

CouchDb masters in database replications. As it's possible to know what has been modified by an_id and a_rev prop, it's easy for a database to distinguish a delta and replicate from another one. At this stage the most important will be the replication of a distant database to a local one.

CouchDb Documentation

To work on our game, we'll need to install CouchDb locally.

Installation

To install CouchDb locally, go to theirwebsite.

Configuration

Create an admin and configure CouchDb as a single node.

Create theRPS database

Then, go to the "Databases" tab and create de database calledrps.

Install CouchDb in React Native

Easy! You only have to runyarn add pouchdb-react-native and you're set!

PouchDb

If CouchDb can store data in a server, PouchDb helps us manipulate data in locale database. PouchDb is close to CouchDb as they share the same API.

PouchDb Documentation

Let's dive into the code!

Sync

We want to share a documentPlay in real-time. How do we do that? We are going to replicate the local database and the database from the server. PouchDb has a really good method for it calledsync. If there is one reason to use PouchDb it's for thesync method! Take a look at this quote from PouchDb documentation:

CouchDB was designed with sync in mind, and this is exactly what it excels at. Many of the rough edges of the API serve this larger purpose. For instance, managing your document revisions pays off in the future, when you eventually need to start dealing with conflicts.

We use it this way:localDB.sync(remoteDB). This method is a shortcut for:

localDB.replicate.to(remoteDB);localDB.replicate.from(remoteDB);

sync has many options and in our case we'll need the following settings:

• a live sync so we add the propertysync totrue,
• a synchronization that persists and retry when there are connection problems. So we define theretry prop astrue.
• We don't want to synchronize the whole database, only the current game. Fortunately, CouchDb and PouchDb can manage that for us with afiltered replication. There are many ways to do a filtered replication but the most efficient one is to give tosync the array of ids we want to listen to.

For more details, I recommend this excellentPouchDb documentation

If we have a look at the whole code, this is what we should see:

// Repository/index.tspublicliveGame(id:string):void{this.cancelLive();constids=[`${id}_${Player.Player1}`,`${id}_${Player.Player2}`];this.sync=this.local.sync<{}>(this.remote,{live:true,retry:true,doc_ids:ids,}).on('change',result=>{console.log('change',result);bus.emit(SYNC_UP,{id,result,});});}

This is pretty simple, isn't it?
We added an eventSYNC_UP to make ourReact component reactive. We'll listen to it later.

Merge

During a game each player will update his own document so we won't have to deal with conflicts. But our component can only handle one documentPlay to display plays and scores. At this stage we only have one work left to do: to fetch the two documents in the database and merge them into one.

In the filePlayService., we'll call the methodmergePlays where we use a spread operator to merge the two documents. But there is a little more work to do when we want to gather playturns (in which each player updates their moves). For eachturn, we retrieve the move of the player 1 in the player 1's document and the move of the player 2 in the player 2's document. Like this:

// PlayService.tsprivatemergePlays(play1:IPlay|null,play2:IPlay|null):IPlay|null{// If one of these two documents is null just return the other one.if(!play1||!play2){returnplay1||play2;}constplay={...play1,...play2,};constturnCount=Math.max(play1.turns.length,play2.turns.length);if(!turnCount){play.turns=[];}else{play.turns=Array.from({length:turnCount}).map((_item,index)=>{constturn1=play1.turns[index];constturn2=play2.turns[index];constplayer1=turn1?turn1.player1:null;constplayer2=turn2?turn2.player2:null;constturn:ITurn={player1,player2,winner:null,};turn.winner=this.getWinner(turn);returnturn;});}returnplay;}

The React Native component

Now that all the settings are in place to sync, it's finally time to display our game on screen. The code below is the pagePlay after the player submits the game id in the home page. We can initialize the liveGame; telling PouchDb to only syncs documents we need.

When fetching the play if there is no player 2, we join the play 🙂.

We can listen to changes by adding a listener to theSYNC_UP event from our PouchDb repository.

// src/views/Play.tsxconstid=navigation.getParam('id')asstring;const[play,setPlay]=useState<IPlay|null>(null);constgetPlay=async()=>{constplayFromDb=awaitPlayService.get(id);setPlay(playFromDb);// ...// If there is no player 2 when fetching the game, we'll be able to join in.if(playFromDb&&!playFromDb.player2){awaitPlayService.joinPlay(id,store.uuid);}};useEffect(()=>{bus.on(SYNC_UP,getPlay);repository.liveGame(id);getPlay();return()=>{bus.removeListener(SYNC_UP,getPlay);};},[]);

A picture is worth a thousand words

For a quick sum up, find below the 3 main steps:

1. Player 1 creates the play
   • Player 1 saves a local document

{"_id":"12345-player1","player1":"uuid-player1","player2":"","turns":[],"_rev":"1-abc"}

• The app right after syncs with the server and saves the document
• Player 1 waits for a Player 2 to come by listening to any updates from the server of documents with ids "12345-player1" and "12345-player2"

1. Player 2 joins the play
   • Player 2 joins the play by fetching and updating the player 1's with his uuid in 'player2' attribute.
   • Player 2 creates a local document

{"_id":"12345-player2","player1":"uuid-player1","player2":"uuid-player2","turns":[],"_rev":"1-bcd"}

• Player 2's app syncs with the database and saves the two documents

1. The play is ready
   • Player 1 gets the updates and is now ready to play the first round
   • Player 1 and player 2 save their document locally and then share them with the server. That way every player receives updates from their opponent.
   • The app merges the two documents into one, so we can calculate who wins the round 1 and update the score.

Conclusion

DONE! We've completed our first live sync between two databases in React Native, awesome!

There is so much more we can explore now. Here a few examples:

• create an offline-first app to provide a seamless experience either the app is online or offline.
• create an app that shares data in Bluetooth without the need of an Internet connection (like shareable books in a region where the Internet is expensive)
• create an app where people can collaborate in live.
• and so on...