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);

Classes

• ConvexHttpClient
• BaseConvexClient

Interfaces

• ClientOptions
• SubscribeOptions
• MutationOptions
• OptimisticLocalStore

Type Aliases

ConvexFunction

Ƭ ConvexFunction: (args?: any) => any

Type declaration

▸ (args?): any

The type of a Convex function in a GenericAPI.

This is used only in type parameter bounds so it has loose types with any.

Parameters

Name	Type
args?	any

Returns

any

Defined in

api/index.ts:15

---

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 dev. It's used to make the Convex clients type-safe.

Type declaration

Name	Type
publicQueries	Record<string, ConvexFunction>
allQueries	Record<string, ConvexFunction>
publicMutations	Record<string, ConvexFunction>
allMutations	Record<string, ConvexFunction>
publicActions	Record<string, ConvexFunction>
allActions	Record<string, ConvexFunction>

Defined in

api/index.ts:25

---

QueryNames

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

The names of query functions in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI

Defined in

api/index.ts:43

---

PublicQueryNames

Ƭ PublicQueryNames<API>: keyof API["publicQueries"] & string

The names of public query functions in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI

Defined in

api/index.ts:51

---

MutationNames

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

The names of mutation functions in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI

Defined in

api/index.ts:59

---

PublicMutationNames

Ƭ PublicMutationNames<API>: keyof API["publicMutations"] & string

The names of public mutation functions in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI

Defined in

api/index.ts:67

---

ActionNames

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

The names of actions in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI

Defined in

api/index.ts:75

---

PublicActionNames

Ƭ PublicActionNames<API>: keyof API["publicActions"] & string

The names of public query functions in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI

Defined in

api/index.ts:83

---

NamedQuery

Ƭ NamedQuery<API, Name>: API["allQueries"][Name]

The type of a query function in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI
Name	extends QueryNames<API>

Defined in

api/index.ts:90

---

NamedMutation

Ƭ NamedMutation<API, Name>: API["allMutations"][Name]

The type of a mutation function in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI
Name	extends MutationNames<API>

Defined in

api/index.ts:100

---

NamedAction

Ƭ NamedAction<API, Name>: API["allActions"][Name]

The type of an action in a Convex API.

Type parameters

Name	Type
API	extends GenericAPI
Name	extends ActionNames<API>

Defined in

api/index.ts:110

---

ArgsObject

Ƭ ArgsObject<F>: Parameters<F>["length"] extends 0 ? EmptyObject : Parameters<F>[0]

The type of the arguments to a Convex function.

This is represented as a single object mapping argument names to values. Functions that don't need any arguments object are represented as {}.

Type parameters

Name	Type
F	extends ConvexFunction

Defined in

api/index.ts:129

---

OptionalRestArgs

Ƭ OptionalRestArgs<F>: Parameters<F>["length"] extends 0 ? [args?: EmptyObject] : [args: Parameters<F>[0]]

An tuple type of the (maybe optional) arguments to F.

This type is used to make methods involving arguments type safe while allowing skipping the arguments for functions that don't require arguments.

Type parameters

Name	Type
F	extends ConvexFunction

Defined in

api/index.ts:140

---

ArgsAndOptions

Ƭ ArgsAndOptions<F, Options>: Parameters<F>["length"] extends 0 ? [args?: EmptyObject, options?: Options] : [args: Parameters<F>[0], options?: Options]

A tuple type of the (maybe optional) arguments to F, followed by an options object of type Options.

This type is used to make methods like useQuery type-safe while allowing

1. Skipping arguments for functions that don't require arguments.
2. Skipping the options object.

Type parameters

Name	Type
F	extends ConvexFunction
Options	Options

Defined in

api/index.ts:154

---

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

Name	Type
Modules	extends Record<string, Record<string, any>>

Type declaration

Name	Type
publicQueries	Expand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isQuery: true ; isPublic: true }>>>
allQueries	Expand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isQuery: true }>>>
publicMutations	Expand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isMutation: true ; isPublic: true }>>>
allMutations	Expand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isMutation: true }>>>
publicActions	Expand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isAction: true ; isPublic: true }>>>
allActions	Expand<ConvertToClientFunctions<PickByValue<MergeAllExports<Modules>, { isAction: true }>>>

Defined in

api/index.ts:232

---

FunctionResult

Ƭ FunctionResult: { success: true ; value: Value ; logLines: string[] } | { success: false ; errorMessage: string ; logLines: string[] }

The result of running a function on the server.

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

Defined in

browser/sync/function_result.ts:11

---

OptimisticUpdate

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

Type parameters

Name	Type
API	extends GenericAPI
Args	extends Record<string, 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

Name	Type	Description
localQueryStore	OptimisticLocalStore<API>	An interface to read and edit local query results.
args	Args	The arguments to the mutation.

Returns

void

Defined in

browser/sync/optimistic_updates.ts:90

---

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.

Defined in

browser/sync/protocol.ts:111

---

UserIdentityAttributes

Ƭ UserIdentityAttributes: Omit<UserIdentity, "tokenIdentifier">

Defined in

browser/sync/protocol.ts:159

---

QueryToken

Ƭ QueryToken: string

A string representing the name and arguments of a query.

This is used by the BaseConvexClient.

Defined in

browser/sync/udf_path_utils.ts:27