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.

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 persists doc.toBytes() after every local change on a document attached through it, and on attach it rehydrates the document from any persisted bytes 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.