anchordb-react

AnchorDB for React Native and Expo — MongoDB and Mongoose for mobile apps, with SQLite storage ready after one install.

Overview · Report a bug or get support

npm install anchordb-react

That single command brings the database, the SQLite driver and the crypto polyfill. Nothing else to install, and no adapter to wire:

// db.ts
import { createAnchorDB } from "anchordb-react";
import { Schema } from "anchordb";

export const db = createAnchorDB({ name: "contacts" });

export const Contact = db.model("Contact", new Schema({
  name:  { type: String, required: true },
  email: { type: String, required: true, unique: true, lowercase: true },
}, { timestamps: true }));

// any component
import { useFind, useCount } from "anchordb-react";
import { db, Contact } from "./db";

function Contacts() {
  const { data, loading, refresh } = useFind(db, Contact, {}, { sort: "-createdAt" });
  const { data: total } = useCount(db, Contact, {});

  if (loading) return <Spinner />;
  return <FlatList data={data} onRefresh={refresh} ListFooterComponent={<Text>{total}</Text>} />;
}

Hooks

| Hook | Purpose | | --- | --- | | useFind | live list query; re-runs on every matching change | | useFindOne | live single document | | useCount | live count, without fetching documents | | useAggregate | live aggregation pipeline | | useSyncStatus | status, pending count and a sync() trigger | | useAnchorEvent | subscribe to any AnchorDB event | | useAnchorReady | resolves once the database is open |

All are built on the same observeQuery primitive as the Angular bindings and the inspector's push events, so a change visible to one is visible to all three.

In an Expo app

npm install anchordb-react installs everything. To keep the two native modules on the exact versions your Expo SDK expects, also pin them in your app:

npx expo install expo-sqlite react-native-get-random-values

anchordb-react declares both with wide ranges precisely so that npm reuses these pins instead of installing its own copies.

This matters most in Expo Go, which ships prebuilt native modules for one SDK. Without the pin, npm may resolve a different major for the JavaScript side — react-native-get-random-values 2.0.0, say, against the 1.11 native module Expo SDK 56 ships — and the two will not match. A development build or an APK compiles whatever version is installed, so it is consistent either way.

npx expo install --fix will not do this for you: it only realigns packages your app lists itself, and these arrive through anchordb-react.

createAnchorDB

Defaults to Expo SQLite, stored as <name>.db. An explicit adapter still wins, so tests are not forced onto SQLite:

import { MemoryAdapter } from "anchordb";
const db = createAnchorDB({ name: "contacts", adapter: new MemoryAdapter("contacts") });

If the native module has not been linked — nearly always an Expo SDK mismatch rather than a missing install, since the dependency is declared — it throws naming the fix:

expo-sqlite did not load. In an Expo app run `npx expo install expo-sqlite react-native-get-random-values` so the
native modules match your SDK, then rebuild the dev client.

Inspect with Anchor Lens

Anchor Lens reads a running app's database through anchor-relay on your computer. Run npx anchor-relay --host 0.0.0.0 --room my-app, then give the database the agent URL it prints:

export const db = createAnchorDB({
  name: "contacts",
  inspector: { enabled: true, relayUrl: "ws://192.168.1.24:9440/relay?room=my-app&role=agent" },
});

Lens scans the relay's QR code and asks for a pairing code, which the app has to show:

import { useAnchorEvent } from "anchordb-react";

function PairingCode() {
  const [code, setCode] = useState(db.inspector?.pairing?.code ?? null);
  useAnchorEvent(db, "inspector:pairing", (pairing) => setCode((pairing as { code: string }).code));
  return code ? <Text>Anchor Lens pairing code: {code}</Text> : null;
}

Two things an Android release build needs: cleartext traffic allowed for the relay's ws:// (expo-build-properties → android.usesCleartextTraffic), and allowInProduction: true — without it the inspector refuses to start, so one left on cannot ship by accident.

This package is React Native only

Importing it pulls in react-native-get-random-values, which imports React Native internals, so a React web build will fail. That is the deliberate cost of the one-install setup above.

Web is not lost, it just does not go through this package: use anchordb directly with anchordb/storage/indexeddb, which is fully supported and covered by the storage conformance suite.

Two things worth knowing

Filters are keyed on serialised content, not object identity. Writing useFind(db, User, { age: { $gte: 18 } }) creates a fresh object every render; depending on identity would resubscribe on each render and loop forever.

useSyncStatus works in local-only mode, reporting "disabled" with zero pending — so a status indicator can be rendered unconditionally instead of every screen branching on whether sync exists.

Status

1.2.0. Requires React 19 (expo-sqlite pulls React Native, which pins it). React 18 projects stay on the release/0.x-react18 line at 0.2.1.

The Expo SQLite adapter has never run on a device — this machine has no simulator. Its query and index logic is inherited from a base that is covered by the conformance suite; the unverified part is driver plumbing. Test a create-read-restart cycle early.

MIT.

The AnchorDB family

Six packages. Only anchordb is required — the rest exist so that an offline-only app never has to download Express, and an Express server never has to download React.

| Package | What it is | Runs where | | --- | --- | --- | | anchordb | The database — schema, models, queries, aggregation, optional sync | phone · browser · Node | | anchordb-react (this package) | React Native hooks + SQLite storage | the device | | anchordb-angular | Angular / Ionic module, DI, RxJS + SQLite storage | the device | | anchordb-sync-server | Server half of sync — Express, NestJS, Next.js | your backend | | anchordb-relay | Dev relay for the Anchor Lens inspector | your laptop | | anchordb-lens-link | Open a QA build's database in Anchor Lens on the same phone, from a file | the device, in QA builds |

Full reasoning and API reference: github.com/knnadeera/anchordb.

Bugs, support and feedback

Report a bug, ask for help or suggest a feature on the AnchorDB project page — choose anchordb-react as the package, and the reply comes by email.

Include the version (npm ls anchordb), where it runs, the smallest snippet that reproduces it, and the full error.