API reference

The library ships three entry points. Everything listed on this page is part of the public API; nothing else is.

Entry point	Contents
convex-angular	The main surface: providers, injection tokens, the inject* helpers for queries, mutations and actions, authentication, structural directives, route guards, and the route resolver.
convex-angular/testing	MockConvexClient and provideConvexTesting() — an in-memory stand-in for ConvexClient so components and services can be unit-tested without a Convex deployment. Import it in test files only.
convex-angular/better-auth	The Better Auth integration: provideBetterAuth(), injectBetterAuth(), and the structurally-typed client contract. Kept separate so the main entry point carries no Better Auth types.

The tables below index every export by category. Kind distinguishes runtime values (function, const, class, InjectionToken, directive) from type-only exports (type, interface) that disappear at compile time.

Providers & tokens

Symbol	Kind	Entry point	Description	Reference
provideConvex	function	convex-angular	Creates the ConvexClient and registers it, plus the SSR services, in the root injector. Call it exactly once.	Providers
ProvideConvexOptions	interface	convex-angular	Options for provideConvex(): every ConvexClientOptions field plus an ssr section.	Providers
CONVEX	InjectionToken	convex-angular	The InjectionToken<ConvexClient> under which the client is registered. Override it to substitute a client.	Providers
injectConvex	function	convex-angular	Returns the ConvexClient instance for direct, low-level use.	ConvexClient
InjectConvexOptions	interface	convex-angular	Options for injectConvex(); carries only injectRef.	Injection context
injectConvexConnectionState	function	convex-angular	A readonly Signal<ConnectionState> that tracks WebSocket connectivity and in-flight request counts.	Connection state
InjectConvexConnectionStateOptions	interface	convex-angular	Options for injectConvexConnectionState(); carries only injectRef.	Connection state
ConvexSsrOptions	interface	convex-angular	The ssr section of ProvideConvexOptions: fetchOnServer, authToken, transferAuthenticatedResults.	SSR configuration

Queries

Symbol	Kind	Entry point	Description	Reference
injectQuery	function	convex-angular	Subscribes to a Convex query and exposes its data, error, and status as Signals. Resubscribes when the reactive args change.	injectQuery
QueryOptions	interface	convex-angular	Options for injectQuery(): injectRef, onSuccess, onError, placeholderData.	injectQuery
QueryResult	interface	convex-angular	The object injectQuery() returns: data, error, isLoading, isRefetching, isPlaceholderData, isSkipped, isSuccess, status, refetch.	injectQuery
QueryReference	type	convex-angular	FunctionReference<'query'> — the type of any query on your generated api object.	injectQuery
QueryPlaceholderData	type	convex-angular	The placeholderData option’s type: a plain value, or a factory taking the current args.	Placeholder data
skipToken	const	convex-angular	A unique symbol returned from an args function to suspend a query without unmounting the helper.	skipToken
SkipToken	type	convex-angular	typeof skipToken, for typing args functions that may skip.	skipToken
injectQueries	function	convex-angular	Subscribes to a dynamic, keyed map of queries and exposes keyed results, errors, and statuses Signals.	injectQueries
QueriesDefinition	type	convex-angular	Record<string, QueryRequest | SkipToken> — the shape the definitions function returns.	injectQueries
QueryRequest	interface	convex-angular	One entry in a QueriesDefinition: a query reference plus its args.	injectQueries
QueriesOptions	interface	convex-angular	Options for injectQueries(): injectRef, and key-aware onSuccess / onError.	injectQueries
QueriesResult	interface	convex-angular	The object injectQueries() returns: results, errors, statuses, isLoading, refetch.	injectQueries
injectPaginatedQuery	function	convex-angular	Loads a paginated query as a growing list, for infinite-scroll UIs. Uses Convex’s experimental paginated subscription client.	Pagination
PaginatedQueryOptions	interface	convex-angular	Options for injectPaginatedQuery(): the required initialNumItems (a number or a Signal), plus injectRef, onSuccess, onError.	Pagination
PaginatedQueryResult	interface	convex-angular	The object injectPaginatedQuery() returns: results, error, isLoadingFirstPage, isLoadingMore, canLoadMore, isExhausted, isSkipped, isSuccess, status, loadMore, reset.	Pagination
PaginatedQueryReference	type	convex-angular	A public query taking a paginationOpts argument and returning a PaginationResult.	Pagination
PaginatedQueryArgs	type	convex-angular	A paginated query’s args with paginationOpts removed — what you return from the args function.	Pagination
PaginatedQueryItem	type	convex-angular	The element type of a paginated query’s page array.	Pagination
injectPrewarmQuery	function	convex-angular	Returns a prewarm(args) function that opens a short-lived subscription to warm the local query cache ahead of navigation.	Prewarming
PrewarmQueryOptions	interface	convex-angular	Options for injectPrewarmQuery(): injectRef, extendSubscriptionFor (default 5000ms), onError.	Prewarming
PrewarmQueryResult	interface	convex-angular	The object injectPrewarmQuery() returns; carries only prewarm.	Prewarming
PrewarmQueryReference	type	convex-angular	FunctionReference<'query'>, as accepted by injectPrewarmQuery().	Prewarming

