Skip to Content
CommunityFAQ

FAQ

Frequently asked questions about Gluonic.

General

What is Gluonic?

Gluonic is an offline-first sync engine for React and React Native applications. It enables apps to work seamlessly with or without network connectivity while providing real-time updates when connected.

Is Gluonic free?

Yes! Gluonic is open source (Apache 2.0 license) and free to use, even commercially.

Who maintains Gluonic?

Gluonic is maintained by Everywai Technologies and the open-source community.

Can I use Gluonic in production?

Gluonic is in active development toward v1.0. The core sync engine is functional and being used in real applications, but the API may change as we refine features. We recommend waiting for v1.0 for production use unless you’re comfortable with potential breaking changes.

Technical

Which databases does Gluonic support?

Gluonic works with any database through adapters:

  • PostgreSQL (via Prisma, TypeORM, raw SQL)
  • MySQL (via Prisma, TypeORM)
  • SQLite (via Prisma, TypeORM)
  • MongoDB (via Prisma, Mongoose, native driver)
  • SQL Server (via Prisma, TypeORM)
  • CockroachDB (via Prisma)

Which ORMs are supported on the server?

  • ✅ Prisma (official adapter, recommended)
  • ✅ TypeORM (community adapters)
  • ✅ Raw SQL (custom adapters)
  • ✅ Drizzle (via Prisma adapter or custom adapter)
  • ⚠️ Kysely (coming soon)

Which storage adapters are supported on the client?

Currently Gluonic supports the Drizzle adapter for client-side local storage. This works on both:

  • React Native (via OP-SQLite)
  • Web (via better-sqlite3)

Additional storage adapters (RxDB, etc.) are planned for future releases.

Does it work with React Native?

Yes! Gluonic is designed for React Native and works perfectly on iOS and Android.

Does it work on Web?

Yes! Gluonic has a universal client that works in both React Native and Web from the same codebase.

Does it work with Expo?

Yes! Gluonic works with Expo managed workflow and bare workflow.

Comparison

How is this different from InstantDB?

  • ✅ Gluonic: Self-hosted, database-agnostic, React Native support
  • ✅ InstantDB: Cloud-hosted, simple setup, web-only

See full comparison.

How is this different from Convex?

  • ✅ Gluonic: Self-hosted, use existing backend
  • ✅ Convex: Cloud-hosted, replaces backend

See full comparison.

How is this different from Replicache?

  • ✅ Gluonic: Simpler setup (35 lines vs 100+), batteries-included
  • ✅ Replicache: Maximum flexibility, web-only

See full comparison.

Can I migrate from WatermelonDB?

Yes! See Migration Guide.

Features

Does Gluonic handle conflicts?

Yes! Gluonic uses optimistic concurrency control with automatic conflict detection. Default is last-write-wins (server), but you can customize with conflict resolution strategies.

Does it support real-time sync?

Yes! Gluonic uses WebSocket for real-time push updates.

Does it work offline?

Yes! That’s the primary feature. Gluonic is offline-first - your app works perfectly without network.

How does it handle large datasets?

Gluonic supports:

  • Streaming bootstrap (memory-safe)
  • Delta sync (only changed data)
  • Snapshot caching (10x faster)
  • Spill-to-disk (for >100MB datasets)

Setup

How long does it take to set up?

  • Quick Start: 5 minutes (basic working app)
  • Production setup: 2-4 hours (with Redis, snapshots, auth)

Do I need Redis?

No! Redis is optional:

  • Without Redis: Single-server real-time sync works
  • With Redis: Multi-pod deployments and better scaling

Do I need to change my database schema?

Yes, minimally. You need to add:

  • Ownership field (e.g., userId) to track who owns data
  • Version field (e.g., version) for conflict detection
  • SyncAction table for delta sync

See Server Setup.

Troubleshooting

Why isn’t my UI updating?

Most common cause: Forgot to wrap component with observer():

// ❌ Wrong
const Component = () => { const post = useModel(...) }
 
// ✅ Correct
const Component = observer(() => { const post = useModel(...) })

Why is bootstrap slow?

Solutions:

  • Enable snapshot caching (10x faster)
  • Use streaming bootstrap for large datasets
  • Optimize database queries

See Performance Guide.

WebSocket disconnects immediately

Cause: Authentication issue with WebSocket.

Solution: Pass token in query param:

wss://api.example.com/sync/v1/ws?token=YOUR_JWT_TOKEN

See Authentication Guide.

TypeScript decorators not working

Cause: Build configuration.

Solution for Vite:

pnpm add -D vite-plugin-typescript-transpile

See Client Setup.

Performance

How fast is Gluonic?

Benchmarks with 10,000 records:

  • Bootstrap: 280ms (35ms with snapshot cache)
  • Delta (100 changes): 45ms
  • Mutation (optimistic): <1ms
  • Memory: 15MB

See Comparison for details.

Can it scale to millions of records?

Yes! With proper configuration:

  • Streaming bootstrap
  • Snapshot caching
  • Batch loading
  • Multi-pod deployment

See Scaling Guide.

Community

How can I get help?

  • GitHub Discussions
  • Discord community
  • Stack Overflow (tag: gluonic)

Can I contribute?

Yes! See Contributing Guide.

Is there a roadmap?

Yes! See Roadmap.

Still have questions?

  • Search the documentation
  • Ask in GitHub Discussions
  • Join Discord
  • Open an issue
Last updated on
Contributing