Interface ClientOptions

apiKey is the API key of the project. It is used to identify the project. If not set, API key of the default project is used.

authTokenInjector is a function that provides a token for the auth webhook. When the webhook response status code is 401, this function is called to refresh the token. The reason parameter is the reason from the webhook response.

If the function rejects, the client keeps the previous token, and its loops (the sync loop, the Watch streams and broadcast retries) do not call the function again for a while: 1s after the first failure, doubling up to 30s, jittered. A loop that got a 401 retries on its own after its usual delay, or once that time is up if it is later, but waits at most 5s for it, so the loops come back once the token API does. A one-shot call such as attach, detach, remove or sync calls the function on every 401, as before: it throws the function's error if the function rejects, and the ErrUnauthenticated it received otherwise; retrying it is up to the caller. The first try of broadcast calls it the same way and throws the function's error if it rejects; otherwise broadcast retries as usual.

A rejection is treated as transient. When the function can tell that a refresh will never succeed (for example, the token API answers that the user is signed out), the app should deactivate the client to stop the retries. If the server refuses the deactivation with a 401 as well and the function rejects again, deactivate still stops the client locally and throws the function's error; the server reaps it after its clientDeactivateThreshold.

channelHeartbeatInterval is the interval of the channel heartbeat (ms). The client sends a RefreshChannel heartbeat to refresh the channel session TTL. The default value is 5000 (ms) — co-tuned to the server's ChannelSessionTTL (15 s) at TTL/3. Values larger than the server TTL risk premature session expiry.

deactivateOnUnload controls whether the client registers a beforeunload listener during activate() that deactivates the client when the page is unloaded. The default value is true.

Setting this to false skips the listener registration. This is useful for apps that don't need GC or presence cleanup on unload (for example, disableGC documents without collaboration): the unload-time deactivate becomes pure overhead and its fetch({ keepalive: true }) request can reject mid-flight during hard navigation, surfacing as an unhandled [unknown] ConnectError. The server reaps the stale client after its clientDeactivateThreshold, so opting out is safe.

key is the client key. It is used to identify the client. If not set, a random key is generated from the runtime's CSPRNG; a runtime with no Web Crypto cannot generate one unguessably, so the constructor throws ErrInvalidArgument there rather than activate under a key another client can predict. Pass key to support such a runtime.

That random default is minted per Client instance, so it differs on every launch. Offline persistence requires a stable key: the server derives the actor stamped into every change from the project and this key, and it also scopes the ClientOptions.store keys (apiKey/clientKey/docKey). A new key therefore does not address the previous launch's entries at all — the restore finds nothing, the un-pushed edits are lost silently (no DocEventType.LocalChangesDropped event: the actor-mismatch guard in Document.restoreFromBytes only fires when the same store key is reached under a different actor), and the previous namespace is orphaned. DocStore exposes no enumeration or prune, so nothing can reclaim those entries afterwards and a durable backend grows without bound, one dead namespace per launch.

An app setting store must therefore pass a key it persists itself and reuses on the next launch. Make it an opaque random value the app mints once — crypto.randomUUID() kept in local storage, say — scoped to the signed-in user and cleared on sign-out. Do not derive it from a user id, a device id, an email, or anything else guessable or shared:

• The key is an identifier, not a credential. It is sent verbatim in ActivateClientRequest.client_key and nothing proves the caller owns it, so a guessable key lets another client of the same project activate under the same derived actor and attribute changes to it.
• A key shared between users of one browser (a device id) gives them one store namespace. attach loads and rehydrates the persisted bytes locally before the attach RPC, so the previous user's document content and un-pushed edits would surface in the next user's session ahead of any server authorization.

maxPersistBytes caps the size of a snapshot this client is willing to write. A document whose snapshot exceeds it stops being persisted and a DocEventType.PersistDisabled event is published; editing is unaffected.

Only snapshots are measured. Appends are a few hundred bytes regardless of document size, so they need no budget — the budget exists for the one operation whose cost scales with the document.

Unset means no limit.

maxPersistMillis caps how long serializing a snapshot may block the main thread before this client gives up persisting the document. Same effect and same event as maxPersistBytes. Unset means no limit.

metadata is the metadata of the client. It is used to store additional information about the client.

reconnectStreamDelay is the delay of the reconnect stream. If the stream is disconnected, the client waits for the delay to reconnect the stream, or up to 5s after a 401 while the token refresh backs off (see authTokenInjector). The default value is 1000(ms).

retrySyncLoopDelay is the delay of the retry sync loop. If the sync loop fails, the client waits for the delay to retry the sync loop, or up to 5s after a 401 while the token refresh backs off (see authTokenInjector). The default value is 1000(ms).

rpcAddr is the address of the RPC server. It is used to connect to the server.

sessionLock is the single-active-session guard used only on the offline persistence path (when store is set). Offline persistence derives a stable actor from the app's clientKey, so two tabs of the same app+user share it; two live tabs would share one server checkpoint and mint colliding clientSeq values — silent edit loss. On attach the client acquires a lock keyed by apiKey/clientKey/docKey and holds it for the attachment lifetime; if it is already held (another tab) the attach fails fast. The default WebLocksSessionLock uses the Web Locks API and is a no-op in non-browser runtimes; inject a fake for testing. Ignored when store is unset (non-persistence clients keep today's behavior).

store is a pluggable persistence backend for offline document state. When set, the client writes one base snapshot at attach and then appends each local change, so recording an edit costs the size of that edit rather than of the whole document. The log is compacted back into a snapshot once it grows large relative to it. A sync that only acks a push writes the small meta header; a sync that pulls content writes a snapshot, because the log carries local changes only. On attach the document is rehydrated from the snapshot and the log is replayed over it, so un-pushed local changes survive a reload. The restored checkpoint is presented in the attach ChangePack so the server seeds the client's document sequence from it and re-accepts the re-pushed local changes. When unset (the default), no persistence happens.

For offline persistence you also want deactivateOnUnload: false: the default true deactivates the client on page unload, which detaches documents server-side and defeats the point of resuming un-pushed local changes on the next load. Setting store therefore auto-defaults deactivateOnUnload to false; pass it explicitly to override.

You must also set ClientOptions.key to an opaque random value the app mints once and reuses across launches. Both the store keys and the actor recovery is keyed by are derived from it, and the default is a fresh random key per Client, so leaving it unset means every restart silently loses every un-pushed change and orphans the previous launch's entries. This cannot be defaulted correctly — only the app knows what identity should outlive the process — so the client warns rather than guessing. See ClientOptions.key for why the value must not be a user id, a device id, or anything else guessable or shared between users of one browser.

syncLoopDuration is the duration of the sync loop. After each sync loop, the client waits for the duration to next sync. The default value is 50(ms).

useGrpcWebTransport determines the transport protocol. If true, uses gRPC-Web transport for backward compatibility. If false (default), uses Connect Protocol transport.

userAgent is the user agent of the client. It is used to identify the client.

watchHeartbeatInterval is the interval (ms) at which the client asks the server to send a heartbeat on an idle Watch stream, so that a half-open stream is noticed and reconnected. It is a request, not a setting: the server clamps it to its own bounds and the client times a silent stream out at three times the interval the server actually uses. 0 asks for no heartbeats, which also leaves the stream without an idle timeout. The default value is 20000 (ms).

Unlike channelHeartbeatInterval, which is how often the client sends RefreshChannel to keep a channel session alive, this is how often the server writes to the client's Watch stream.