JavaScript: Initializing

createSupabaseKizunaSync(options) builds the app client over a Supabase project that kizunasync init has provisioned. It derives the protocol remote, the session gate, the Storage transfer, and the Realtime doorbell from the supabase-js client and the config you pass, then hands everything to createKizunaSync. createKizunaSync(driver, remote, config, options?) builds the same client without the Supabase composition, for a hand-assembled remote.

An app creates the client once, at module scope, in src/kizunasync.ts, and every other file imports it from there. Creating it checks the config and opens nothing: the engine opens, and sync starts, on the first call that needs them, so the module is safe to import during a static render or server-side rendering. Vite wires that module into a browser app from install to the first synced row, and Vanilla JavaScript does the same without a framework.

Examples#

Create the app client#

// src/kizunasync.ts
import { byOwner, defineConfig } from 'kizunasync'
import { createSupabaseKizunaSync } from 'kizunasync/supabase'
import { createWebWorkerDriver } from 'kizunasync/web'
import { supabase } from './supabase-client'

const config = defineConfig({
  tables: { todos: { sync: 'read-write', bucket: byOwner('user_id') } },
})

export const kizunasync = createSupabaseKizunaSync({
  supabase,
  driver: createWebWorkerDriver('todos.db'),
  config,
})

That is the whole module. Open the browser driver brings the browser's network signal, and the composition watches the document for the tab coming back, so no platform port is passed by hand. The client follows supabase.auth on its own: an app with its own sign-in screen signs in with supabase-js, and the next pull runs under that session. The engine fills the byOwner bucket with the signed-in user, so no setBucket call is needed for it.

Use it from any file#

// src/todo-list.ts
import { kizunasync } from './kizunasync'

const { data } = await kizunasync.from('todos').select('id, title, done')

The first call that needs the engine opens it, here the read, which answers from the local database at once. The automatic loop starts with that open and runs its first sync right away, so the server's rows arrive without a call to sync(), and Subscribe to events tells a view when to read again.

Sign in anonymously on the first run#

An app whose first screen has no sign-in passes anonymousSignIn: true. Anonymous sign-ins must be enabled on the Supabase project.

// src/kizunasync.ts
import { byOwner, defineConfig } from 'kizunasync'
import { createSupabaseKizunaSync } from 'kizunasync/supabase'
import { createWebWorkerDriver } from 'kizunasync/web'
import { supabase } from './supabase-client'

const config = defineConfig({
  tables: { todos: { sync: 'read-write', bucket: byOwner('user_id') } },
})

export const kizunasync = createSupabaseKizunaSync({
  supabase,
  driver: createWebWorkerDriver('todos.db'),
  config,
  anonymousSignIn: true,
})

When a sync attempt finds no session, the client calls recoverAnonymousSession, which restores a persisted or refreshable session first and signs in a new anonymous user only when there is none. A recovery that fails, for example because the network drops mid-request, fails only that attempt, and the loop retries on its next one.

With attachments#

// src/kizunasync.ts
import { attachment, byOwner, defineConfig } from 'kizunasync'
import { createSupabaseKizunaSync } from 'kizunasync/supabase'
import { createWebFileStore, createWebWorkerDriver } from 'kizunasync/web'
import { supabase } from './supabase-client'

const config = defineConfig({
  tables: {
    todos: {
      sync: 'read-write',
      bucket: byOwner('user_id'),
      attachments: { image_path: attachment('todo-images') },
    },
  },
})

const fileStore = createWebFileStore()

export const kizunasync = createSupabaseKizunaSync({
  supabase,
  driver: createWebWorkerDriver('todos.db'),
  config,
  fileStore,
})

A fileStore alone is enough: the composition builds the Storage transfer over the same client. Browser file store opens its sandbox on the first attachment call that reads or writes bytes, so building it here touches no storage, and a browser without OPFS fails that call with STORE_UNAVAILABLE rather than the module's import. The attachment column borrows user_id from the byOwner bucket as the owner column its object keys derive from. Omitting either port while a table declares attachment() throws ATTACHMENT_PORTS_MISSING.

Without the Supabase composition#

