Skip to content
Kizuna Sync

Docs Client library reference Expo

v0.2.6-alpha.3

Expo: Installing

The Expo ports ship in the kizunasync package as the kizunasync/expo subpath, together with the engine, the Supabase composition, the React bindings, the browser engine that runs on Expo web, and the React Native module that links the native engine. The package wraps native modules it declares as optional peers, so add those with npx expo install and the Expo SDK modules match the app's Expo SDK. These pages assume an Expo Router app with its routes under src/app/, so expo, expo-router, React, and React Native come from the app's own template.

Install from npm#

npm install kizunasync

kizunasync/react holds KizunaSyncProvider, which src/app/_layout.tsx wraps the navigator in, and the hooks the screens read. React: Installing covers the package.

Install the Expo-managed packages#

npx expo install expo-sqlite expo-file-system @react-native-community/netinfo @supabase/supabase-js react-native-url-polyfill expo-build-properties
PackageWhy the app needs it
expo-sqliteA required peer that backs Open the SQLite driver. src/supabase-client.ts also imports expo-sqlite/localStorage/install, the localStorage that keeps the Supabase session across launches.
expo-file-systemAn optional peer that backs the File store, which only an app with attachments needs. The op-sqlite driver example reads the app's document directory from it.
@react-native-community/netinfoA required peer that backs the network signal the driver carries, the Connectivity port.
@supabase/supabase-jsSupabase's JavaScript client, which src/supabase-client.ts creates and kizunasync/supabase takes as a peer. Native download from kizunasync/expo/transfer runs on it too.
react-native-url-polyfillA URL that follows the WHATWG URL Standard, in place of React Native's partial one. src/supabase-client.ts imports react-native-url-polyfill/auto first, as Supabase's Expo quickstart does.
expo-build-propertiesThe config plugin whose ios.enableSceneSupport property adopts the UIKit scene life cycle on SDK 57, as iOS scene life cycle shows.

expo and React Native 0.86 or later are required peers too, which any Expo app already satisfies.

The React Native module inside kizunasync autolinks and links the native engine on iOS and Android, as Native engine describes. @op-engineering/op-sqlite is an optional peer for the op-sqlite driver, and nothing loads it until that path is imported.

kizunasync/expo also declares expo-asset as a peer, the package Open the SQLite driver reads the engine binary's asset URL through on Expo web. It arrives already, as a dependency of expo itself, so npx expo install needs nothing further for it. Metro still needs wasm in resolver.assetExts to bundle that binary:

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config')

const config = getDefaultConfig(__dirname)

config.resolver.assetExts.push('wasm')

module.exports = config

TypeScript resolves openExpoDriver from kizunasync/expo.

Native engine#

The React Native module inside kizunasync links a prebuilt engine library on iOS and Android, so the app project needs no Rust toolchain. Both platforms fetch the library at the exact version of kizunasync from the registries the Swift and Kotlin clients use.

On iOS, pod install adds the KizunaSyncEngine product of the Swift package https://github.com/kizunasync/kizunasync-swift to the Pods project through React Native's spm_dependency helper, and Xcode fetches that package when it builds the app. The library requires iOS 16 or later. Expo SDK 57 sets its own floor at iOS 16.4, above that minimum, so an Expo app needs no change for it.

On Android, Gradle resolves com.kizunasync:kizunasync-engine from Maven Central. That artifact carries the library for arm64-v8a, armeabi-v7a, and x86_64, and the module builds for the architectures in that list that the app also targets. A 32-bit x86 emulator cannot load the engine, so run an emulator image for x86_64 or arm64-v8a.

Expo Go cannot run the engine, because it loads no custom native code. A development build (npx expo run:ios / npx expo run:android, or EAS Build) is required on iOS and Android, and the engine joins the app during that build; a JavaScript reload or a plain install does not add it. Rust engine covers when the client selects it.

iOS scene life cycle#

iOS 27 terminates an app that does not adopt the UIKit scene life cycle, and Expo SDK 57 adopts it only when the expo-build-properties plugin sets ios.enableSceneSupport. Add the entry to the plugins array in app.json, after the plugins the app already lists (app.config.js takes the same entry):

{
  "expo": {
    "plugins": [
      "expo-router",
      ["expo-build-properties", { "ios": { "enableSceneSupport": true } }]
    ]
  }
}

The property needs expo 57.0.23 or later and the standard SDK 57 Swift AppDelegate, and the plugin throws when either is missing. Expo SDK 58 and later include scene support in the project template, so the entry applies to SDK 57 only, and the plugin warns when it finds the entry on SDK 58.

The plugin edits the generated iOS project, so rebuild it after adding the entry. npx expo run:ios generates the project when the app has no ios/ folder, and npx expo prebuild --platform ios --clean regenerates an existing one, which discards manual edits in ios/.

← IntroductionInitializing →

Found a problem? Edit this page on GitHub