@powersync/react-native

PowerSync SDK for React Native

PowerSync is a Postgres-SQLite sync layer, which helps developers to create local-first real-time reactive apps that work seamlessly both online and offline.

This package (packages/react-native) is the PowerSync SDK for React Native clients. It is an extension of packages/common.

See a summary of features here.

Installation

Install Package

npx expo install @powersync/react-native

Install Peer Dependency: SQLite

This SDK currently requires @journeyapps/react-native-quick-sqlite as a peer dependency.

Install it in your app with:

npx expo install @journeyapps/react-native-quick-sqlite

Install Polyfills

This package connects to a PowerSync instance via HTTP streams (enabled by default) or WebSockets.

• Both connection methods require the React Native Common Polyfills, as detailed below.
• The WebSocket method requires an additional polyfill for the Buffer interface.
• Other polyfills are required for watched queries using the Async Iterator response format.

React Native Common Polyfills

This package requires polyfills for HTTP streaming and other text encoding functions. These functions can be provided with react-native-polyfill-globals.

Install the collection of polyfills with:

npx expo install react-native-polyfill-globals

The react-native-polyfill-globals package uses peer dependencies for individual functions. Most modern package managers install peer dependencies by default, however currently the peer dependency version ranges are quite broad and might result in certain packages being incompatible. Currently an issue is open for a breaking change in one of the dependencies. The best practice is to currently add the packages as explicit dependencies with version ranges to your project with the command below.

npx expo install react-native-fetch-api@^3.0.0 react-native-url-polyfill@^2.0.0 text-encoding@^0.7.0 web-streams-polyfill@3.2.1 base-64@^1.0.0

Enable the polyfills in React Native app by adding the following in your top level entry point

// App.js
import 'react-native-polyfill-globals/auto';

HTTP Connections

HTTP connections require the HTTP streaming polyfills included in the common section. See additional setup required for Android.

WebSocket Connections: Buffer

Note: Beta Release - WebSockets are currently in a beta release. It should be safe to use in production if sufficient testing is done on the client side.

Our WebSocket implementation supports binary payloads which are encoded as BSON documents.

This requires support for the Buffer interface.

Apply the Buffer polyfill

npx expo install @craftzdog/react-native-buffer

import { Buffer } from '@craftzdog/react-native-buffer';

if (typeof global.Buffer == 'undefined') {
  // @ts-ignore If using TypeScript
  global.Buffer = Buffer;
}

This library uses RSocket for reactive WebSocket streams which requires process.nextTick to be available. Apply a polyfill if not available.

if (typeof process.nextTick == 'undefined') {
  process.nextTick = setImmediate;
}

Babel Plugins: Watched Queries

Watched queries can be used with either a callback response or Async Iterator response.

Watched queries using the Async Iterator response format require support for Async Iterators.

Expo apps currently require polyfill and Babel plugins in order to use this functionality.

npx expo install @azure/core-asynciterator-polyfill

Make sure to import the polyfill early in your application

// App.js
import '@azure/core-asynciterator-polyfill';

Install the async generator Babel plugin

pnpm add -D @babel/plugin-transform-async-generator-functions

Add the Babel plugin to your babel.config.js file

module.exports = function (api) {
 return {
   presets: [...],
   plugins: [
     // ... Other plugins
     '@babel/plugin-transform-async-generator-functions'
   ]
 };
};

Native Projects

This package uses native libraries. Create native Android and iOS projects (if not created already) by running:

npx expo run:android
# OR
npx expo run:ios

Getting Started

Our SDK reference contains everything you need to know to get started implementing PowerSync in your project.

Changelog

A changelog for this SDK is available here.

API Reference

The full API reference for this SDK can be found here.

Examples

For example projects built with PowerSync and React Native, see our Demo Apps / Example Projects gallery. Most of these projects can also be found in the demos/ directory.

Found a bug or need help?

• Join our Discord server where you can browse topics from our community, ask questions, share feedback, or just say hello :)
• Please open a GitHub issue when you come across a bug.
• Have feedback or an idea? Submit an idea via our public roadmap or schedule a chat with someone from our product team.