Documentation
Get up and running with Kizuna
Offline-first sync for the Supabase project you own. Start with the introduction, run kizunasync in your app project, or open the playground.
Getting started
Connect a framework
Start with a how-to for the UI you already ship. Dedicated bindings are React and Vue; Swift and Kotlin use KizunaSyncClient; every other JavaScript UI uses the core client.
React
Wire KizunaSyncProvider and the useQuery, useMutation, useSyncStatus, and useAttachment hooks into a React app
Vue
Provide the kizunasync/vue composables and read, write, and track sync status in a Vue 3 app
Expo / React Native
Wire the offline-first sync engine into Expo or React Native, from the SQLite driver to session persistence and attachments
Swift and Kotlin
Build the in-repository UniFFI bindings and understand their current Alpha distribution limits
Vite
Wire the browser worker driver and OPFS file store into a Vite-based React or Vue app with Supabase
Vanilla
Wire the core client into vanilla JavaScript or any UI without a dedicated Kizuna binding
Client library reference
Supabase-style API reference for each client library: methods, guides, and types rendered in-site.
Swift
AlphaKizunaSyncClient over UniFFI for iOS and macOS apps: typed config, optimistic writes, local queries, sync, rejections, events, and attachments
Kotlin
AlphaKizunaSyncClient over UniFFI for Android apps: typed config, optimistic writes, local queries, sync, rejections, events, and attachments
JavaScript
Alphakizunasync, kizunasync/supabase, and kizunasync/web: createKizunaSync, the local query builder, sync controls, adapters, and the browser driver
React
AlphaKizunaSyncProvider and the useKizunaSync, useQuery, useMutation, useSyncStatus, useAttachment, useRejections, and useOverwrites hooks
Vue
AlphacreateKizunaSyncPlugin, provideKizunaSync, and the useKizunaSync, useQuery, useMutation, useSyncStatus, useAttachment, useRejections, and useOverwrites composables
Expo
AlphaSQLite drivers, connectivity, file store, and native download helpers for Expo and React Native
Sync
Offline writes
Durable queues, verdicts, sync state in your UI, patterns and limits
Sync rules & buckets
RLS as security, buckets as selection, the adoption ladder
Validate writes
Enforce your rules in Postgres with RLS, preconditions, constraints, and triggers, and surface every rejection in the app
Collaborative fields
Independent columns, increment and array transforms, the conflict journal, and client-side text merge
Conflict resolution
How concurrent writes are detected, ordered, and resolved
Server-side validation
Where every write is validated, which guards answer with a clean verdict, and how a rejection reaches your UI
Consistency model
The guarantees and their limits
Fencing and horizons
Why a naive cursor skips committed changes, and the xid8 horizon that fixes it
Protocol overview
The wire protocol, message types, and session lifecycle
Attachments
CLI & provisioning
CLI
init · sync · status · doctor · lint · upgrade · deprovision · mock
Configuration
kizunasync._config and kizunasync._settings: every column, every default
Install
Preview the plan and provision the SQL pack locally or through the Management API
What Kizuna installs
The Kizuna schema, internal tables, five public RPCs, per-table triggers, provision ledger, and grants created by the current pack
Manage synced tables
Use kizunasync sync to edit the synchronized table set, generate one delta migration, and optionally apply it
Upgrade
Reconcile an installed project file ledger with the current pack and refuse drift or breaking pending files
Remove
Preview and remove understood ledgered Kizuna objects while preserving application tables and data
Local Supabase
Start, inspect, migrate, stop, and deliberately reset the repository local Supabase development stack
Testing & operations
Test offline behavior
Fault injection, the headless matrix, CI integration
CI and CD
The quality gate, Supabase database tests, and conformance corpus harness that run on every push and pull request
Troubleshooting
Diagnose the OPFS lock, bucket, attachment, and RLS errors you hit most often, with the exact fix for each
Reference
Client library comparison
Which capabilities each Kizuna client library supports
Supported query operators
Every postgrest-js method and option, with its status in the JavaScript, Swift, and Kotlin app clients
SQL pack
The tables, RPCs, sequences, and maintenance functions the 0001_kizuna_init.sql migration provisions into your project
Protocol reference
Wire shapes, verdict kinds, the cursor codec, and fencing rules, cross-referenced to the conformance corpus
Status taxonomy
Maturity labels, decision and corpus statuses, sync phases, attachment states, rejection kinds, and wire status values
Drivers and the TCK
The platform-port boundary, protocol-corpus evidence, and the limits of current driver conformance
Resources
FAQ
Answers about offline periods, supabase-js, files, conflicts, security, platforms, and cost
Comparison with alternatives
How Kizuna compares with PowerSync, Electric, Zero, Firestore, and other sync libraries, and when to choose each
Architecture
The device engine, the SQL pack, and what deliberately does not exist
Design trade-offs
What Kizuna deliberately does not do, why, what it does instead, and how each trade-off is enforced
Protocol decisions
The open-decision model, what is implemented, and what remains planned
Repository layout
Rust kernel, UniFFI and N-API bridges, JS/Swift/Kotlin app clients, CLI, and examples
Native packaging
Regenerate UniFFI bindings and build the XCFramework, AAR, and React Native module from a checkout
Glossary
Definitions for terms used throughout the Kizuna documentation
Roadmap
Implemented Alpha surfaces, remaining release gaps, and later work without presenting plans as shipped features
Contribute
How to build, test, document, and license a change to Kizuna
Governance
Apache-2.0, PolyForm Shield on the SQL pack, never-paywall drivers, RFC process, honesty rules