Mutations & actions

Symbol	Kind	Entry point	Description	Reference
injectMutation	function	convex-angular	Creates a reactive mutation caller: a mutate() method plus Signals describing the latest call.	injectMutation
MutationOptions	interface	convex-angular	Options for injectMutation(): injectRef, onSuccess, onError, optimisticUpdate.	Optimistic updates
MutationResult	interface	convex-angular	The object injectMutation() returns: mutate, data, error, isLoading, isSuccess, status, reset.	injectMutation
MutationReference	type	convex-angular	FunctionReference<'mutation'>.	injectMutation
injectAction	function	convex-angular	Creates a reactive action caller: a run() method plus Signals describing the latest call.	injectAction
ActionOptions	interface	convex-angular	Options for injectAction(): injectRef, onSuccess, onError. Actions have no optimistic updates.	injectAction
ActionResult	interface	convex-angular	The object injectAction() returns: run, data, error, isLoading, isSuccess, status, reset.	injectAction
ActionReference	type	convex-angular	FunctionReference<'action'>.	injectAction

Auth

Symbol	Kind	Entry point	Description	Reference
injectAuth	function	convex-angular	Returns the reactive Convex auth state registered by provideConvexAuth() or a provider-specific helper.	Auth overview
InjectAuthOptions	interface	convex-angular	Options for injectAuth(); carries only injectRef.	Injection context
provideConvexAuth	function	convex-angular	Wires a CONVEX_AUTH provider into the Convex client’s auth sync. Root-only; call it exactly once.	Custom auth provider
provideConvexAuthFromExisting	function	convex-angular	Registers an existing injectable service as CONVEX_AUTH and calls provideConvexAuth() in one step.	Custom auth provider
CONVEX_AUTH	InjectionToken	convex-angular	The token a ConvexAuthProvider implementation is registered under.	Custom auth provider
ConvexAuthProvider	interface	convex-angular	The contract a custom auth provider implements: isLoading, isAuthenticated, fetchAccessToken, optional reauthVersion and error.	Custom auth provider
ConvexAuthState	interface	convex-angular	What injectAuth() returns: isLoading, isAuthenticated, isRefreshing, error, status, and the getAuth() snapshot.	Auth overview
ConvexAuthStatus	type	convex-angular	'loading', 'authenticated', 'refreshing', or 'unauthenticated'.	Status and state
AuthTokenFetcher	type	convex-angular	The async token-fetching function signature, called with { forceRefreshToken }.	Custom auth provider

Auth integrations

Symbol	Kind	Entry point	Description	Reference
provideClerkAuth	function	convex-angular	Bridges a CLERK_AUTH service into Convex auth. Includes provideConvexAuth() — do not register that separately.	Clerk
CLERK_AUTH	InjectionToken	convex-angular	The token your ClerkAuthProvider implementation is registered under.	Clerk
ClerkAuthProvider	interface	convex-angular	The Clerk-shaped contract: isLoaded, isSignedIn, getToken, optional sessionId, orgId, orgRole, sessionAudience, error.	Clerk
provideAuth0Auth	function	convex-angular	Bridges an AUTH0_AUTH service into Convex auth. Includes provideConvexAuth().	Auth0
AUTH0_AUTH	InjectionToken	convex-angular	The token your Auth0AuthProvider implementation is registered under.	Auth0
Auth0AuthProvider	interface	convex-angular	The Auth0-shaped contract: isLoading, isAuthenticated, getAccessTokenSilently, optional error.	Auth0

Directives

All four are standalone structural directives driven by injectAuth().

Symbol	Kind	Entry point	Description	Reference
CvaAuthenticatedDirective	directive	convex-angular	*cvaAuthenticated — renders while the user is authenticated and auth is not loading.	Auth directives
CvaUnauthenticatedDirective	directive	convex-angular	*cvaUnauthenticated — renders while the user is not authenticated and auth is not loading.	Auth directives
CvaAuthLoadingDirective	directive	convex-angular	*cvaAuthLoading — renders while auth state is still being determined.	Auth directives
CvaAuthRefreshingDirective	directive	convex-angular	*cvaAuthRefreshing — renders while Convex is replacing a server-rejected token. The user stays authenticated throughout.	Auth directives

Guards

