Syncly Engine

0.1.10 verified Fri May 01 auth: no javascript

Syncly Engine is a local-first database synchronization engine for Expo/React Native apps, implementing the transactional outbox pattern to reliably sync data with cloud backends (initially Firestore). Current version 0.1.10 is under active development and not production-ready. It uses SQLite as the single source of truth, ULID keys for sortable IDs, soft deletes via deletedAt, and a provider abstraction for swappable cloud adapters. Key differentiators: offline-first, atomic writes of business data and sync payloads, conflict resolution tracking.

Common errors

error Module not found: Can't resolve 'syncly-engine' ↓

cause Package not installed or incorrectly imported.

fix

Install with: npm install syncly-engine

error TypeError: Cannot read properties of undefined (reading 'repository') ↓

cause Client not initialized before accessing repository.

fix

Await client.initialize() before using client.repository.

error FirebaseError: Firebase: No Firebase App '[DEFAULT]' has been created ↓

cause Firebase not initialized before creating FirestoreSyncAdapter.

fix

Call initializeApp() before getFirestore().

Warnings

gotcha Pre-1.0.0 API instability: APIs may change without notice until stable release. ↓

fix Pin to exact version and expect breakage on updates.

gotcha Firestore only: currently only FirestoreSyncAdapter is implemented; other providers not available. ↓

fix Use Firestore or implement custom adapter.

gotcha Requires Expo: this library is designed for Expo managed/bare workflows; may not work in vanilla React Native without Expo modules. ↓

fix Use expo-dev-client or eject to bare workflow.

gotcha No CJS support: package is ESM-only; cannot be required() in Node.js environments. ↓

fix Use import syntax; for Jest, configure transformIgnorePatterns.

Install

npm install syncly-engine

yarn add syncly-engine

pnpm add syncly-engine

Imports

SynclyClient

wrong

const SynclyClient = require('syncly-engine')

correct

import { SynclyClient } from 'syncly-engine'

ESM-only; no CJS support

SynclyClient

wrong

const { default: SynclyClient } = require('syncly-engine')

correct

import SynclyClient from 'syncly-engine'

Default export available but named export preferred

FirestoreSyncAdapter

wrong

import { FirestoreProvider } from 'syncly-engine'

correct

import { FirestoreSyncAdapter } from 'syncly-engine'

Exact class name; no alias exists

type SyncConfig

wrong

import { SyncConfig } from 'syncly-engine'

correct

import type { SyncConfig } from 'syncly-engine'

SyncConfig is a TypeScript type, use type import for tree-shaking

Quickstart

Demonstrates initializing SynclyClient, attaching a Firestore adapter, starting periodic sync, inserting a record into the local repository (which automatically queues a sync payload), and stopping sync.

import { SynclyClient, FirestoreSyncAdapter } from 'syncly-engine';

// Initialize the sync client
const client = new SynclyClient();
await client.initialize();

// Configure a Firestore adapter (requires Firestore instance)
const firestore = getFirestore(); // from firebase/firestore
const adapter = new FirestoreSyncAdapter(firestore, {
  collectionPrefix: 'syncly_'
});

// Start syncing periodically (every 30 seconds)
client.startSync(adapter, { intervalMs: 30000 });

// Use repository to write data (local-first)
const entity = await client.repository.insert('tasks', {
  title: 'Buy groceries',
  completed: false
});

// Data is automatically queued for sync
// Stop syncing when done
client.stopSync();