PowerSync SDK for React Native

PowerSync is a sync engine for building local-first apps with instantly-responsive UI/UX and simplified state transfer. Syncs between SQLite on the client-side and Postgres, MongoDB, MySQL or SQL Server on the server-side.

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 @op-engineering/op-sqlite

Configuration options

Encryption with SQLCipher

To enable SQLCipher you need to add the following configuration option to your application's package.json. Note that for monorepos you may have to add this configuration to the monorepo root package.json instead, this depends on where your package manager tool hoists modules.

{
  // your normal package.json
  // ...
  "op-sqlite": {
    "sqlcipher": true
  }
}

Additionally you will need to add an encryption key to the OPSQLite factory constructor

const db = new PowerSyncDatabase({
  schema: new Schema(...),
  database: {
    dbFilename: 'sqlite.db',
    sqliteOptions: {
      encryptionKey: 'your-encryption-key'
    }
  }
});

Full-Text Search

To enable the fts5 extension, configure OP-SQLite in your (or for monorepos, the root) package.json:

{
  // your normal package.json
  // ...
  "op-sqlite": {
    "fts5": true
  }
}

Loading SQLite extensions

To load additional SQLite extensions include the extensions option in sqliteOptions which expects an array of objects with a path and an entryPoint:

sqliteOptions: {
  extensions: [{ path: libPath, entryPoint: 'sqlite3_powersync_init' }];
}

More info can be found in the OP-SQLite docs.

Example usage:

import { getDylibPath } from '@op-engineering/op-sqlite';

let libPath: string;
if (Platform.OS === 'ios') {
  libPath = getDylibPath('co.powersync.sqlitecore', 'powersync-sqlite-core');
} else {
  libPath = 'libpowersync';
}

const factory = new OPSqliteOpenFactory({
  dbFilename: 'sqlite.db',
  sqliteOptions: {
    extensions: [{ path: libPath, entryPoint: 'sqlite3_powersync_init' }]
  }
});

Install Polyfills

• Polyfills are required for watched queries using the Async Iterator response format.

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. PowerSyncDatabase.getCrudTransactions() also returns an Async Iterator and requires this workaround.

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'
   ]
 };
};

Expo EAS config (optional)

If you are using this library in an Expo project and encounter issues with multiple versions of SQLite3, the conflict might be due to expo-updates also depending on SQLite. To resolve this, you can configure Expo to use the third-party SQLite pod.

Update your ios/Podfile.properties.json to include the following configuration:

{
  "expo.updates.useThirdPartySQLitePod": "true"
}

Metro config (optional)

When using a bare React Native app without a framework like Expo, the @powersync/react-native package does not work well with inline requires.

If you see the following error message

Super expression must either be null or a function

then you will need to add this to your metro.config.js:

const config = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        inlineRequires: {
          blockList: {
            [require.resolve('@powersync/react-native')]: true
          }
        }
      }
    })
  }
};

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.