expo-surrealdb

Features

• Works in Expo apps and bare React Native apps (via expo-modules-core)
• Multi platform:
  • iOS (CarPlay), iPadOS, watchOS, visionOS: powered by the Swift SDK
  • Android: powered by the Kotlin SDK
  • Web: powered by the official JS SDK (surrealdb npm package)
• Embedded SurrealDB (iOS & Android only for now)
• Query Builder Pattern
• HTTP or WebSocket

Install

npm install expo-surrealdb expo-modules-core

For bare React Native projects, install Expo modules once:

npx install-expo-modules@latest

Expo example app

A minimal Expo demo app is included at examples/expo. It is configured for Expo SDK 55.

cd examples/expo
npm install
npm run start

The example imports this package using file:../.., so it always runs against your local module source.

iOS setup

This module expects the SurrealDB Swift package to be linked in your iOS app target.

1. Open your iOS workspace in Xcode.
2. Add a Swift Package dependency: https://github.com/ForetagInc/surrealdb.swift.
3. Link the SurrealDBRuntime product to your app target.
4. Run pod install and rebuild.

If this is missing, the module throws: SurrealDB Swift SDK is not linked....

Optional (Podfile automation): if you use cocoapods-spm, this podspec can map the package product automatically.

plugin 'cocoapods-spm'
spm_pkg 'SurrealDB', :url => 'https://github.com/ForetagInc/surrealdb.swift.git', :branch => 'main'

Android setup

This module depends on the Kotlin SDK artifact configured in android/build.gradle:

• Gradle property: expoSurrealdbKotlinDependency
• Env var override: EXPO_SURREALDB_KOTLIN_DEPENDENCY
• Default: com.github.itsezc:surrealdb.kotlin:main-SNAPSHOT

In your Android project:

1. Use Java 17+ for Gradle builds.
2. Add JitPack to Gradle repositories (usually in settings.gradle).
3. If your Kotlin SDK artifact coordinate differs, override expoSurrealdbKotlinDependency.

Example settings.gradle repository block:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url 'https://jitpack.io' }
  }
}

Usage

import { createSurrealClient } from 'expo-surrealdb';

const client = await createSurrealClient({
  kind: 'http',
  endpoint: 'http://127.0.0.1:8000',
  namespace: 'test',
  database: 'test',
});

const rows = await client.query('RETURN 1;');

await client.close();

HTTP example:

const client = await createSurrealClient({
  kind: 'http',
  endpoint: 'http://127.0.0.1:8000',
  namespace: 'test',
  database: 'test',
});

await client.signin({
  kind: 'root',
  username: 'root',
  password: 'root',
});

const rows = await client.query('SELECT * FROM person LIMIT 10;');

Builder pattern example (JS-SDK style, executed by native bridge):

const people = await client
  .select('person')
  .limit(10);

const created = await client
  .create('person:ada')
  .content({ name: 'Ada' });

const query = client.queryBuilder('RETURN 1; RETURN 2;');
const responses = await query.responses();

API

createSurrealClient(options)

Creates a native client and returns a SurrealClient instance.

Android note: only http and websocket kinds are supported. Calling memory or surrealkv on Android throws an error. Web note: only http and websocket kinds are supported. Calling memory or surrealkv on web throws an error.

SurrealClient

• query(sql, bindings?)
• query(boundQueryLike)
• queryBuilder(sql, bindings?)
• select(...)
• create(...)
• insert(...)
• update(...)
• upsert(...)
• delete(...)
• relate(...)
• run(...)
• use(namespace?, database?)
• signin(credentials)
• signup(credentials)
• authenticate(token)
• invalidate()
• close()

See src/ExpoSurrealdb.types.ts for full option and credential shapes.

Testing and CI

Run the same checks locally that CI runs:

bun run ci

This includes:

• lint (biome check on src and tests)
• typecheck (tsc --noEmit)
• unit tests (vitest) covering:
  • JS client wrapper behavior
  • web adapter behavior (surrealdb npm path)
  • React Native bridge compatibility (mocked expo-modules-core)
  • iOS/Android native bridge method contract parity