Class: ConvexHttpClient
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.ConvexHttpClient
A Convex client that runs queries and mutations over HTTP.
This client is stateful (it has user credentials and queues mutations) so take care to avoid sharing it between requests in a server.
This is appropriate for server-side code (like Netlify Lambdas) or non-reactive webapps.
Constructors
constructor
• new ConvexHttpClient(address, options?)
Create a new ConvexHttpClient.
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? | Object | An object of options. - skipConvexDeploymentUrlCheck - 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. - logger - A logger or a boolean. If not provided, logs to the console. You can construct your own logger to customize logging to log elsewhere or not log at all, or use false as a shorthand for a no-op logger. 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(). - auth - A JWT containing identity claims accessible in Convex functions. This identity may expire so it may be necessary to call setAuth() later, but for short-lived clients it's convenient to specify this value here. - fetch - A custom fetch implementation to use for all HTTP requests made by this client. |
options.skipConvexDeploymentUrlCheck? | boolean | - |
options.logger? | boolean | Logger | - |
options.auth? | string | - |
options.fetch? | (input: URL | RequestInfo, init?: RequestInit) => Promise<Response>(input: string | URL | Request, init?: RequestInit) => Promise<Response> | - |
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
Methods
backendUrl
▸ backendUrl(): string
Obtain the ConvexHttpClient's URL to its backend.
Deprecated
Use url, which returns the url without /api at the end.
Returns
string
The URL to the Convex backend, including the client's API version.
Defined in
setAuth
▸ setAuth(value): void
Set the authentication token to be used for subsequent queries and mutations.
Should be called whenever the token changes (i.e. due to expiration and refresh).
Parameters
| Name | Type | Description |
|---|---|---|
value | string | JWT-encoded OpenID Connect identity token. |
Returns
void
Defined in
clearAuth
▸ clearAuth(): void
Clear the current authentication token if set.
Returns
void
Defined in
consistentQuery
▸ consistentQuery<Query>(query, ...args): Promise<FunctionReturnType<Query>>
This API is experimental: it may change or disappear.
Execute a Convex query function at the same timestamp as every other consistent query execution run by this HTTP client.
This doesn't make sense for long-lived ConvexHttpClients as Convex backends can read a limited amount into the past: beyond 30 seconds in the past may not be available.
Create a new client to use a consistent time.
Deprecated
This API is experimental: it may change or disappear.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> | FunctionReference_future<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
query | Query | - |
...args | OptionalRestArgs<Query> | The 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
query
▸ query<Query>(query, ...args): Promise<FunctionReturnType<Query>>
Execute a Convex query function.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> | FunctionReference_future<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
query | Query | - |
...args | OptionalRestArgs<Query> | The 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
mutation
▸ mutation<Mutation>(mutation, ...args): Promise<FunctionReturnType<Mutation>>
Execute a Convex mutation function. Mutations are queued by default.
Type parameters
| Name | Type |
|---|---|
Mutation | extends FunctionReference<"mutation"> | FunctionReference_future<"mutation"> |
Parameters
| Name | Type | Description |
|---|---|---|
mutation | Mutation | - |
...args | ArgsAndOptions<Mutation, HttpMutationOptions> | The arguments object for the mutation. If this is omitted, the arguments will be {}. |
Returns
Promise<FunctionReturnType<Mutation>>
A promise of the mutation's result.
Defined in
action
▸ action<Action>(action, ...args): Promise<FunctionReturnType<Action>>
Execute a Convex action function. Actions are not queued.
Type parameters
| Name | Type |
|---|---|
Action | extends FunctionReference<"action"> | FunctionReference_future<"action"> |
Parameters
| Name | Type | Description |
|---|---|---|
action | Action | - |
...args | OptionalRestArgs<Action> | The arguments object for the action. If this is omitted, the arguments will be {}. |
Returns
Promise<FunctionReturnType<Action>>
A promise of the action's result.