Skip to main content

Module: browser

Tools for accessing Convex in the browser.

If you are using React, use the react module instead.

Usage

Create a ConvexHttpClient to connect to the Convex Cloud.

import { ConvexHttpClient } from "convex/browser";
// typically loaded from an environment variable
const address = "https://small-mouse-123.convex.cloud";
const convex = new ConvexHttpClient(address);

Interfaces

Classes

Type Aliases

GenericAPI

Ƭ GenericAPI: Object

Description of the Convex functions available to an application.

This is a generic type that expresses the shape of API types created by npx convex codegen. It's used to make the Convex clients type-safe.

Type declaration

NameType
queriesRecord<string, (...args: any[]) => any>
mutationsRecord<string, (...args: any[]) => any>
actionsRecord<string, (...args: any[]) => any>

QueryNames

Ƭ QueryNames<API>: keyof API["queries"] & string

The names of query functions in a Convex API.

Type parameters

NameType
APIextends GenericAPI

MutationNames

Ƭ MutationNames<API>: keyof API["mutations"] & string

The names of mutation functions in a Convex API.

Type parameters

NameType
APIextends GenericAPI

ActionNames

Ƭ ActionNames<API>: keyof API["actions"] & string

The names of actions in a Convex API.

Type parameters

NameType
APIextends GenericAPI

NamedQuery

Ƭ NamedQuery<API, Name>: API["queries"][`Name`]

The type of a query function in a Convex API.

Type parameters

NameType
APIextends GenericAPI
Nameextends QueryNames<API>

NamedMutation

Ƭ NamedMutation<API, Name>: API["mutations"][`Name`]

The type of a mutation function in a Convex API.

Type parameters

NameType
APIextends GenericAPI
Nameextends MutationNames<API>

NamedAction

Ƭ NamedAction<API, Name>: API["actions"][`Name`]

The type of an action in a Convex API.

Type parameters

NameType
APIextends GenericAPI
Nameextends MutationNames<API>

ApiFromModules

Ƭ ApiFromModules<Modules>: Object

Create the API type from the types of all of the modules.

Input is an object mapping file paths to the type of each module.

For internal use by Convex code generation.

Type parameters

NameType
Modulesextends Record<string, Record<string, any>>

Type declaration

NameType
queriesExpand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isQuery: true }>>>
mutationsExpand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isMutation: true }>>>
actionsExpand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isAction: true }>>>

OptimisticUpdate

Ƭ OptimisticUpdate<API, Arguments>: (localQueryStore: OptimisticLocalStore<API>, ...args: Arguments) => void

Type parameters

NameType
APIextends GenericAPI
Argumentsextends Value[]

Type declaration

▸ (localQueryStore, ...args): void

A temporary, local update to query results within this client.

This update will always be executed when a mutation is synced to the Convex server and rolled back when the mutation completes.

Note that optimistic updates can be called multiple times! If the client loads new data while the mutation is in progress, the update will be replayed again.

Parameters
NameTypeDescription
localQueryStoreOptimisticLocalStore<API>An interface to read and edit local query results.
...argsArgumentsThe arguments to the mutation.
Returns

void


QueryJournal

Ƭ QueryJournal: string | null

A serialized representation of decisions made during a query's execution.

A journal is produced when a query function first executes and is re-used when a query is re-executed.

Currently this is used to store pagination end cursors to ensure that pages of paginated queries will always end at the same cursor. This enables gapless, reactive pagination.

null is used to represent empty journals.


QueryResult

Ƭ QueryResult: { success: true ; value: Value } | { success: false ; errorMessage: string }

The result of running a query function on the server.

If the function hit an exception it will have an errorMessage. Otherwise it will produce a Value.


QueryToken

Ƭ QueryToken: string

A string representing the name and arguments of a query.

This is used by the InternalConvexClient.