couchbase-mobile

name	couchbase-mobile
description	Design and build mobile, edge, and offline-first applications with Couchbase Lite, Sync Gateway, and Capella App Services. Use whenever the user asks about Couchbase Lite, Sync Gateway, App Services, offline-first, mobile sync, data replication to mobile, Couchbase Lite database, replicator, push/pull replication, sync function, channel access, user authentication in mobile, conflict resolution in mobile, iOS Couchbase, Android Couchbase, React Native Couchbase, Xamarin Couchbase, .NET MAUI Couchbase, peer-to-peer sync, edge database, Couchbase Lite vector search, or 'how do I sync data to mobile apps.' Distinct from couchbase-xdcr (server-to-server replication) and couchbase-app-integration (server-side SDKs). Use proactively when the user has a mobile, IoT, field worker, or offline-capable application requirement.
license	MIT

Couchbase Mobile

A skill for designing and building mobile and edge applications with Couchbase Lite + Sync Gateway / Capella App Services — offline-first sync, channel-based access control, conflict resolution, and mobile-specific patterns.

Distinct from:

• couchbase-xdcr — server-to-server replication between Couchbase clusters
• couchbase-app-integration — server-side SDK integration (Python, Java, Node.js, etc.)
• couchbase-capella — Capella cluster provisioning (App Services runs on top of a Capella cluster)

If the conversation is "I'm building a mobile app / offline-first app / IoT device that needs to sync with Couchbase," this is the right skill.

When this skill applies

• "How do I sync data to an iOS / Android app?"
• "How do I build an offline-first app with Couchbase?"
• "What's Couchbase Lite?"
• "How does Sync Gateway work?"
• "How do I set up Capella App Services?"
• "How do I control which users see which documents?"
• "How do I handle conflicts in mobile sync?"
• "How do I do peer-to-peer sync between devices?"
• "Can I use vector search in Couchbase Lite?"

Pick the right reference

Question	Read
"Architecture — Lite vs Sync Gateway vs App Services, when to use which"	references/architecture.md
"Sync function — channels, access control, routing documents to users"	references/sync-function.md
"Couchbase Lite — replicator config, conflict resolution, queries"	references/couchbase-lite.md

Three core principles

Principle 1 — Channel-based access is the security model. Sync Gateway / App Services control data access through channels. A document is routed to one or more channels by the sync function; a user has access to a set of channels. Users only receive documents in channels they have access to. There is no other row-level security mechanism — if you need per-document access control, you need per-document or per-group channels.

Principle 2 — Offline-first means conflicts are inevitable. When two devices edit the same document while offline, both changes are valid locally. When they sync, a conflict occurs. Couchbase Lite resolves conflicts automatically (last-write-wins by default) or via a custom conflict resolver. Design your documents assuming conflicts will happen — use additive updates (event logs, append-only fields) over destructive in-place updates where possible.

Principle 3 — The sync function runs on every document mutation. The sync function (or the equivalent access/channel routing in App Services) is a JavaScript function that executes on the Sync Gateway / App Services side for every document write. It determines which channels the document belongs to and who can read/write it. Keep it fast and free of side effects. Slow sync functions bottleneck the entire write path.

Platform support

Couchbase Lite runs on:

• iOS (Swift, Objective-C)
• Android (Kotlin, Java)
• React Native
• .NET (Xamarin, .NET MAUI, Windows, macOS, Linux)
• Flutter (community)
• JavaScript / Ionic / Capacitor

All platforms share the same replication protocol and sync semantics. The API differs by language but the concepts are identical.

Current releases (mid-2026)

The June 30, 2026 edge/mobile wave (shipped alongside the AI Data Plane — see couchbase-ai-applications) advanced the whole mobile stack. Gate version-specific guidance accordingly, and verify exact API surface against the docs for the version you target:

• Couchbase Lite 4.1 — peer-to-peer sync over Bluetooth with automatic switch to Wi-Fi; expanded Windows / ARM support; on-device vector search continues from 3.2 (see references/couchbase-lite.md).
• Edge Server 1.1 — client-level (per-client) access control; expanded Windows/ARM support. Edge Server is the lightweight on-prem/edge sync+query tier between Lite devices and the cloud.
• Sync Gateway 4.1 — cloud-to-edge sync, non-disruptive rolling upgrades, concurrent distributed resync for high-volume workloads; available as a managed service through App Services.
• React Native 1.1 — Turbo Module integration for direct Couchbase Lite performance without bridging overhead.

Don't remove older-version guidance when relying on these — mixed fleets are common in the field. Treat specific new API signatures as unverified until confirmed against the versioned docs.

Capella App Services vs self-managed Sync Gateway

	Capella App Services	Self-managed Sync Gateway
Management	Fully managed by Couchbase	You manage the install and config
Setup time	Minutes	Hours to days
Scaling	Automatic	Manual (add nodes)
Pricing	Included in Capella tier	License fee
Customization	Sync function via UI/API	Full config file control
Use when	Capella cluster; minimal ops overhead	On-prem; specific config requirements

For new projects on Capella: use App Services. For self-managed Couchbase Server: use Sync Gateway.

Related skills

• couchbase-capella — provisioning the Capella cluster that App Services connects to
• couchbase-data-modeling — document design decisions (especially channel design and conflict-resistant document shapes)
• couchbase-security-hardening — Sync Gateway TLS and authentication configuration