Symbol	Kind	Entry point	Description	Reference
convexAuthGuard	const	convex-angular	A ready-made CanActivateFn & CanMatchFn requiring authentication, redirecting to the login route with a returnUrl.	Route guards
convexUnauthGuard	const	convex-angular	A CanActivateFn & CanMatchFn for signed-out-only routes; redirects authenticated users to authenticatedRoute.	Route guards
createConvexAuthGuard	function	convex-angular	Builds a guard with an optional claims-based allow check for role- or permission-gated routes.	Route guards
ConvexAuthGuardOptions	interface	convex-angular	Options for createConvexAuthGuard(): allow, forbiddenRoute, loginRoute.	Route guards
CONVEX_AUTH_GUARD_CONFIG	InjectionToken	convex-angular	Application-wide guard configuration token.	Route guards
ConvexAuthGuardConfig	interface	convex-angular	The config shape: loginRoute (default '/login') and authenticatedRoute (default '/').	Route guards

Resolvers

Symbol	Kind	Entry point	Description	Reference
convexQueryResolver	function	convex-angular	Builds an Angular ResolveFn that blocks navigation until a query’s first result is available locally, so the routed component renders without a loading state.	Route resolver
ConvexQueryResolverOptions	interface	convex-angular	Options for convexQueryResolver(): keepSubscribedFor (default 5000ms).	Route resolver

Optimistic-update helpers

These operate on the OptimisticLocalStore handed to a mutation’s optimisticUpdate, and understand Convex’s cursor-pagination page layout.

Symbol	Kind	Entry point	Description	Reference
optimisticallyUpdateValueInPaginatedQuery	function	convex-angular	Applies an update function to every matching item across all locally cached pages of a paginated query.	Paginated optimistic updates
insertAtTop	function	convex-angular	Prepends an item to the first page (the page whose cursor is null).	Paginated optimistic updates
insertAtBottomIfLoaded	function	convex-angular	Appends an item to the final page, but only when that page is already loaded.	Paginated optimistic updates
insertAtPosition	function	convex-angular	Inserts an item into the correct page and offset using the same sort key and order as the server query.	Paginated optimistic updates
sortByField	function	convex-angular	Builds a sortKeyFromItem callback from one or more item fields, for use with insertAtPosition.	Paginated optimistic updates

Types & utilities

Symbol	Kind	Entry point	Description	Reference
QueryStatus	type	convex-angular	'pending', 'success', 'error', or 'skipped'.	Status and state
PaginatedQueryStatus	type	convex-angular	The same four states, for a paginated query’s first page.	Status and state
MutationStatus	type	convex-angular	'idle', 'pending', 'success', or 'error'.	Status and state
ActionStatus	type	convex-angular	'idle', 'pending', 'success', or 'error'.	Status and state
ConvexError	class	convex-angular	Re-exported from convex/values so err instanceof ConvexError narrowing (and reading err.data) works without importing from Convex directly.	Error handling

Testing

Symbol	Kind	Entry point	Description	Reference
MockConvexClient	class	convex-angular/testing	In-memory stand-in for ConvexClient. Captures every subscription and invocation so a test can emit results, settle calls, seed the warm cache, and push connection states.	MockConvexClient
provideConvexTesting	function	convex-angular/testing	Registers a MockConvexClient under the CONVEX token for a TestBed. Creates a fresh mock when no instance is passed.	Testing overview
MockConvexClientOptions	interface	convex-angular/testing	Options for the mock; disabled mirrors a server-side-rendering client.	MockConvexClient
MockQuerySubscription	interface	convex-angular/testing	A captured live-query subscription, with emit, emitError, and unsubscribed.	Driving state
MockPaginatedSubscription	interface	convex-angular/testing	A captured paginated subscription; emit takes the client-shaped { results, status, loadMore }.	Driving state
MockCallableCall	interface	convex-angular/testing	A captured mutation or action invocation, settled with resolve or reject.	Driving state

Better Auth

Symbol	Kind	Entry point	Description	Reference
provideBetterAuth	function	convex-angular/better-auth	Takes a factory returning your Better Auth client and wires session tracking, Convex token exchange, and auth sync. Includes provideConvexAuth().	Better Auth
injectBetterAuth	function	convex-angular/better-auth	Returns the Better Auth session state registered by provideBetterAuth().	Better Auth
InjectBetterAuthOptions	interface	convex-angular/better-auth	Options for injectBetterAuth(); carries only injectRef.	Injection context
BetterAuthState	interface	convex-angular/better-auth	What injectBetterAuth() returns: session, isLoading, isAuthenticated, error, refreshSession(), clearSession().	Better Auth
BetterAuthClientLike	interface	convex-angular/better-auth	The minimal structurally-typed client surface the integration needs: getSession, convex.token, and the optional cross-domain extras.	Better Auth
BetterAuthSessionData	interface	convex-angular/better-auth	The session snapshot shape: a session with id, and a user with id plus arbitrary extra fields.	Better Auth
BetterAuthFetchResult	interface	convex-angular/better-auth	Better Auth’s { data, error } fetch envelope.	Better Auth

Where to go next

New to the library? Start with the introduction and providers. If a helper is throwing at runtime, the error message catalogue explains every error the library raises. The cross-cutting behavior shared by all helpers is documented under reactivity, injection context, and error handling; server-side rendering has its own overview, authenticated SSR, and hydration semantics pages.