README.md

React Native Replicache

Plug-in React Native compatibility bindings for Replicache.

CleanShot.2023-02-18.at.19.59.27.mov

Replicache version compatibility

• 1.0.0 : replicache <= 14.2.2
• 1.3.0 : replicache >= 15

Why is this needed?

Replicache enables us to build applications that are performant, offline-capable and collaborative. By default, it uses IndexedDB for client-side persistance. Unfortunately, this technology is not available in React Native and is only supported in web-browsers.

Thankfully, Replicache allows us to provide our own transactional data-store via kvStore. The goal of this project is to provide some implementations of such a store, along with some guidance in getting up and running with Replicache in React Native.

What are the strategies?

React Native has relatively good support for SQLite - which provides the strict serializable transactions that we require.

In particular, we provide the choice between three SQLite bindings:

1. @react-native-replicache/react-native-expo-sqlite
   • Backed by expo-sqlite
   • Supported in Expo Go.
2. @react-native-replicache/react-native-op-sqlite
   • Backed by react-native-op-sqlite
   • Better performance.

Any additional considerations?

Some configuration is required to receive poke events from the server. In our example, seen here, we use a polyfill for Server Sent Events. These aren't built into React Native, but are really handy for a demo.

You most likely want to use web-sockets for this. This is relatively trivial with Pusher/Ably etc and similar to the web-app so we won't discuss that further here.

How can I install this?

1. Install the following in your React Native project:
   • yarn add expo-crypto
   • Decide which SQLite binding is for you and install one of the following:
     • yarn add @op-engineering/op-sqlite @react-native-replicache/react-native-op-sqlite
     • yarn add expo-sqlite @react-native-replicache/expo-sqlite
2. Ensure that you've polyfilled crypto.getRandomValues on the global namespace.
   • See here for an example.
3. Pass in your chosen SQLite binding's React Native Replicache binding into Replicache's kvStore option.
   • This will be one of the following, depending on the binding you chose:
     • createReplicacheOPSQLiteKVStore
     • createReplicacheExpoSQLiteKVStore
   • See here for an example.

How can I experiment with this locally?

Prerequisites

• Environment capable of developing iOS/Android applications (iOS is likely preferred).
  • See How to install React Native on Mac
    • or: Setting up the development environment
  • Note: Installing Xcode from the Mac App Store tends to be unusually slow and buggy.
    • Try download it from the Apple website instead.

Instructions

1. Clone the repository: git clone https://github.com/braden1996/react-native-replicache.git
2. Install yarn dependencies from repo root: yarn install
3. Perform an initial build: yarn build
4. Install the example iOS app onto a simulator/emulator or connected physical device, e.g: yarn workspace @react-native-replicache/example-mobile-react-native ios
5. Once the above has installed onto your device, you can cancel the now running Metro bundler and simply start dev for all workspaces: yarn run dev.

Tips

• Flipper has been configured for use with the example app.
  • Download it to browser network requests etc