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.

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.

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. 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. 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.

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.