// src/kizunasync.ts
import { createKizunaSync, defineConfig } from 'kizunasync'
import { createRpcRemote } from 'kizunasync/supabase'
import { createWebWorkerDriver } from 'kizunasync/web'
import { supabase } from './supabase-client'

const config = defineConfig({ tables: { todos: { sync: 'read-write' } } })

export const kizunasync = createKizunaSync(createWebWorkerDriver('todos.db'), createRpcRemote(supabase), config)

This client reads no session of its own. supabase-js still attaches its session to each RPC call, but the engine learns who the user is only from the tokens the app passes to Set access token, and a byOwner bucket stays unset until one arrives.

Parameters#

createSupabaseKizunaSync(options):

createKizunaSync(driver, remote, config, options?) takes the same options minus supabase, anonymousSignIn, wakeupOptions, remoteOptions, refreshOnForeground, and sessionTimeoutMs, which belong to the Supabase composition:

Returns#

An IKizunaSync client. It is a plain object, so members can be destructured. Building it opens nothing. The first call to any member opens the engine, once for the client's lifetime, except for connectivity, setRemoteAccessToken, dispose, and a read of the inspector or attachments property.

Errors#

Creating the client throws only for a configuration it can check on its own:

Opening the engine happens on the first call that needs it, and a failed open surfaces there, never at import:

A failed open is kept as one typed TEngineError, and the client never tries to open again. The call that opened it and every later promise-returning call reject with that same error, setBucket and a read of engine throw it, on and the attachment and inspector subscriptions stay silent, and Sync health reports it: getSyncHealth() returns phase backoff with the error as lastError, and an onSyncHealth listener hears that snapshot once. A hook built on the client therefore shows one stable error state instead of crashing a render. Open the browser driver lists how a browser store that cannot open fails.

Notes#

The composition reads auth.getSession() before every pull and push, applies the token to the engine, and subscribes to auth.onAuthStateChange so a refreshed session reaches the engine without another call from you. A missing session raises the retryable AUTH_SESSION_MISSING, after the anonymous recovery when anonymousSignIn is set, rather than falling back to the publishable key, which would run the pull and push RPCs as the anon role: those RPCs are granted only to authenticated, so an anon call would fail a different way. Create the Storage transfer documents the separate publishable-key fallback a resumable upload takes when the Storage bucket allows it.

The first session token the engine sees names the user the local database belongs to. The engine keeps that owner in the database, fills every byOwner bucket with it, and fills the owner column of an insert that leaves it out. After a restart both are filled from the database before any session is read, offline included. A token of another user on the same device soft-blocks sync with identity_changed until reset() runs, so writes queued under one user never go out under another. An account switch is a reset(), which Sync soft-blocks after switching accounts walks through. setBucket is for byColumn buckets, whose value only the app knows.

On a foreground signal the composition refreshes the session, calls realtime.connect() when the client holds channels but the socket reports disconnected, and only then wakes the scheduler. That reconnect matters because a backgrounded tab can lose its socket without a status event, which Supabase describes in handling silent disconnections.

On Expo and React Native, Expo: Open the SQLite driver returns a driver that carries the device's own network and foreground ports, and Expo: Initializing lists the options that composition takes.

Next steps#

1. Provide the client: import kizunasync from src/kizunasync.ts wherever the UI needs it. React: Initializing and Vue: Initializing hand it to the component tree, and Vanilla JavaScript imports it from the entry file.
2. Sign in: sign in with supabase-js wherever your app already does, as Supabase describes in Auth, or pass anonymousSignIn: true when the first run has no sign-in screen.
3. Read: Fetch data answers from the local database, and Subscribe to events tells a view when to read again.
4. Write: Insert data, Update data, and Delete data commit locally and queue the change for the server.
5. Show sync state: Sync health and Outbox depth feed an indicator.

Nothing else has to run for the data to move. The client syncs once as soon as it opens, after every local write, on a poll every 15 seconds or so (a random point between half the interval and the whole of it), when the network or the tab comes back, and on a Realtime doorbell signal, so Sync is for a Sync now button, a pull-to-refresh, or a test.

Related reference#

• Installing
• Define config
• Sync
• List overwrites
• Open the browser driver
• React: Initializing
• Vue: Initializing
• Swift: Initializing
• Kotlin: Initializing