Refactor React Native package and remove dependency

Author: steida

.changeset/cool-hoops-give.md

@@ -0,0 +1,39 @@
+---
+"@evolu/react-native": patch
+"@evolu/common": patch
+---
+
+Refactor React Native package structure and remove react-native-quick-base64 dependency
+
+**Breaking Changes:**
+
+- Package exports reorganized: use `/expo-sqlite`, `/expo-op-sqlite`, or `/bare-op-sqlite` instead of `/expo-sqlite` and `/op-sqlite`
+- Updated quickstart documentation to reflect new import paths
+
+**@evolu/react-native:**
+
+- Reorganized package structure with exports in dedicated `/exports` directory
+- Move SQLite driver implementations into `/sqlite-drivers` directory
+- Created shared dependency initialization in `shared.ts`
+- Removed `react-native-quick-base64` dependency (no longer needed)
+- Added `createExpoDeps.ts` for Expo-specific configuration including SecureStore integration
+- Updated `package.json` exports to include three entry points:
+  - `/expo-sqlite` - for Expo projects using expo-sqlite
+  - `/expo-op-sqlite` - for Expo projects using @op-engineering/op-sqlite
+  - `/bare-op-sqlite` - for bare React Native projects using @op-engineering/op-sqlite
+- Reorganized imports following project guidelines (named imports, top-down organization)
+
+**@evolu/common:**
+
+- Added `Platform.ts` module with platform detection utilities
+- Refactored `LocalAuth.ts` constants to follow naming conventions:
+  - `AUTH_NAMESPACE` → `localAuth_Namespace`
+  - `AUTH_DEFAULT_OPTIONS` → `localAuthDefaultOptions`
+  - `AUTH_METAKEY_LAST_OWNER` → `localAuthMetakeyLastOwner` (private)
+  - `AUTH_METAKEY_OWNER_NAMES` → `localAuthMetakeyOwnerNames` (private)
+
+**Documentation:**
+
+- Updated quickstart guide to remove `react-native-quick-base64` from installation instructions
+- Simplified Expo setup warnings and instructions
+- Updated React Native import example to use `/bare-op-sqlite` path

apps/web/src/app/(docs)/docs/quickstart/page.mdx

@@ -34,12 +34,12 @@ npm install @evolu/common@preview @evolu/react@preview @evolu/react-web@preview
 
 ```bash {{ title: 'React Native' }}
 npm install @evolu/common@preview @evolu/react@preview @evolu/react-native@preview \
-  @op-engineering/op-sqlite react-native-quick-crypto react-native-quick-base64
+  @op-engineering/op-sqlite react-native-quick-crypto
 ```
 
 ```bash {{ title: 'Expo' }}
 npm install @evolu/common@preview @evolu/react@preview @evolu/react-native@preview \
-  expo-sqlite react-native-quick-crypto react-native-quick-base64
+  expo-sqlite react-native-quick-crypto
 ```
 
 ```bash {{ title: 'Svelte' }}
@@ -53,17 +53,14 @@ npm install @evolu/common@preview @evolu/web@preview
 </SinglePlatformCodeGroup>
 
 <ConditionalPlatformAlert platform={["Expo"]} type="warning">
-  **Expo Go is not supported.** You must use a [development
-  build](https://docs.expo.dev/develop/development-builds/introduction/) or
-  create a production build to use Evolu with Expo, as it requires native
-  dependencies.
+  **Expo Go is not supported.** as it requires native dependencies
+  (`react-native-quick-crypto`). Use `expo-sqlite` for standard performance or
+  `expo-op-sqlite` for better performance.
 </ConditionalPlatformAlert>
 
 <ConditionalPlatformAlert platform={["Expo", "React Native"]} type="info">
   Make sure to follow the [react-native-quick-crypto setup
   instructions](https://github.com/margelo/react-native-quick-crypto#installation)
-  and [react-native-quick-base64 setup
-  instructions](https://github.com/craftzdog/react-native-quick-base64#installation)
   for proper native dependency configuration.
 </ConditionalPlatformAlert>
 
@@ -162,7 +159,7 @@ const { insert, update } = useEvolu();
 ```ts {{ title: 'React Native', language: 'tsx' }}
 import { createEvolu, getOrThrow, SimpleName } from "@evolu/common";
 import { createUseEvolu, EvoluProvider } from "@evolu/react";
