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 surface 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/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`, and `createBetterConvexTestAuth`

The test entries run only in tests. better-auth/test refuses to run 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`, `useConvexPaginatedQuery`, `useConvexMutation`, `useConvexAction`, `useConvexForm`, `useConvexOperation`, `useConvexFileUpload`, `useConvexConnectionState`, `useConvex`, `ConvexCallError`, and `ConvexFormError`
`@lupinum/better-convex-vue/errors`	`ConvexCallError`, `ConvexFormError`, `isConvexCallError`, `normalizeConvexError`, and `isSerializedConvexCallError`
`@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.

MCP package

Import	Contents
`@lupinum/better-convex-mcp`	`handleMcpRequest`, `registerMcpTool`, `defineMcpTool`, `runMcpTool`, `projectMcpToolError`, `McpUnsupportedCapabilityError`, and the verifier types
`@lupinum/better-convex-mcp/test`	`listMcpCatalog`, which returns the tools and resources that a client sees, for snapshot tests

The MCP package does not depend on Nuxt or Better Auth. It does not turn Convex functions into tools by itself, and it does not 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/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. Code in convex/ imports ./_generated/api directly.

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.

Auto-imports

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

In Nitro code, it auto-imports serverConvex, getConvexUser, requireConvexUser, and toConvexH3Error.

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, UseConvexOperationReturn, ConvexOperation, UseConvexFileUploadReturn, ConvexFileUploadResult, UseConvexConnectionStateReturn, UseConvexAuthReturn, NuxtConvexQuery, and NuxtConvexPaginatedQuery;
Nuxt query options: UseNuxtConvexQueryOptions and UseNuxtConvexPaginatedQueryOptions, which add server and lazy to the Vue options;
other options: ModuleOptions, ConvexAuthOptions, UseConvexMutationOptions, UseConvexFileUploadOptions, UploadComplete, ConvexOperationWork, ConvexOperationUploadOptions, and OptimisticUpdate;
argument and item helpers: UseConvexQueryParameters, ConvexQueryArgs, PaginatedQueryArgs, PaginatedQueryItem, UploadUrlMutation, and UploadCompleteContext;
state values: ConvexCallStatus, ConvexAuthMode, ConvexAuthStatus, ConvexQueryBlockedBy ('skip' | 'auth' | 'manual' | 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.