Skip to main content

Package exports

Every import path of the three packages, the Nuxt aliases, and what the module auto-imports.

Import only from the paths on this page. Do not import from dist, src/runtime, or the .nuxt folder. The API reference page lists every exported name.

Nuxt package

ImportUse it inContents
@lupinum/better-convex-nuxtnuxt.config.tsThe Nuxt module and the public types
@lupinum/better-convex-nuxt/serverNitroserverConvex, getConvexUser, requireConvexUser, toConvexH3Error, and ServerConvexValidationError
@lupinum/better-convex-nuxt/errorsAnywhereConvexCallError, ConvexFormError, isConvexCallError, normalizeConvexError, and isSerializedConvexCallError
@lupinum/better-convex-nuxt/experimentalNuxt componentsinsertAtTop, optimisticallyUpdateValueInPaginatedQuery, useConvexOperation, UseConvexOperationReturn, and ConvexOperationWork
@lupinum/better-convex-nuxt/better-auth/serverconvex/createBetterConvexAuth and the other Convex auth helpers
@lupinum/better-convex-nuxt/better-auth/clientThe convex.auth.client filedefineConvexAuthClient, to add Better Auth client plugins
@lupinum/better-convex-nuxt/better-auth/convex.configconvex/convex.config.tsThe Better Auth Convex component. Mount it with app.use(betterAuth).
@lupinum/better-convex-nuxt/better-auth/_generated/component.jsTypes onlyComponentApi, the type of components.betterAuth
@lupinum/better-convex-nuxt/testComponent testssetupBetterConvexTest and invalidCursorError: the Vue test runtime plus a useConvexAuth() double
@lupinum/better-convex-nuxt/better-auth/testconvex-test testsregister, signInAs, grantMcp, and createBetterConvexTestAuth

The test entries run only in tests. createBetterConvexTestAuth refuses to run outside a test runner (VITEST set or NODE_ENV=test) or unless SITE_URL and CONVEX_SITE_URL are local (localhost, 127.0.0.1, or [::1]). See component testing.

Vue package

ImportContents
@lupinum/better-convex-vuecreateBetterConvex, useConvexQuery, preloadConvexQuery, useConvexPaginatedQuery, useConvexMutation, useConvexAction, useConvexForm, useConvexFileUpload, useConvexConnectionState, useConvex, ConvexCallError, and ConvexFormError
@lupinum/better-convex-vue/errorsConvexCallError, ConvexFormError, isConvexCallError, normalizeConvexError, and isSerializedConvexCallError
@lupinum/better-convex-vue/experimentalinsertAtTop, optimisticallyUpdateValueInPaginatedQuery, useConvexOperation, UseConvexOperationReturn, and ConvexOperationWork
@lupinum/better-convex-vue/embeddedcreateBetterConvexAttachment and the BetterConvexAttachment type, for a Vue application that runs inside another application and shares its Convex connection
@lupinum/better-convex-vue/testsetupBetterConvexTest and invalidCursorError: a component-test runtime that runs the real composables against an in-memory Convex connection. Use it only in tests.

@lupinum/better-convex-vue/internal exists only for the Nuxt package. It is not public API and can change in any release.

Functions package

ImportContents
@lupinum/better-convex-functionsdefineFunctions, definePolicy, can, consentScopes, the row rules (tenant, owner, publicRead, anyOf, allOf, custom, unchecked), libraryTables, docValidator, trusted, fail and oneLine
@lupinum/better-convex-functions/policydefinePolicy, can, consentScopes and the policy types, without server code: for the browser and for convex/policy.ts
@lupinum/better-convex-functions/testunguardedFunctions and countDocuments, for tests

@lupinum/better-convex-functions/internal exists only for the agents package and the in-app agent runtime. It is not public API, is not covered by semver, and can change in any release.

Agents package

ImportContents
@lupinum/better-convex-agentsdefineTools: tools, approvals, the activity feed and housekeeping from the operations of @lupinum/better-convex-functions
@lupinum/better-convex-agents/mcpcreateMcpServer, handleMcpRequest, listMcpCatalog (snapshot tests), projectMcpToolError, McpUnsupportedCapabilityError, and the verifier types
@lupinum/better-convex-agents/testcallTool: calls a tool in convex-test as the MCP door does; loads without the MCP SDK

