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.
sync
✓ import { sync } from 'bettersync'
✗ const { sync } = require('bettersync')
ESM-only package; no CJS support.
defineConfig
✓ import { defineConfig } from 'bettersync/config'
✗ import { defineConfig } from 'bettersync'
Config helper is exported from 'bettersync/config' subpath.
SyncEngine
✓ import { SyncEngine } from 'bettersync'
✗ import SyncEngine from 'bettersync'
It's a named export, not default.
Initializes a PGlite local database with Drizzle and starts bidirectional sync with a remote Postgres instance.
import { sync, defineConfig } from 'bettersync';
import { drizzle } from 'drizzle-orm/pglite';
import { PGlite } from '@electric-sql/pglite';
const client = new PGlite();
const db = drizzle(client);
const config = defineConfig({
syncTables: ['users', 'posts'],
remoteUrl: process.env.POSTGRES_URL ?? '',
authToken: process.env.AUTH_TOKEN ?? '',
});
await sync(db, config);
console.log('Sync started');
Debug
Known issues
breakingESM-only: Package does not provide CommonJS exports. Using require() will throw MODULE_NOT_FOUND.fixUse import syntax or enable ESM in your project.
affects: >=0.0.1
deprecatedv0.0.10 deprecated the old 'startSync' function in favor of 'sync'.fixReplace startSync() with sync().
affects: >=0.0.10 <0.0.15
gotchaConfig must include both syncTables and remoteUrl. Missing either causes a runtime error without clear message.fixAlways provide both syncTables (array of table names) and remoteUrl (Postgres connection string).
affects: >=0.0.1
breakingHLC clock drift tolerance changed from 5s to 1s in v0.0.12.fixEnsure your system clocks are synchronized within 1 second.
affects: >=0.0.12
gotchaPeer dependency 'pg' is required even if using @electric-sql/pglite; it's used for the remote connection.fixInstall 'pg' as a dependency.
affects: >=0.0.1
securityAuth token is passed in plain text over the wire if using HTTP. Use HTTPS or configure a secure connection.fixEnsure your Postgres connection uses TLS (e.g., postgres://...?sslmode=require).
affects: >=0.0.1
Errors
Common errors & fixes
Cannot find module 'bettersync' or its corresponding type declarations.
TypeScript project without ESM module resolution.
fixSet 'moduleResolution' to 'node16' or 'bundler' in tsconfig.json.
Error: syncTables is required
The config object is missing the 'syncTables' array.
fixAdd syncTables: ['your_table_name'] to defineConfig().
TypeError: (0 , bettersync.sync) is not a function
Using CommonJS require() on an ESM-only package.
fixUse import { sync } from 'bettersync' instead of require(). Audit
Dependencies
@electric-sql/pgliteoptionalRequired for PGlite local database adapter
better-sqlite3optionalRequired for better-sqlite3 local database adapter
expo-sqliteoptionalRequired for Expo SQLite local database adapter
@prisma/clientoptionalRequired for Prisma ORM adapter
drizzle-ormoptionalRequired for Drizzle ORM adapter
kyselyoptionalRequired for Kysely ORM adapter
nextoptionalRequired for Next.js integration