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
| Import | Use it in | Contents |
|---|---|---|
@lupinum/better-convex-nuxt | nuxt.config.ts | The Nuxt module and the public types |
@lupinum/better-convex-nuxt/server | Nitro | serverConvex, getConvexUser, requireConvexUser, toConvexH3Error, and ServerConvexValidationError |
@lupinum/better-convex-nuxt/errors | Anywhere | ConvexCallError, ConvexFormError, isConvexCallError, normalizeConvexError, and isSerializedConvexCallError |
@lupinum/better-convex-nuxt/experimental | Nuxt components | insertAtTop, optimisticallyUpdateValueInPaginatedQuery, useConvexOperation, UseConvexOperationReturn, and ConvexOperationWork |
@lupinum/better-convex-nuxt/better-auth/server | convex/ | createBetterConvexAuth and the other Convex auth helpers |
@lupinum/better-convex-nuxt/better-auth/client | The convex.auth.client file | defineConvexAuthClient, to add Better Auth client plugins |
@lupinum/better-convex-nuxt/better-auth/convex.config | convex/convex.config.ts | The Better Auth Convex component. Mount it with app.use(betterAuth). |
@lupinum/better-convex-nuxt/better-auth/_generated/component.js | Types only | ComponentApi, the type of components.betterAuth |
@lupinum/better-convex-nuxt/test | Component tests | setupBetterConvexTest and invalidCursorError: the Vue test runtime plus a useConvexAuth() double |
@lupinum/better-convex-nuxt/better-auth/test | convex-test tests | register, 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
| Import | Contents |
|---|---|
@lupinum/better-convex-vue | createBetterConvex, useConvexQuery, preloadConvexQuery, useConvexPaginatedQuery, useConvexMutation, useConvexAction, useConvexForm, useConvexFileUpload, useConvexConnectionState, useConvex, ConvexCallError, and ConvexFormError |
@lupinum/better-convex-vue/errors | ConvexCallError, ConvexFormError, isConvexCallError, normalizeConvexError, and isSerializedConvexCallError |
@lupinum/better-convex-vue/experimental | insertAtTop, optimisticallyUpdateValueInPaginatedQuery, useConvexOperation, UseConvexOperationReturn, and ConvexOperationWork |
@lupinum/better-convex-vue/embedded | createBetterConvexAttachment and the BetterConvexAttachment type, for a Vue application that runs inside another application and shares its Convex connection |
@lupinum/better-convex-vue/test | setupBetterConvexTest 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
| Import | Contents |
|---|---|
@lupinum/better-convex-functions | defineFunctions, definePolicy, can, consentScopes, the row rules (tenant, owner, publicRead, anyOf, allOf, custom, unchecked), libraryTables, docValidator, trusted, fail and oneLine |
@lupinum/better-convex-functions/policy | definePolicy, can, consentScopes and the policy types, without server code: for the browser and for convex/policy.ts |
@lupinum/better-convex-functions/test | unguardedFunctions 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
| Import | Contents |
|---|---|
@lupinum/better-convex-agents | defineTools: tools, approvals, the activity feed and housekeeping from the operations of @lupinum/better-convex-functions |
@lupinum/better-convex-agents/mcp | createMcpServer, handleMcpRequest, listMcpCatalog (snapshot tests), projectMcpToolError, McpUnsupportedCapabilityError, and the verifier types |
@lupinum/better-convex-agents/test | callTool: 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
| Alias | Points to |
|---|---|
#convex/api | Your convex/_generated/api |
#convex/dataModel | Your convex/_generated/dataModel. Types only. |
#convex/server | @lupinum/better-convex-nuxt/server |
#convex/auth-client | The 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, andConvexPaginatedQuery; - Nuxt query options:
UseNuxtConvexQueryOptionsandUseNuxtConvexPaginatedQueryOptions, which addserverandlazyto the Vue options; - other options:
ModuleOptions,ConvexAuthOptions,UseConvexMutationOptions,UseConvexFileUploadOptions,UploadComplete,ConvexOperationUploadOptions, andOptimisticUpdate; - argument and item helpers:
UseConvexQueryParameters,ConvexQueryArgs,PaginatedQueryArgs,PaginatedQueryItem,UploadUrlMutation, andUploadCompleteContext; - state values:
ConvexCallStatus,ConvexAuthMode,ConvexAuthStatus,ConvexQueryBlockedBy('skip' | 'auth' | 'manual' | 'server' | null), andUploadProgressInfo; - data shapes:
ConvexUser,ConvexRuntimeConfig,ConvexClientHandle,ConvexCallError,ConvexCallErrorCode,ConvexCallOutcome,ConvexUploadPhase,ConvexFormError,ConvexFormErrorKind,ConvexFormErrorMapping,ConvexFormIssue, andConvexFormSubmitResult.
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.