@lupinum/better-convex-agents/internal exists only for the in-app agent runtime: toolFailure and the helpers that move an agent run between its states. It is not public API, is not covered by semver, and can change in any release.

The agents package does not depend on Nuxt or Better Auth. It turns only operations with a tool field into tools, and the operation's policy and row rules decide what a user may do. The Better Auth parts of MCP are in @lupinum/better-convex-nuxt/better-auth/server: the oauth.mcp option, auth.createMcpAccessVerifier, auth.requireMcpPrincipal, auth.oauthConnections, auth.oauthOperator, and mcpPrincipalValidator. See MCP on Convex.

Agent documentation

Each package also exports ./agent-docs, for example @lupinum/better-convex-nuxt/agent-docs. It is a Markdown file for coding agents. It lists the documentation pages that are packed with the installed version. See choose your path.

Nuxt aliases

AliasPoints to
#convex/apiYour convex/_generated/api
#convex/dataModelYour convex/_generated/dataModel. Types only.
#convex/server@lupinum/better-convex-nuxt/server
#convex/auth-clientThe file in convex.auth.client. Only in builds with auth.

Use #convex/api in components, composables, middleware, and Nitro routes, and import type from #convex/dataModel there for Id and Doc. Code in convex/ imports the generated files by a path relative to the file: ./_generated/api and ./_generated/dataModel in convex/, ../_generated/dataModel in convex/lib/.

Before Convex creates convex/_generated/api, #convex/api points to a placeholder. Reading a function from it throws an error that tells you to run Convex codegen. #convex/dataModel has no placeholder: until Convex creates convex/_generated/dataModel, importing from it fails type-checking.

Auto-imports

In application code, the module auto-imports useConvex, useConvexQuery, useConvexPaginatedQuery, useConvexMutation, useConvexAction, useConvexForm, useConvexFileUpload, useConvexConnectionState, useConvexConfig, useConvexAttachment, and useConvexActivation.

In server code, it auto-imports serverConvex, getConvexUser, requireConvexUser, and toConvexH3Error. Import everything else, such as defineEventHandler, from nuxt/server.

With convex.auth set, it also auto-imports useConvexAuth, useConvexAuthReturnTo, and normalizeLocalRedirectPath, and it adds the auth route middleware. Without convex.auth, none of these exist, getConvexUser returns null, and requireConvexUser throws a 401 error.

The module registers no components.

Root types

@lupinum/better-convex-nuxt exports only types besides the module:

  • return types: UseConvexQueryState, UseConvexPaginatedQueryState, UseConvexMutationReturn, UseConvexActionReturn, UseConvexFormReturn, ConvexOperation, UseConvexFileUploadReturn, ConvexFileUploadResult, UseConvexConnectionStateReturn, UseConvexAuthReturn, ConvexQuery, and ConvexPaginatedQuery;
  • Nuxt query options: UseNuxtConvexQueryOptions and UseNuxtConvexPaginatedQueryOptions, which add server and lazy to the Vue options;
  • other options: ModuleOptions, ConvexAuthOptions, UseConvexMutationOptions, UseConvexFileUploadOptions, UploadComplete, ConvexOperationUploadOptions, and OptimisticUpdate;
  • argument and item helpers: UseConvexQueryParameters, ConvexQueryArgs, PaginatedQueryArgs, PaginatedQueryItem, UploadUrlMutation, and UploadCompleteContext;
  • state values: ConvexCallStatus, ConvexAuthMode, ConvexAuthStatus, ConvexQueryBlockedBy ('skip' | 'auth' | 'manual' | 'server' | null), and UploadProgressInfo;
  • data shapes: ConvexUser, ConvexRuntimeConfig, ConvexClientHandle, ConvexCallError, ConvexCallErrorCode, ConvexCallOutcome, ConvexUploadPhase, ConvexFormError, ConvexFormErrorKind, ConvexFormErrorMapping, ConvexFormIssue, and ConvexFormSubmitResult.

Types that the Vue package also exports have the same meaning in both packages. UseConvexQueryOptions and UseConvexPaginatedQueryOptions are the Vue option types. Import them from @lupinum/better-convex-vue. To type Nuxt query parameters, pass UseNuxtConvexQueryOptions as the second type argument of UseConvexQueryParameters.