docs: add expo package workflow and README documentation

Author: callum-gander

.github/workflows/main.yml

@@ -419,6 +419,19 @@ jobs:
           echo "   Platform packages: 7"
           echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
+      - name: build and publish expo package
+        if: steps.tag.outputs.version != ''
+        run: |
+          cd packages/expo
+
+          echo "Generating @sqliteai/sqlite-sync-expo package..."
+          node generate-expo-package.js "${{ steps.tag.outputs.version }}" "../../artifacts" "./expo-package"
+
+          echo "Publishing @sqliteai/sqlite-sync-expo to npm..."
+          cd expo-package
+          npm publish --provenance --access public
+          echo "✓ Published @sqliteai/sqlite-sync-expo@${{ steps.tag.outputs.version }}"
+
       - uses: softprops/[email protected]
         if: steps.tag.outputs.version != ''
         with:
@@ -427,6 +440,7 @@ jobs:
 
             [**Node**](https://www.npmjs.com/package/@sqliteai/sqlite-sync): `npm install @sqliteai/sqlite-sync`
             [**WASM**](https://www.npmjs.com/package/@sqliteai/sqlite-wasm): `npm install @sqliteai/sqlite-wasm`
+            [**Expo/React Native**](https://www.npmjs.com/package/@sqliteai/sqlite-sync-expo): `npm install @sqliteai/sqlite-sync-expo`
             [**Android**](https://central.sonatype.com/artifact/ai.sqlite/sync): `ai.sqlite:sync:${{ steps.tag.outputs.version }}`
             [**Swift**](https://github.com/sqliteai/sqlite-sync#swift-package): [Installation Guide](https://github.com/sqliteai/sqlite-sync#swift-package)
 

README.md

@@ -176,6 +176,47 @@ SQLiteDatabase db = SQLiteDatabase.openDatabase(config, null, null);
 
 **Note:** Additional settings and configuration are required for a complete setup. For full implementation details, see the [complete Android example](https://github.com/sqliteai/sqlite-extensions-guide/blob/main/examples/android/README.md).
 
+### React Native / Expo
+
+Install the Expo package:
+
+```bash
+npm install @sqliteai/sqlite-sync-expo
+```
+
+Add to your `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": ["@sqliteai/sqlite-sync-expo"]
+  }
+}
+```
+
+Run prebuild:
+
+```bash
+npx expo prebuild --clean
+```
+
+Load the extension:
+
+```typescript
+import { open } from '@op-engineering/op-sqlite';
+import { Platform } from 'react-native';
+
+const db = open({ name: 'mydb.db' });
+
+// Load SQLite Sync extension
+if (Platform.OS === 'ios') {
+  const path = db.getDylibPath('ai.sqlite.cloudsync', 'CloudSync');
+  db.loadExtension(path);
+} else {
+  db.loadExtension('cloudsync');
+}
+```
+
 ## Getting Started
 
 Here's a quick example to get started with SQLite Sync:

packages/expo/README.md

@@ -0,0 +1,136 @@
+# @sqliteai/sqlite-sync-expo Generator
+
+This directory contains the generator script for the `@sqliteai/sqlite-sync-expo` npm package.
+
+## How It Works
+
+The `generate-expo-package.js` script creates a complete npm package from CI build artifacts:
+
+1. Generates `package.json`, `app.plugin.js`, `src/index.js`, `src/index.d.ts`, `README.md`
+2. Copies iOS `CloudSync.xcframework` from artifacts
+3. Copies Android `cloudsync.so` files for each architecture
+
+## Usage (CI)
+
+This script is called automatically during the release workflow:
+
+```bash
+node generate-expo-package.js <version> <artifacts-dir> <output-dir>
+```
+
+Example:
+
+```bash
+node generate-expo-package.js 0.8.57 ../../artifacts ./expo-package
+cd expo-package && npm publish --provenance --access public
+```
+
+## Generated Package Structure
+
+```
+expo-package/
+├── package.json
+├── src/
+│   ├── index.js
+│   └── index.d.ts
+├── app.plugin.js
+├── ios/
+│   └── CloudSync.xcframework/
+├── android/
+│   └── jniLibs/
+│       ├── arm64-v8a/cloudsync.so
+│       ├── armeabi-v7a/cloudsync.so
+│       └── x86_64/cloudsync.so
+├── README.md
+└── LICENSE.md
+```
+
+## Testing Locally
+
+To test the generator locally, you need to set up mock artifacts that simulate what CI produces.
+
+### Step 1: Get binaries
+
+**Option A: Download from latest release**
+
+```bash
+VERSION="0.8.57"  # or latest version
+
+mkdir -p artifacts/cloudsync-apple-xcframework
+mkdir -p artifacts/cloudsync-android-arm64-v8a
+mkdir -p artifacts/cloudsync-android-armeabi-v7a
+mkdir -p artifacts/cloudsync-android-x86_64
+
+# Download xcframework
+curl -L "https://github.com/sqliteai/sqlite-sync/releases/download/${VERSION}/cloudsync-apple-xcframework-${VERSION}.zip" -o xcframework.zip
+unzip xcframework.zip -d artifacts/cloudsync-apple-xcframework/
+rm xcframework.zip
+
+# Download Android binaries
+for arch in arm64-v8a armeabi-v7a x86_64; do
+  curl -L "https://github.com/sqliteai/sqlite-sync/releases/download/${VERSION}/cloudsync-android-${arch}-${VERSION}.zip" -o android-${arch}.zip
+  unzip android-${arch}.zip -d artifacts/cloudsync-android-${arch}/
+  rm android-${arch}.zip
+done
+```
+
+**Option B: Build from source**
+
+```bash
+# Build xcframework (macOS only)
+make xcframework
+
+# Build Android (requires Android NDK)
+export ANDROID_NDK=/path/to/ndk
+make extension PLATFORM=android ARCH=arm64-v8a
+make extension PLATFORM=android ARCH=armeabi-v7a
+make extension PLATFORM=android ARCH=x86_64
+
+# Move to artifacts structure
+mkdir -p artifacts/cloudsync-apple-xcframework
+mkdir -p artifacts/cloudsync-android-arm64-v8a
+mkdir -p artifacts/cloudsync-android-armeabi-v7a
+mkdir -p artifacts/cloudsync-android-x86_64
+
+cp -r dist/CloudSync.xcframework artifacts/cloudsync-apple-xcframework/
+# Copy .so files similarly...
+```
+
+### Step 2: Run the generator
+
+```bash
+cd packages/expo
+node generate-expo-package.js 0.8.57 ../../artifacts ./expo-package
+```
+
+### Step 3: Test in a React Native app
+
+```bash
+# In your RN/Expo app
+npm install /path/to/sqlite-sync/packages/expo/expo-package
+
+# Or use file: reference in package.json
+# "@sqliteai/sqlite-sync-expo": "file:/path/to/sqlite-sync/packages/expo/expo-package"
+```
+
+Update `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": ["@sqliteai/sqlite-sync-expo"]
+  }
+}
+```
+
+Run prebuild and verify:
+
+```bash
+npx expo prebuild --clean
+
+# Check iOS
+ls ios/<YourApp>/CloudSync.xcframework
+
+# Check Android
+ls android/app/src/main/jniLibs/arm64-v8a/cloudsync.so
+```