-import { evoluReactNativeDeps } from "@evolu/react-native/op-sqlite";
+import { evoluReactNativeDeps } from "@evolu/react-native/bare-op-sqlite";
 
 const evolu = createEvolu(evoluReactNativeDeps)(Schema, {
  name: SimpleName.orThrow("your-app-name"),

examples/react-expo/app/_layout.tsx

@@ -1,5 +1,5 @@
-// import "react-native-quick-base64";
 import { install } from "react-native-quick-crypto";
+
 install();
 
 import { Stack } from "expo-router";

examples/react-expo/package.json

@@ -34,7 +34,6 @@
     "expo-sqlite": "~16.0.8",
     "react": "catalog:react19",
     "react-native": "^0.81.4",
-    "react-native-quick-base64": "^2.2.1",
     "react-native-quick-crypto": "^0.7.17",
     "react-native-safe-area-context": "^5.6.0",
     "react-native-screens": "^4.15.3",

packages/common/src/Evolu/LocalAuth.ts

@@ -84,7 +84,7 @@ export const createLocalAuth = (
     id: OwnerId,
     options?: LocalAuthOptions,
   ): Promise<void> => {
-    await deps.secureStorage.setItem(AUTH_METAKEY_LAST_OWNER, id, {
+    await deps.secureStorage.setItem(localAuthMetakeyLastOwner, id, {
       ...buildAuthOptions(options),
       accessControl: "none",
     });
@@ -93,7 +93,7 @@ export const createLocalAuth = (
   const getLastOwnerId = async (
     options?: LocalAuthOptions,
   ): Promise<OwnerId | undefined> => {
-    const item = await deps.secureStorage.getItem(AUTH_METAKEY_LAST_OWNER, {
+    const item = await deps.secureStorage.getItem(localAuthMetakeyLastOwner, {
       ...buildAuthOptions(options),
       accessControl: "none",
     });
@@ -103,7 +103,7 @@ export const createLocalAuth = (
   const getOwnerNames = async (
     options?: LocalAuthOptions,
   ): Promise<Record<OwnerId, string>> => {
-    const item = await deps.secureStorage.getItem(AUTH_METAKEY_OWNER_NAMES, {
+    const item = await deps.secureStorage.getItem(localAuthMetakeyOwnerNames, {
       ...buildAuthOptions(options),
       accessControl: "none",
     });
@@ -122,7 +122,7 @@ export const createLocalAuth = (
     const names = await getOwnerNames(options);
     names[id] = username;
     await deps.secureStorage.setItem(
-      AUTH_METAKEY_OWNER_NAMES,
+      localAuthMetakeyOwnerNames,
       JSON.stringify(names),
       {
         ...buildAuthOptions(options),
@@ -137,7 +137,7 @@ export const createLocalAuth = (
   ): Promise<void> => {
     const { [id]: _, ...names } = await getOwnerNames(options);
     await deps.secureStorage.setItem(
-      AUTH_METAKEY_OWNER_NAMES,
+      localAuthMetakeyOwnerNames,
       JSON.stringify(names),
       {
         ...buildAuthOptions(options),
@@ -157,8 +157,8 @@ export const createLocalAuth = (
       .filter(Boolean)
       .filter(
         (i) =>
-          i.key !== AUTH_METAKEY_LAST_OWNER &&
-          i.key !== AUTH_METAKEY_OWNER_NAMES,
+          i.key !== localAuthMetakeyLastOwner &&
+          i.key !== localAuthMetakeyOwnerNames,
       )
       .map((i) => i.key as OwnerId);
   };
@@ -171,7 +171,7 @@ export const createLocalAuth = (
     username?: string,
   ): LocalAuthOptions => {
     const newOptions: LocalAuthOptions = {
-      ...AUTH_DEFAULT_OPTIONS,
+      ...localAuthDefaultOptions,
       ...(username && { webAuthnUsername: username }),
       ...options,
     };
@@ -311,13 +311,11 @@ export const createLocalAuth = (
   };
 };
 
-// TOHO: With `const`, we don't need UPPER_CASE
-export const AUTH_NAMESPACE = "evolu";
-export const AUTH_METAKEY_LAST_OWNER = "_last_owner";
-export const AUTH_METAKEY_OWNER_NAMES = "_owner_names";
-export const AUTH_DEFAULT_OPTIONS: LocalAuthOptions = {
-  service: AUTH_NAMESPACE,
-  keychainGroup: AUTH_NAMESPACE,
+export const localAuth_Namespace = "evolu";
+
+export const localAuthDefaultOptions: LocalAuthOptions = {
+  service: localAuth_Namespace,
+  keychainGroup: localAuth_Namespace,
   androidBiometricsStrongOnly: true,
   iosSynchronizable: true,
   webAuthnUsername: "Evolu User",
@@ -326,6 +324,9 @@ export const AUTH_DEFAULT_OPTIONS: LocalAuthOptions = {
   },
 };
 
+const localAuthMetakeyLastOwner = "_last_owner";
+const localAuthMetakeyOwnerNames = "_owner_names";
+
 export interface AuthResult {
   /** The app owner created during registration. */
   readonly owner: AppOwner | undefined;

packages/common/src/Platform.ts

@@ -0,0 +1,26 @@
+/**
+ * Platform detection utilities for Evolu.
+ *
+ * @module
+ */
+
+/** Detects if the code is running in React Native environment. */
+export const isReactNative =
+  typeof navigator !== "undefined" &&
+  "product" in navigator &&
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  (navigator as any).product === "ReactNative";
+
+/**
+ * Detects if Node.js Buffer is available and should be used.
+ *
+ * React Native apps often polyfill Node.js APIs like Buffer, but we want to use
+ * native methods when available for better performance.
+ *
+ * Returns false in React Native even if Buffer is polyfilled, as we prefer
+ * native methods in that environment.
+ *
+ * @see https://github.com/craftzdog/react-native-quick-base64#installation
+ */
+export const hasNodeBuffer =
+  !isReactNative && typeof globalThis.Buffer !== "undefined";

packages/common/src/Type.ts

@@ -182,6 +182,7 @@ import { pack } from "msgpackr";
 import type { Brand } from "./Brand.js";
 import { type RandomBytesDep } from "./Crypto.js";
 import { isPlainObject } from "./Object.js";
+import { hasNodeBuffer } from "./Platform.js";
 import { err, getOrNull, getOrThrow, ok, Result, trySync } from "./Result.js";
 import { safelyStringifyUnknownValue } from "./String.js";
 import type { Literal, Simplify, WidenLiteral } from "./Types.js";
@@ -1426,7 +1427,6 @@ export const formatBase64UrlError = createTypeErrorFormatter<Base64UrlError>(
   (error) => `The value ${error.value} is not a valid Base64Url string.`,
 );
 
-const hasNodeBuffer = typeof globalThis.Buffer !== "undefined";
 const base64UrlOptions = { alphabet: "base64url", omitPadding: true };
 
 /** Encodes a Uint8Array to a {@link Base64Url} string. */

packages/common/src/index.ts

@@ -16,6 +16,7 @@ export * from "./ManyToManyMap.js";
 export * from "./Number.js";
 export * from "./Object.js";
 export * from "./Order.js";
+export * from "./Platform.js";
 export * from "./Random.js";
 export * from "./Ref.js";
 export * from "./Result.js";

packages/common/typedoc.json

@@ -33,6 +33,7 @@
     "src/Number.ts",
     "src/Object.ts",
     "src/Order.ts",
+    "src/Platform.ts",
     "src/Random.ts",
     "src/Ref.ts",
     "src/Result.ts",

packages/react-native/package.json

@@ -25,15 +25,21 @@
       "react-native": "./dist/index.js"
     },
     "./expo-sqlite": {
-      "types": "./dist/expo-sqlite.d.ts",
-      "default": "./dist/expo-sqlite.js",
-      "react-native": "./dist/expo-sqlite.js",
+      "types": "./dist/exports/expo-sqlite.d.ts",
+      "default": "./dist/exports/expo-sqlite.js",
+      "react-native": "./dist/exports/expo-sqlite.js",
       "browser": "./dist/web.js"
     },
-    "./op-sqlite": {
-      "types": "./dist/op-sqlite.d.ts",
-      "default": "./dist/op-sqlite.js",
-      "react-native": "./dist/op-sqlite.js",
+    "./expo-op-sqlite": {
+      "types": "./dist/exports/expo-op-sqlite.d.ts",
+      "default": "./dist/exports/expo-op-sqlite.js",
+      "react-native": "./dist/exports/expo-op-sqlite.js",
+      "browser": "./dist/web.js"
+    },
+    "./bare-op-sqlite": {
+      "types": "./dist/exports/bare-op-sqlite.d.ts",
+      "default": "./dist/exports/bare-op-sqlite.js",
+      "react-native": "./dist/exports/bare-op-sqlite.js",
       "browser": "./dist/web.js"
     }
   },
@@ -43,10 +49,13 @@
         "./dist/index.d.ts"
       ],
       "expo-sqlite": [
-        "./dist/expo-sqlite.d.ts"
+        "./dist/exports/expo-sqlite.d.ts"
       ],
-      "op-sqlite": [
-        "./dist/op-sqlite.d.ts"
+      "expo-op-sqlite": [
+        "./dist/exports/expo-op-sqlite.d.ts"
+      ],
+      "bare-op-sqlite": [
+        "./dist/exports/bare-op-sqlite.d.ts"
       ]
     }
   },
@@ -61,9 +70,6 @@
     "clean": "shx rm -rf .turbo node_modules dist",
     "format": "prettier --write \"src/*.{ts,tsx,md}\""
   },
-  "dependencies": {
-    "blo": "^2.0.0"
-  },
   "devDependencies": {
     "@evolu/common": "workspace:*",
     "@evolu/react": "workspace:*",