Interface: BaseConvexClientOptions
For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.
browser.BaseConvexClientOptions
Options for BaseConvexClient.
Hierarchy
-
BaseConvexClientOptions
Properties
unsavedChangesWarning
• Optional unsavedChangesWarning: boolean
Whether to prompt the user if they have unsaved changes pending when navigating away or closing a web page.
This is only possible when the window object exists, i.e. in a browser.
The default value is true in browsers.
Defined in
webSocketConstructor
• Optional webSocketConstructor: Object
Call signature
• new webSocketConstructor(url, protocols?): WebSocket
Specifies an alternate
WebSocket
constructor to use for client communication with the Convex cloud.
The default behavior is to use WebSocket from the global environment.
Parameters
| Name | Type |
|---|---|
url | string | URL |
protocols? | string | string[] |
Returns
WebSocket
Type declaration
| Name | Type |
|---|---|
prototype | WebSocket |
CONNECTING | 0 |
OPEN | 1 |
CLOSING | 2 |
CLOSED | 3 |
Defined in
verbose
• Optional verbose: boolean
Adds additional logging for debugging purposes.
The default value is false.
Defined in
logger
• Optional logger: boolean | Logger
A logger, true, or false. If not provided or true, logs to the console.
If false, logs are not printed anywhere.
You can construct your own logger to customize logging to log elsewhere. A logger is an object with 4 methods: log(), warn(), error(), and logVerbose(). These methods can receive multiple arguments of any types, like console.log().
Defined in
reportDebugInfoToConvex
• Optional reportDebugInfoToConvex: boolean
Sends additional metrics to Convex for debugging purposes.
The default value is false.
Defined in
onServerDisconnectError
• Optional onServerDisconnectError: (message: string) => void
Type declaration
▸ (message): void
This API is experimental: it may change or disappear.
A function to call on receiving abnormal WebSocket close messages from the connected Convex deployment. The content of these messages is not stable, it is an implementation detail that may change.
Consider this API an observability stopgap until higher level codes with
recommendations on what to do are available, which could be a more stable
interface instead of string.
Check connectionState for more quantitative metrics about connection status.
Parameters
| Name | Type |
|---|---|
message | string |
Returns
void
Defined in
skipConvexDeploymentUrlCheck
• Optional skipConvexDeploymentUrlCheck: boolean
Skip validating that the Convex deployment URL looks like
https://happy-animal-123.convex.cloud or localhost.
This can be useful if running a self-hosted Convex backend that uses a different URL.
The default value is false
Defined in
authRefreshTokenLeewaySeconds
• Optional authRefreshTokenLeewaySeconds: number
If using auth, the number of seconds before a token expires that we should refresh it.
The default value is 10.
Defined in
expectAuth
• Optional expectAuth: boolean
This API is experimental: it may change or disappear.
Whether query, mutation, and action requests should be held back until the first auth token can be sent.
Opting into this behavior works well for pages that should only be viewed by authenticated clients.
Defaults to false, not waiting for an auth token.
Defined in
initialAuthTokenReuse
• Optional initialAuthTokenReuse: boolean
This API is experimental: it may change or disappear.
When true, the client reuses the initial cached auth token instead of immediately fetching a fresh one. This avoids a second Authenticate message that causes the server to re-execute all authenticated queries.
The cached token's remaining lifetime is estimated using the server's clock skew measurement, and a refresh is scheduled before it expires.
Defaults to false, preserving the original behavior of immediately fetching a fresh token after the cached token is confirmed.