supastash

library0.2.10jsnpmunverified

Supastash (v0.2.10, active development) is an offline-first sync engine that synchronizes Supabase data with SQLite for React Native, Expo, and experimental Tauri desktop apps. It provides two-way sync, real-time updates, conflict resolution, batched updates, and row-level filtering. It supports multiple SQLite adapters including expo-sqlite, react-native-nitro-sqlite, and react-native-sqlite-storage. Version 0.2.1+ introduced breaking changes requiring explicit network adapter import, and v0.2.1+ added experimental Tauri desktop support. Ships TypeScript types.

database mobile

npm install supastash

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SUPASTASH

supastash

databasejavascriptv0.2.10

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

configureSupastash

✓ import { configureSupastash } from 'supastash'

✗ const { configureSupastash } = require('supastash')

ESM-only; require() will fail as package is ESM-only since v0.2.0.

defineLocalSchema

✓ import { defineLocalSchema } from 'supastash'

✗ import { defineLocalSchema } from 'supastash/schema'

Exported from 'supastash', not a subpath. Use named import directly.

useSupatash

✓ import { useSupatash } from 'supastash'

✗ import useSupatash from 'supastash'

React hook; must be a named import. Default import is undefined.

supastashEventBus

✓ import { supastashEventBus } from 'supastash'

✗ import { eventBus } from 'supastash'

Event bus object for custom events; named 'supastashEventBus', not 'eventBus'.

Configures Supastash with Supabase client, Expo SQLite, NetInfo network adapter, a local schema, and initializes the app after database readiness.

// lib/supastash.ts import { configureSupastash, defineLocalSchema } from 'supastash'; import { createClient } from '@supabase/supabase-js'; import { openDatabaseAsync } from 'expo-sqlite'; import * as NetInfo from '@react-native-community/netinfo'; const supabase = createClient(process.env.SUPABASE_URL ?? '', process.env.SUPABASE_ANON_KEY ?? ''); configureSupastash({ supabaseClient: supabase, dbName: 'supastash_db', sqliteClient: { openDatabaseAsync }, sqliteClientType: 'expo', networkAdapter: NetInfo, onSchemaInit: () => { defineLocalSchema('users', { id: 'TEXT PRIMARY KEY', name: 'TEXT', email: 'TEXT', created_at: 'TEXT NOT NULL', updated_at: 'TEXT NOT NULL', }); }, debugMode: true, syncEngine: { push: true, pull: false, }, }); // App.tsx import '@/lib/supastash'; import { useSupatash } from 'supastash'; import { Stack } from 'expo-router'; export default function App() { const { dbReady } = useSupatash(); if (!dbReady) return null; return <Stack />; }

Debug

Known issues

breakingYou must now pass `networkAdapter: NetInfo` explicitly in `configureSupastash`. Import it as `import * as NetInfo from "@react-native-community/netinfo";`

fix

Add the import and pass `networkAdapter: NetInfo` to `configureSupastash`.

affects: >=0.2.1

breakingThe package is ESM-only since v0.2.0. Using `require()` will fail with a runtime error.

fix

Use `import` syntax instead of `require()`.

affects: >=0.2.0

breakingDesktop support via Tauri is experimental (v0.2.1+). Adapter and API may change with breaking updates.

fix

Expect rough edges and breaking changes when using Tauri. Monitor releases and update code accordingly.

affects: >=0.2.1

deprecatedThe `syncEngine.pull` option defaults to false; if you rely on pull sync (e.g., for filters or RLS), you must enable it explicitly.

fix

Set `syncEngine.pull: true` in the configuration if you need pull sync.

affects: >=0.0.1

gotchaThe hook is named `useSupatash` (typo: missing 's'), not `useSupastash`.

fix

Use `useSupatash` (note the missing 's') in your components.

affects: >=0.0.1

gotchaOnly one SQLite adapter should be used at a time. Installing multiple may cause conflicts.

fix

Choose one adapter (e.g., `expo-sqlite`) and set `sqliteClientType` accordingly.

affects: >=0.0.1

gotchaThe `onSchemaInit` callback must be synchronous and defined before calling `configureSupastash`.

fix

Define schemas inside `onSchemaInit` without async operations; call `configureSupastash` after.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: supastash is not a function

Default import used when package only exports named exports.

fix

Use named imports like `import { configureSupastash } from 'supastash'`.

Cannot find module 'supastash' or its corresponding type declarations.

TypeScript project lacks proper ESM config or import resolution.

fix

Ensure `"moduleResolution": "node16"` or `"bundler"` in tsconfig, and use full import paths.

Error: `networkAdapter` is required for React Native. Please pass `networkAdapter: NetInfo` to `configureSupastash`.

Missing `networkAdapter` configuration in React Native environment (v0.2.1+).

fix

Import `import * as NetInfo from "@react-native-community/netinfo"` and pass `networkAdapter: NetInfo`.

TypeError: Cannot read properties of undefined (reading 'openDatabaseAsync')

Missing or incorrect `sqliteClient` object with wrong adapter property.

fix

Pass `sqliteClient: { openDatabaseAsync }` where `openDatabaseAsync` is from your chosen adapter (e.g., `expo-sqlite`).

Error: duplicate table name: users

Schema defined multiple times or `onSchemaInit` called twice.

fix

Ensure `defineLocalSchema` is called only once per table, inside a single `onSchemaInit` callback.

Upgrade

Version history

0.2.10latest on npm

Audit

Dependencies

@supabase/supabase-jsrequiredRequired as peer dependency for Supabase client operations

@react-native-community/netinfooptionalRequired for network status detection in React Native environments

reactoptionalRequired as peer dependency for React Native/Expo projects

react-nativeoptionalRequired as peer dependency for React Native/Expo projects

Agent activity

44 hits · last 30 days

node