Class: ConvexReactClient
react.ConvexReactClient
A Convex client for use within React.
This loads reactive queries and executes mutations over a WebSocket.
Constructors
constructor
• new ConvexReactClient(address, options?)
Parameters
| Name | Type | Description |
|---|---|---|
address | string | The url of your Convex deployment, often provided by an environment variable. E.g. https://small-mouse-123.convex.cloud. |
options? | ConvexReactClientOptions | See ConvexReactClientOptions for a full description. |
Defined in
Accessors
url
• get url(): string
Return the address for this client, useful for creating a new client.
Not guaranteed to match the address with which this client was constructed: it may be canonicalized.
Returns
string
Defined in
logger
• get logger(): Logger
Get the logger for this client.
Returns
Logger
The Logger for this client.
Defined in
Methods
setAuth
▸ setAuth(fetchToken, onChange?): void
Set the authentication token to be used for subsequent queries and mutations.
fetchToken will be called automatically again if a token expires.
fetchToken should return null if the token cannot be retrieved, for example
when the user's rights were permanently revoked.
Parameters
| Name | Type | Description |
|---|---|---|
fetchToken | AuthTokenFetcher | an async function returning the JWT-encoded OpenID Connect Identity Token |
onChange? | (isAuthenticated: boolean) => void | a callback that will be called when the authentication status changes |
Returns
void
Defined in
clearAuth
▸ clearAuth(): void
Clear the current authentication token if set.
Returns
void
Defined in
watchQuery
▸ watchQuery<Query>(query, ...argsAndOptions): Watch<FunctionReturnType<Query>>
Construct a new Watch on a Convex query function.
Most application code should not call this method directly. Instead use the useQuery hook.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
query | Query | A FunctionReference for the public query to run. |
...argsAndOptions | ArgsAndOptions<Query, WatchQueryOptions> | - |
Returns
Watch<FunctionReturnType<Query>>
The Watch object.
Defined in
prewarmQuery
▸ prewarmQuery<Query>(queryOptions): void
Indicates likely future interest in a query subscription.
The implementation currently immediately subscribes to a query. In the future this method may prioritize some queries over others, fetch the query result without subscribing, or do nothing in slow network connections or high load scenarios.
To use this in a React component, call useQuery() and ignore the return value.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
queryOptions | ConvexQueryOptions<Query> & { extendSubscriptionFor?: number } | A query (function reference from an api object) and its args, plus an optional extendSubscriptionFor for how long to subscribe to the query. |
Returns
void
Defined in
mutation
▸ mutation<Mutation>(mutation, ...argsAndOptions): Promise<FunctionReturnType<Mutation>>
Execute a mutation function.
Type parameters
| Name | Type |
|---|---|
Mutation | extends FunctionReference<"mutation"> |
Parameters
| Name | Type | Description |
|---|---|---|
mutation | Mutation | A FunctionReference for the public mutation to run. |
...argsAndOptions | ArgsAndOptions<Mutation, MutationOptions<FunctionArgs<Mutation>>> | - |
Returns
Promise<FunctionReturnType<Mutation>>
A promise of the mutation's result.
Defined in
action
▸ action<Action>(action, ...args): Promise<FunctionReturnType<Action>>
Execute an action function.
Type parameters
| Name | Type |
|---|---|
Action | extends FunctionReference<"action"> |
Parameters
| Name | Type | Description |
|---|---|---|
action | Action | A FunctionReference for the public action to run. |
...args | OptionalRestArgs<Action> | An arguments object for the action. If this is omitted, the arguments will be {}. |
Returns
Promise<FunctionReturnType<Action>>
A promise of the action's result.
Defined in
query
▸ query<Query>(query, ...args): Promise<FunctionReturnType<Query>>
Fetch a query result once.
Most application code should subscribe to queries instead, using the useQuery hook.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
query | Query | A FunctionReference for the public query to run. |
...args | OptionalRestArgs<Query> | An arguments object for the query. If this is omitted, the arguments will be {}. |
Returns
Promise<FunctionReturnType<Query>>
A promise of the query's result.
Defined in
connectionState
▸ connectionState(): ConnectionState
Get the current ConnectionState between the client and the Convex backend.
Returns
The ConnectionState with the Convex backend.
Defined in
subscribeToConnectionState
▸ subscribeToConnectionState(cb): () => void
Subscribe to the ConnectionState between the client and the Convex backend, calling a callback each time it changes.
Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently. ConnectionState may also lose properties in future versions as we figure out what information is most useful. As such this API is considered unstable.
Parameters
| Name | Type |
|---|---|
cb | (connectionState: ConnectionState) => void |
Returns
fn
An unsubscribe function to stop listening.
▸ (): void
Subscribe to the ConnectionState between the client and the Convex backend, calling a callback each time it changes.
Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently. ConnectionState may also lose properties in future versions as we figure out what information is most useful. As such this API is considered unstable.
Returns
void
An unsubscribe function to stop listening.
Defined in
close
▸ close(): Promise<void>
Close any network handles associated with this client and stop all subscriptions.
Call this method when you're done with a ConvexReactClient to dispose of its sockets and resources.
Returns
Promise<void>
A Promise fulfilled when the connection has been completely closed.