Couchbase Mobile

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: celticht32
• Source: celticht32/Couchbase-Skills-for-Claude.ai
• License: MIT

Install and usage instructions live in the source repository linked above.