Skip to main content

Class: ConvexHttpClient<API>

browser.ConvexHttpClient

A Convex client that runs queries and mutations over HTTP.

This is appropriate for server-side code (like Netlify Lambdas) or non-reactive webapps.

If you're building a React app, consider using ConvexReactClient instead.

To ConvexHttpClient with TypeScript type specific to your API, pass in the API type parameter:

import { ConvexHttpClient } from "convex/browser";
import { API } from "./convex/_generated/api";

const client = new ConvexHttpClient<API>(process.env["CONVEX_URL"]);

Type parameters

NameType
APIextends GenericAPI

Constructors

constructor

new ConvexHttpClient<API>(address)

Create a new ConvexHttpClient.

Type parameters

NameType
APIextends GenericAPI

Parameters

NameTypeDescription
addressstringThe url of your Convex deployment, often provided by an environment variable. E.g. https://small-mouse-123.convex.cloud.

Defined in

browser/http_client.ts:61

Methods

backendUrl

backendUrl(): string

Obtain the ConvexHttpClient's URL to its backend.

Returns

string

The URL to the Convex backend, including the client's API version.

Defined in

browser/http_client.ts:72


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

NameTypeDescription
valuestringJWT-encoded OpenID Connect identity token.

Returns

void

Defined in

browser/http_client.ts:83


clearAuth

clearAuth(): void

Clear the current authentication token if set.

Returns

void

Defined in

browser/http_client.ts:99


query

query<Name>(name, ...args): Promise<ReturnType<NamedQuery<API, Name>>>

Execute a Convex query function.

Type parameters

NameType
Nameextends string

Parameters

NameTypeDescription
nameNameThe name of the query.
...argsOptionalRestArgs<NamedQuery<API, Name>>The arguments object for the query. If this is omitted, the arguments will be {}.

Returns

Promise<ReturnType<NamedQuery<API, Name>>>

A promise of the query's result.

Defined in

browser/http_client.ts:121


mutation

mutation<Name>(name, ...args): Promise<ReturnType<NamedMutation<API, Name>>>

Execute a Convex mutation function.

Type parameters

NameType
Nameextends string

Parameters

NameTypeDescription
nameNameThe name of the mutation.
...argsOptionalRestArgs<NamedMutation<API, Name>>The arguments object for the mutation. If this is omitted, the arguments will be {}.

Returns

Promise<ReturnType<NamedMutation<API, Name>>>

A promise of the mutation's result.

Defined in

browser/http_client.ts:175


action

action<Name>(name, ...args): Promise<ReturnType<NamedAction<API, Name>>>

Execute a Convex action function.

Type parameters

NameType
Nameextends string

Parameters

NameTypeDescription
nameNameThe name of the action.
...argsOptionalRestArgs<NamedAction<API, Name>>The arguments object for the action. If this is omitted, the arguments will be {}.

Returns

Promise<ReturnType<NamedAction<API, Name>>>

A promise of the action's result.

Defined in

browser/http_client.ts:226