React Native

Electron · Tauri · Qt · Flutter · React Native · Capacitor and Ionic · .NET MAUI

React Native applications use a dedicated module binding the C SDK for iOS and Android. It exposes the Node package’s application API with the same names. The JavaScript thread calls it through JSI. Queries return the same rows and columns as on Node.

Requirements

React Native 0.87 or newer with the New Architecture.

Platform	Minimum version
iOS	15.1, the minimum for React Native 0.87
Android	13 (API level 33)

For Expo, use a development build. Expo Go loads no native module outside the Expo SDK.

Install CocoaPods before the iOS steps, and check it with pod --version. The Ruby that macOS includes (2.6) cannot install the current CocoaPods. Use Ruby 3.4 or newer.

What ships

The TypeScript column of the compatibility matrix, packaged for React Native. Each release runs the quickstart on the platforms in this table. Other platforms have no verification for this integration.

Platform	Targets	Package
iOS and iPadOS	apple-mobile-device-arm64, apple-mobile-simulator-arm64, apple-mobile-simulator-x86_64	@potluckdb/potluckdb-react-native
Android	android-arm64-v8a, android-x86_64	@potluckdb/potluckdb-react-native

Install

Create the Notes application.

npx @react-native-community/cli init Notes
cd Notes
npm install @potluckdb/potluckdb-react-native

For iOS, run pod install from the ios directory.

Autolinking registers the module on both platforms.

On Android, set minSdkVersion = 33 in android/build.gradle. Set reactNativeArchitectures=arm64-v8a,x86_64 in android/gradle.properties.

Replace android/app/src/main/java/com/notes/MainActivity.kt with MainActivity.kt from the Quickstart section. It sets POTLUCKDB_CONFIG_DIR under the application’s files directory before React Native starts. The licensing page explains this requirement.

Quickstart

Replace App.tsx with the file below. The application opens the database in the document directory the module reports, inserts a note and renders the table. Run npx react-native run-ios or npx react-native run-android from the Notes directory. run-ios starts the app in the iOS Simulator.

The application logs quickstart: ok once the database is open. On Android, the line is in the device log with the tag ReactNativeJS. On iOS, it is in the simulator’s log.

App.tsx

// potluckdb in a React Native application: one database in the application's document
// directory, which the module reports so that no second native module is needed for a path.

import React, { useEffect, useState } from "react";
import { FlatList, SafeAreaView, Text } from "react-native";
import { documentDirectory, open, Remote } from "@potluckdb/potluckdb-react-native";

type Note = { id: number; body: string };

export default function App(): React.JSX.Element {
  const [notes, setNotes] = useState<Note[]>([]);

  useEffect(() => {
    let db: Awaited<ReturnType<typeof open>> | undefined;
    let remote: Remote | undefined;
    (async () => {
      remote = Remote.fromDirectory(`${documentDirectory}/remote`); // a bucket replaces this in production; see the Node installation page
      db = await open(`${documentDirectory}/notes.potluckdb`, remote);
      await db.execute("CREATE TABLE IF NOT EXISTS note(id INTEGER PRIMARY KEY, body TEXT NOT NULL)");
      await db.execute("INSERT INTO note(body) VALUES(?)", ["buy milk"]);
      const { rows } = await db.query("SELECT id, body FROM note ORDER BY id");
      setNotes(rows as Note[]);
      console.log("quickstart: ok");
    })();
    return () => {
      db?.close();
      remote?.close();
    };
  }, []);

  return (
    <SafeAreaView>
      <FlatList
        data={notes}
        keyExtractor={(note) => String(note.id)}
        renderItem={({ item }) => <Text>{item.id}: {item.body}</Text>}
      />
    </SafeAreaView>
  );
}

MainActivity.kt

package com.notes

import android.os.Bundle
import android.system.ErrnoException
import android.system.Os
import android.util.Log
import com.facebook.react.ReactActivity
import com.facebook.react.ReactActivityDelegate
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
import com.facebook.react.defaults.DefaultReactActivityDelegate

class MainActivity : ReactActivity() {

  override fun getMainComponentName(): String = "Notes"

  override fun onCreate(savedInstanceState: Bundle?) {
    // React Native starts in super.onCreate and can open the database at once.
    try {
      Os.setenv("POTLUCKDB_CONFIG_DIR", "$filesDir/configuration", false)
    } catch (error: ErrnoException) {
      Log.e("Notes", "could not place the configuration directory", error)
    }
    super.onCreate(savedInstanceState)
  }

  override fun createReactActivityDelegate(): ReactActivityDelegate =
      DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
}

Verified by the release

Each release verifies persisted notes without a development server in React Native 0.87.1 on the iOS simulator and Android emulator. The iOS device, Intel simulator, and arm64-v8a Android libraries compile but do not run in these checks.