How to Build an iOS Chat App with React Native: Overview and Setup (Part One)

Welcome to our 4-part series on building an iOS chat app with React Native and ChatEngine. If you’re here, you’re looking to add chat to a new or existing mobile app by means of React Native.

The full GitHub repo for this series is available here.

ChatEngine Overview

When building chat-enabled applications, developers typically have a variety of concerns to think about. The server side of chat operations is dramatically non-trivial. Getting a sample chat service backend running on a single server might be no big deal. But as the application grows, networking, security, availability and extensibility become paramount concerns. On the client side, there is a lot to build for the initial user experience, from authentication logic to textbox styling. If the chat functionality needs to work cross-platform (yup, it usually does), that increases the amount of effort even more.

This is where ChatEngine comes in. ChatEngine is the premier framework for creating chat-enabled applications built on PubNub. It provides a powerful event-driven model for building chat functionality, allowing developers to focus on application-specific needs. The toolkit is written in JavaScript, allowing it to integrate quickly with browser-based HTML5 applications, NodeJS services, and mobile applications via React Native components.

Prerequisites for ChatEngine with React Native for iOS

There are a few prerequisites for building with ChatEngine and React Native on iOS:

Configure a ChatEngine Application

To get started, you’ll have to sign up for PubNub and configure ChatEngine. You can do so in the embedded form below:

Once that’s all set, you should be able to verify the keys using the Admin Dashboard.

Keep track of those keys – you’ll need them in an upcoming step!

Node.js Setup

Setting up Node.js takes about a couple minutes using the platform-specific installer package.

Once you have Node.js installed, you should be able to verify the installation using node -v.

$ node -v

React Native Setup

React Native installation requires Node.js – ensure it’s installed and on your path before following the directions here.

Once React Native is installed, you should be able to verify the installation using react-native -v.

$ react-native -v
react-native-cli: 2.0.1
react-native: 0.54.2

There, that was easy!

Install Xcode

Installing Xcode should be quick and easy using the OS X App Store (or for the latest release).

Once you have Xcode installed, start it up and check the version using Menu → Xcode → About Xcode. Our version is 9.4.1.

Configuring a Simulator or iOS Device

If you’ve developed on iOS before, this step should be familiar. We either create a Simulator (iOS Device Simulator) to run our app in simulation, or connect a real iOS hardware device for debugging.

The target iOS version we use in our application is 11.4, but this application is likely to work on any platform revision supported by your version of React Native. If you run into any platform-specific issues, please let us know!

Running the Sample Application

Now that you’ve got the development environment all set, getting started with ChatEngine with React Native on iOS is a quick 4-step process.

  • Clone the repository git clone
  • Update the settings in lib/ex-config-pnsettings.js with your Publish and Subscribe key credentials from the first step above
  • Run npm install to install all JS dependencies
  • Run react-native run-ios to run the application (ensure that the iOS device or simulator is on & ready for debugging)

Let’s take a look at each step.

Cloning the Repository

To run the code, we must first obtain the code. Cloning the sample application from GitHub takes just a few seconds:

$ git clone
Cloning into 'chatengine-react-native-sample'...
remote: Counting objects: 118, done.
remote: Compressing objects: 100% (80/80), done.
remote: Total 118 (delta 28), reused 117 (delta 27), pack-reused 0
Receiving objects: 100% (118/118), 355.17 KiB | 0 bytes/s, done.
Resolving deltas: 100% (28/28), done.
Checking connectivity... done.

Updating the PubNub ChatEngine Credentials

This is an easy but critical step – you need to update the authentication credentials so that the sample application can communicate using the PubNub network.

Update the YOUR_PUB_KEYandYOUR_SUB_KEY in the file lib/ex-config-pnsettings.js to the values from your ChatEngine application in the PubNub Admin Portal – it should be as easy as copy and paste of the two values.

Running NPM Install

If we’re going to run the sample application, we’ll need to download all of the dependencies that make it work. This includes React Native support libraries, as well as ChatEngine itself. To do this, run npm install from the project directory.

If you run into any issues, make sure you’re using a recent Node.js and NPM version, and reach out to PubNub support if we can be of any assistance!

Running the Application

Alright! Now that that’s all out of the way, we can move on to running the application. Make sure that your simulator or iOS device is running and ready for debugging. From your project directory, run react-native run-ios. If all is well, you should see something like the following.

04 Running React Native

Understanding the Project Layout

There are two major directories to be aware of when developing with the ChatEngine React Native Sample Application on iOS. The first is (unsuprisingly) the ios folder in the root project directory. This includes all of the important iOS files like ChatEngineReactNativeSample.xcodeproj where application name, permissions, and other settings are kept.

The other important directory is the lib folder under the root project directory. It includes all of the JavaScript code that implements our application under React Native. You have already edited the lib/ex-config-pnsettings.js file in the previous configuration step.

The files in the lib directory follow this naming convention:

  • ce-core-chatengineprovider.js : the main interface for the ChatEngine provider library in our application
  • ce-model-*.js : these model classes deal with shuttling data from ChatEngine into the application
  • ce-view-*.js : these view classes deal with displaying chat components in the application
  • ce-theme-*.js : these files abstract the look & feel away from the application (work in progress)
  • ex-config-pnsettings.js : the ChatEngine credentials for the application
  • ex-screen-*.js : the screens and tabs that implement the application

The intention is that all of the files with the “ce-” prefix are generic, while the files with the “ex-” prefix are more specific to your application.

Also of note is the App.js file in the root directory. It defines the application navigation – from app loading to login, chat tab view and more.

Updating the Application Look & Feel

If you’d like to update a component’s look and feel, start first in the “-view-” file for that component. If there is a style class already defined, it can be edited in the “ce-theme-style.js” file easily. If you don’t find the rendering style in the “-view-” file, check for a nested “-view-” file, or examine the “-screen-” file for rendering code. As we refine the sample application, we intend to streamline the styles to make it easier to modify the look & feel. Stay tuned!

Next Steps: Messaging and Message History

Now that we’re done our setup, it’s time to start adding chat functionality. In Part Two, we’ll add realtime messaging and message history, as well as styling the app.

Try PubNub Today

Share this on facebookShare this on TwitterShare this on Linkedin