Upgrade to 1.0
Move an application from Better Convex Nuxt 1.0.0-beta.7 and Better Convex MCP 1.0.0-beta.2 to 1.0.
This page lists every breaking change between @lupinum/better-convex-nuxt
1.0.0-beta.7, @lupinum/better-convex-mcp 1.0.0-beta.2, and 1.0. Each
change shows the old code and the new code. 1.0 has no compatibility layer:
the old names are gone, and TypeScript reports each place that you must
change.
Work through the sections in order. Then run your type check, your Convex tests, and a sign-in in the browser.
Already on 1.0.0-rc.1?
You need only these changes:
- The command is
better-convex-nuxt, notbetter-convex, andinitisauth init. Replacebetter-convex convexwithbetter-convex-nuxt convexandbetter-convex initwithbetter-convex-nuxt auth initin yourpackage.jsonscripts and CI.better-convex-nuxt devruns Convex and Nuxt together. See Command line. useConvexAuth().statusreports'pending'instead of'loading', andpendingfollowsstatus. See section 13.upload(file, args, { context })becomesupload(file, { args, context }). See section 12.- Delete query
refresh()calls. See section 9. - The paginated query's
reset()is nowrestart(). See section 10. - Import
useConvexOperationfrom@lupinum/better-convex-nuxt/experimental(or@lupinum/better-convex-vue/experimental). Nuxt no longer auto-imports it. See Experimental APIs. - A Nuxt
convex.auth.originthat differs from the ConvexSITE_URLnow fails auth requests unlesssiteOriginslists it, andBETTER_AUTH_TRUSTED_ORIGINSis rejected. WithoauthoroauthProvider, set both to the same origin. See section 7. - In component tests, a mutation that passes
optimisticUpdatenow fails. See section 16. - With a local auth component, regenerate its schema and export
pruneRateLimitsfrom the component adapter. See section 4. - With a local auth component, export
expireVerificationfrom the component adapter. The schema does not change. See section 4. Expired email codes are now deleted by a scheduled function. A deployment where code sign-in fails withAUTH_BULK_OPERATION_LIMIT_EXCEEDEDsigns in again after the upgrade, and its old expired rows are deleted without manual work. - Auth defaults: see Password sign-in is off unless you name it.
- MCP:
@lupinum/better-convex-mcpis now@lupinum/better-convex-agents, with@lupinum/better-convex-functionsas a required peer at the same version.runMcpToolistools.runTool(name, operation).auth.mcpis removed: spreadauth.mcpAuthorization(ctx)into thehandleMcpRequestoptions. Install@modelcontextprotocol/server@2.3.1(rc.1 used2.1.0), and for MCP Apps@modelcontextprotocol/client@2.3.1and@modelcontextprotocol/core@2.3.1. See section 15. - Nuxt 4.6 or newer, and server imports from
nuxt/server: see Nuxt 4.6 and server imports.
Password sign-in is off unless you name it
The auth factory now turns on no sign-in method by itself. Pass
emailAndPassword: {} to keep password sign-in. Add
requireEmailVerification: false to keep sign-in before verification. Add an
email hook before you deploy: a deployment that sends auth mail without it
fails to load. An app that decides access by email should use email codes
(emailOTP). See Sign in and sign out.
Migration: pass emailAndPassword: {} to keep password sign-in (add requireEmailVerification: false to keep sign-in before verification), add an email hook before deploying, and apps that decide access by email should use email codes.
Nuxt 4.6 and server imports
The Nuxt package needs Nuxt ^4.6.0 || ^5.0.0-0 and Node.js
^22.22.3 || ^24.15.0 || >=26.0.0. It is tested on Nuxt 4.6.4 and on the
Nuxt 5 nightly. Nuxt 5 is a pre-release until it ships. The package no longer
depends on h3.
- Import
defineEventHandler,createError,readBody,readValidatedBody,getRequestHeader, anduseRuntimeConfigfromnuxt/server. Nuxt 5 does not import them automatically. CalluseRuntimeConfig()without an event. - Set response headers with
event.res.headers.set()instead ofsetHeader(). toConvexH3Errorreturns, andrequireConvexUserandgetConvexUserthrow, an HTTP error (NuxtError). Check it withisNuxtError(error)fromnuxt/serverand readerror.status, notstatusCode.- The server helpers take
event: ConvexServerEvent. Type your own helper functions withConvexServerEventfrom@lupinum/better-convex-nuxt/server, or let TypeScript infer the type. - The server helpers read the server's runtime config, not a per-request copy. On Nuxt 4 with runtime config that changes per request (for example Cloudflare module workers), set the Convex config at build or boot time.
import { defineEventHandler } from 'nuxt/server'
import { requireConvexUser } from '#convex/server'
export default defineEventHandler(async (event) => {
const user = await requireConvexUser(event)
event.res.headers.set('cache-control', 'private, no-store')
return { id: user.id }
})1. Update the packages
Install 1.0:
pnpm add @lupinum/better-convex-nuxtA plain Vue application installs @lupinum/better-convex-vue
instead. An application with MCP replaces @lupinum/better-convex-mcp with
@lupinum/better-convex-agents, which needs @lupinum/better-convex-functions
next to it, and imports the transport from @lupinum/better-convex-agents/mcp.
defineMcpTool, registerMcpTool and runMcpTool are removed: register tools
with server.registerTool and run them through tools.runTool, or derive them
from operations with defineTools. MIGRATING.md has the steps:
pnpm add @lupinum/better-convex-agents @lupinum/better-convex-functions @modelcontextprotocol/server@2.3.1Better Auth moves from 1.7.2 to 1.7.16. Every application with auth
installs all three Better Auth packages, including the OAuth provider, even
without MCP:
pnpm add better-auth@1.7.16 @better-auth/core@1.7.16 @better-auth/oauth-provider@1.7.16The MCP transport now uses @modelcontextprotocol/server 2.3.1
(before: 2.0.0; 1.0.0-rc.1 used 2.1.0). Install that exact version next to it, so the application
resolves one copy. For MCP Apps, use @modelcontextprotocol/ext-apps 2.x.
2. Check the auth component data
Deploy 1.0 with your normal deploy command. Convex checks every stored auth row against the new component schema, and the beta rows pass: you do not export, import, or clear any auth table.
If your application uses MCP or the Better Auth OAuth provider, beta refresh
tokens stop working. 1.0 binds every refresh token to the consent that issued
it. Beta refresh tokens have no such binding, so 1.0 answers a refresh with
one with invalid_grant and issues no new token. Connected MCP hosts and
other OAuth clients sign in again, and then receive a bound token. The beta
rows stay in the oauthRefreshToken table, but 1.0 never accepts them. You
do not need to delete them.
1.0 identifies an auth account by its provider and the provider's account ID
(providerId and accountId). The beta releases used issuer and
accountId. Your existing account rows keep working:
- Beta rows keep their
issuervalue in an optional column. Better Convex never reads or writes it. - Users, account IDs, passwords, and linked sign-in providers stay the same. You do not need a new auth component, and users do not sign up again.
If you use a local auth component, regenerate its schema:
pnpm exec better-convex-nuxt auth schema \
--config convex/betterAuth/schemaOptions.ts \
--output convex/betterAuthAfter you deploy 1.0, check for accounts that now share one key. Add this internal action:
import { findAccountKeyCollisions } from '@lupinum/better-convex-nuxt/better-auth/server'
import { v } from 'convex/values'
import { components } from './_generated/api'
import { internalAction } from './_generated/server'
export const checkAccountKeys = internalAction({
args: { cursor: v.optional(v.union(v.string(), v.null())) },
handler: (ctx, { cursor }) => findAccountKeyCollisions(ctx, components.betterAuth, { cursor }),
})Run it:
pnpm exec better-convex-nuxt convex run authUpgrade:checkAccountKeys '{}'The result lists each group of accounts with the same providerId and
accountId. One run reads at most 10,000 accounts. When the result has
isDone: false, run it again and pass the returned continueCursor:
pnpm exec better-convex-nuxt convex run authUpgrade:checkAccountKeys '{"cursor":"<continueCursor>"}'When isDone is true and no run reported a collision, you are done. You can
then delete the file.
A collision is possible only when one provider stored the same user under two
issuers during the beta. This can happen with Microsoft Entra ID, Cognito,
Paybin, genericOAuth providers (including the Keycloak, Okta, and Auth0
helpers), or a custom provider, when the issuer changed. It cannot happen for
email and password, Google, Apple, Facebook, LINE, or providers without their
own issuer, such as GitHub or Discord.
Better Auth does not sign in a user whose account key has more than one row. Other users are not affected. For each reported group, merge the rows into one or delete the extra rows. Then that user can sign in again.
This upgrade path is tested on a real local Convex backend. The repository
suite pnpm test:integration deploys the 1.0.0-beta.7 auth component
with beta users, accounts, sessions, and OAuth rows, then pushes 1.0 over it.
It checks that user IDs stay the same, that password sign-in and account
lookups work, that beta refresh tokens are rejected, and that
findAccountKeyCollisions finds a planted collision and nothing else.
3. Removed features
| Removed | Use instead |
|---|---|
workforce: true and createWorkforceAuthSchemaOptions | The twoFactor option. See Better Auth plugin support. |
Workforce session functions (workforceSessions.*) | Better Auth session endpoints through useConvexAuth().client |
@lupinum/better-convex-mcp/vue and useMcpApp | The App class from @modelcontextprotocol/ext-apps. See MCP Apps. |
oauthPopupClient() in defineConvexAuthClient | client.signIn.social(). The server never supported popup sign-in. |
verifyOAuthBearerToken | auth.createMcpAccessVerifier(ctx) |
The beta.3 user migration (migrateBeta3UserGeneration) | Nothing. Finish that migration on a beta release before you upgrade. |
convexAuth, createAuthComponent, createConvexAuthRateLimitStorage, requireWritableAuthCtx | createBetterConvexAuth |
auth.authComponent | The helpers on auth itself (section 5 below) |
Types UseConvexCall, UploadStatus | UseConvexMutationReturn, UseConvexActionReturn, ConvexCallStatus |
Types UseConvexQueryOptions, UseConvexPaginatedQueryOptions | UseNuxtConvexQueryOptions, UseNuxtConvexPaginatedQueryOptions |
4. Update the local auth component exports
If you have convex/betterAuth/adapter.ts, export exactly these functions:
import { defineAuthAdapterFunctions } from '@lupinum/better-convex-nuxt/better-auth/server'
import schema from './schema'
import schemaMetadata from './schemaMetadata'
export const {
consumeOne,
consumeRateLimit,
count,
create,
deleteMany,
deleteOne,
expireSession,
expireVerification,
findMany,
findOne,
incrementOne,
oauthLiveAccess,
pruneRateLimits,
pruneSigningKeys,
rotateSigningKey,
sessionAdmission,
updateMany,
updateOne,
} = defineAuthAdapterFunctions({ metadata: schemaMetadata, schema })assertProfile and the five workforce functions are gone. expireSession,
expireVerification, oauthLiveAccess, pruneRateLimits, and
pruneSigningKeys are new. The component schedules expireSession and
expireVerification itself, so a missing export breaks sign-in.
In convex/auth.ts, also export pruneSigningKeys, and schedule it, for
example as a daily cron:
// Before
export const { ensureSigningKey, rotateSigningKey } = auth.jwksOperatorFunctions()
// After
export const { ensureSigningKey, pruneSigningKeys, rotateSigningKey } = auth.jwksOperatorFunctions()5. Read the signed-in user in Convex
The user helpers moved from auth.authComponent to auth. requireUser
throws a ConvexError with code UNAUTHENTICATED instead of the string
'Unauthenticated'.
// Before
export const { authComponent } = auth
const user = await authComponent.safeGetAuthUser(ctx)
const required = await authComponent.getAuthUser(ctx)
const { auth: betterAuth, headers } = await authComponent.getAuth(createAuth, ctx)
// After
const user = await auth.getUser(ctx)
const required = await auth.requireUser(ctx)
const { auth: betterAuth, headers } = await auth.getAuth(ctx)For an HTTP action that must act as the signed-in user, use the new
auth.sessionHttpAction(handler). See
Backend authorization.
6. Send auth email through one hook
The per-feature email callbacks are replaced by one email hook. The
emailAndPassword, emailVerification, and emailOTP options no longer
accept a function of ctx; pass plain objects. Password reset is now off
until you set passwordReset: true.
// Before
export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
emailAndPassword: (ctx) => ({
requireEmailVerification: true,
sendResetPassword: async ({ user, url }) => {
await ctx.runMutation(internal.mail.send, { to: user.email, url })
},
}),
emailVerification: {
sendVerificationEmail: async ({ user, url }) => {
/* ... */
},
},
})
// After
export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
emailAndPassword: { requireEmailVerification: true, passwordReset: true },
emailVerification: { sendOnSignUp: true },
email: async (ctx, message) => {
switch (message.type) {
case 'verify-email':
case 'reset-password':
await ctx.runMutation(internal.mail.send, { to: message.to, url: message.url })
return
default:
throw new Error(`Unsupported auth email: ${message.type}`)
}
},
})sendResetPassword, sendVerificationEmail, sendVerificationOTP,
twoFactor.otpOptions.sendOTP, and organization.sendInvitationEmail now fail
with AUTH_CONFIG_INVALID. See
Transactional auth email
for every message type.
7. Check the session and account options
session now accepts expiresIn and updateAge with fixed limits, and a
limited cookieCache:
| Option | Default | Allowed |
|---|---|---|
expiresIn | 7 days | 1 hour to 30 days |
updateAge | 1 day | 5 minutes to expiresIn |
cookieCache.maxAge | 300 | 1 to 300 seconds; refreshCache is rejected |
account.accountLinking.trustedProviders now accepts only names of configured
social providers. Any other key under account fails. See
Social sign-in.
Better Auth now trusts only the Convex SITE_URL and the exact origins listed
in siteOrigins. A Nuxt convex.auth.origin that differs
from SITE_URL fails auth requests until you set both to the same origin or
list it in siteOrigins. With oauth or oauthProvider, siteOrigins is
rejected, so set both to the same origin. BETTER_AUTH_TRUSTED_ORIGINS is rejected, because
Better Auth would trust those origins next to the verified one. See
Several site origins.
Convex session tokens carry only the library claims. If you read name,
email, emailVerified, or image from useConvexAuth().user or
ctx.auth.getUserIdentity(), return them from defineSessionClaims, or use
auth.getUser(ctx) in Convex functions:
export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
defineSessionClaims: ({ user }) => ({ name: user.name, email: user.email }),
})8. Destructure mutations and actions
useConvexMutation and useConvexAction return an object instead of a
function with state attached. Destructure the verb: mutate for mutations,
run for actions.
// Before
const updateProject = useConvexMutation(api.projects.update)
await updateProject({ projectId, name })
const saving = updateProject.pending
const generate = useConvexAction(api.ai.generate)
await generate({ documentId })
// After
const { mutate: updateProject, pending: saving } = useConvexMutation(api.projects.update)
await updateProject({ projectId, name })
const { run: generate } = useConvexAction(api.ai.generate)
await generate({ documentId })Both now also return data, status, error, and reset(). When a
component reads several of them, keep the object and call the verb on it:
const updateProject = useConvexMutation(api.projects.update)
await updateProject.mutate({ projectId, name })
const saving = updateProject.pendingA second submit() of useConvexForm while one is pending now rejects with
code SUBMIT_IN_PROGRESS. Disable the submit button while pending is
true.
9. Delete query refresh() calls
useConvexQuery and useConvexPaginatedQuery no longer have refresh().
It did nothing: Convex answers a read of a subscribed query from its local
cache, and it already runs the query again when its data changes. Delete the
calls, including the ones after a mutation.
// Before
await createProject({ name })
await projects.refresh()
// After
await createProject({ name })A query error stays until its cause changes, for example new arguments or a
fixed deployment. Do not offer a retry button that calls the query again. If
the user needs a way out of a persistent error, reload the page with
reloadNuxtApp(). A failed later page is retried with loadMore().
10. Update pagination state
pageStatus and cursor are no longer public. status and pending
describe only the first page. Use isLoadingMore for later pages, and
isExhausted for the end of the list. loadMore() returns a promise, never
rejects, and does nothing while canLoadMore is false.
<!-- Before -->
<button v-if="canLoadMore" :disabled="pending" @click="loadMore(20)">Load more</button>
<p v-else-if="status === 'success'">No more items.</p>
<!-- After -->
<button v-if="canLoadMore || isLoadingMore" :disabled="!canLoadMore" @click="loadMore(20)">
{{ isLoadingMore ? 'Loading…' : 'Load more' }}
</button>
<p v-else-if="isExhausted">No more items.</p>A failed later page now keeps the loaded items and sets error. The next
loadMore() retries it. See Pagination.
reset() on a paginated query is now restart(), because it starts the list
again from the first page:
// Before
messages.reset()
// After
messages.restart()11. Update error handling
ConvexCallError.message of a server error is now the text that your Convex
function wrote: a string ConvexError data, or data.message. Before, it was
always Convex application error. Check that these messages are safe to show
to users.
Every error now has functionName. Errors raised by the library have a stable
code. Use isConvexCallError instead of reading data yourself:
import { isConvexCallError } from '@lupinum/better-convex-nuxt/errors'
// Before
catch (error) {
const normalized = normalizeConvexError(error)
if ((normalized.data as { code?: string } | undefined)?.code === 'PROJECT_ARCHIVED') showNotice()
}
// After
catch (error) {
if (isConvexCallError(error, 'PROJECT_ARCHIVED')) showNotice()
}The library codes include IDENTITY_CHANGED, CANCELLED, FILE_TOO_LARGE,
FILE_TYPE_NOT_ALLOWED, UPLOAD_IN_PROGRESS, SUBMIT_IN_PROGRESS,
UNAUTHENTICATED, CLIENT_UNAVAILABLE, NETWORK_ERROR, and TIMEOUT.
Error types lists every
code.
Browser errors also have outcome. 'not-sent' means that the request never
reached Convex. 'unknown' means that it was sent and its result did not
arrive, so it may have run. Before, IDENTITY_CHANGED always meant that the
write may have run. See Error types.
12. Update file uploads
Pass mutation arguments and context in one options object. Omit args when
the prepare mutation takes none:
// Before
await upload(file, { folder }, { context: documentId })
await upload(file, {}, { context: documentId })
// After
await upload(file, { args: { folder }, context: documentId })
await upload(file, { context: documentId })upload() now resolves with { storageId, prepared, completed } instead of
the storage ID. data holds the same object.
// Before
const storageId = await upload(file)
const uploadedId = data.value
// After
const { storageId } = await upload(file)
const uploadedId = data.value?.storageIdIf you save the file in a second mutation after the upload, move that
mutation into complete. It then runs for the same signed-in user, and
pending and error cover it:
// Before
const { upload } = useConvexFileUpload(api.files.generateUploadUrl)
const { mutate: attachFile } = useConvexMutation(api.documents.attachFile)
const storageId = await upload(file)
await attachFile({ documentId, storageId })
// After
const { upload } = useConvexFileUpload(api.files.generateUploadUrl, {
complete: (
op,
{ storageId, context: documentId }: UploadCompleteContext<string, Id<'documents'>>,
) => op.mutation(api.documents.attachFile, { documentId, storageId }),
})
await upload(file, { context: documentId })The target passed as context is captured when upload() is called, so a
later change to component state cannot attach the file to another record.
A prepare mutation can now return an object, such as an upload session. Pass
url to select the upload URL. See Upload files.
upload() failures now have codes, a phase, and an outcome. cancel()
makes the pending upload reject with CANCELLED; ignore that code when your
own cancel caused it. The new reset() clears data, error, and
progress.
try {
await upload(file)
} catch (error) {
if (isConvexCallError(error, 'CANCELLED')) return
throw error
}Plain Vue applications now import useConvexFileUpload from
@lupinum/better-convex-vue.
13. Remove the null check on the auth client
useConvexAuth().client is never null. During server rendering, its
methods throw a ConvexCallError with code CLIENT_UNAVAILABLE, so keep
calling them from event handlers or onMounted().
const { client } = useConvexAuth()
// Before
if (!client) return
await client.signOut()
// After
await client.signOut()Auth status and pending
useConvexAuth().status is 'pending' until the first auth result, instead of
'loading'. pending is now true exactly while status is 'pending', as
in every other composable. It no longer tells you that a sign-in is running:
keep your own ref around the call.
// Before
const { client, pending } = useConvexAuth()
// <button :disabled="pending">
// After
const { client } = useConvexAuth()
const signingIn = ref(false)
async function signIn() {
signingIn.value = true
try {
await client.signIn.email({ email: email.value, password: password.value })
} finally {
signingIn.value = false
}
}
// <button :disabled="signingIn">status now changes only after Convex accepts the session. A sign-in or user
switch keeps the previous value until then.
14. Render browser-only queries as idle during SSR
A query with server: false now renders status: 'idle' with
blockedBy: 'server' on the server, and keeps both during hydration. It
becomes pending with blockedBy: null when the browser starts it. Show your
loading state for both:
<Skeleton v-if="status === 'pending' || blockedBy === 'server'" />15. Update the MCP server
The MCP OAuth setup moves into the auth factory. The verifier now returns a
typed principal, and configureServer receives one object.
createBetterAuthMcpAccessVerifier, auth.validateOAuthAccess, and the
OAuthLiveAccess type are removed. Use auth.createMcpAccessVerifier(ctx) in
the HTTP action and auth.requireMcpPrincipal(ctx, principal, { scope }) in
the Convex function that the tool calls. There is no other public path.
Before, the options held a hand-written oauthProvider: { ... } profile.
Replace it with oauth.mcp:
import { createBetterConvexAuth } from '@lupinum/better-convex-nuxt/better-auth/server'
import { components } from './_generated/api'
import type { DataModel } from './_generated/dataModel'
export const auth = createBetterConvexAuth<DataModel>(components.betterAuth, {
oauth: {
mcp: {
scopes: { 'notes:read': 'Read your notes.' },
hosts: ['chatgpt', 'claude'],
},
},
})Before, the HTTP action built the verifier by hand:
handleMcpRequest(request, {
resource,
authorization: {
mode: 'oauth',
issuer,
verifier: createBetterAuthMcpAccessVerifier({
allowedScopes: MCP_SCOPES,
jwksUrl: `${issuer}/jwks`,
maxLifetimeSeconds: 600,
validateLiveAccess: (access) => authComponent.validateOAuthAccess(ctx, access),
}),
scopesSupported: MCP_SCOPES,
},
serverInfo,
configureServer(access, server) {
server.registerTool('list_notes', config, async () =>
runMcpTool(async () => ({
structuredContent: await ctx.runQuery(internal.notes.list, {
access: {
subject: access.subject,
clientId: access.clientId,
scopes: [...access.scopes],
},
}),
})),
)
},
})Now the auth factory provides the verifier and the addresses. The tool passes the typed principal to its internal function:
import { handleMcpRequest } from '@lupinum/better-convex-agents/mcp'
import { z } from 'zod'
import { internal } from './_generated/api'
import { httpAction } from './_generated/server'
import { auth } from './auth'
export const handleMcp = httpAction((ctx, request) =>
handleMcpRequest(request, {
serverInfo: { name: 'notes', version: '1.0.0' },
// The resource, issuer, scopes and token verifier of the `oauth.mcp` profile.
...auth.mcpAuthorization(ctx),
configureServer({ principal, server, tools }) {
server.registerTool(
'list_notes',
{
description: 'List your newest notes.',
inputSchema: z.object({}).strict(),
annotations: { readOnlyHint: true, openWorldHint: false },
scopeChallenge: tools.requireScopes('notes:read'),
},
() =>
tools.runTool('list_notes', async () => {
const notes = await ctx.runQuery(internal.notes.list, { principal })
return { content: [{ type: 'text', text: JSON.stringify({ notes }) }] }
}),
)
},
}),
)The MCP package is now @lupinum/better-convex-agents; import the transport
from its /mcp entry. runMcpTool is tools.runTool(name, operation) inside
configureServer. An application on @lupinum/better-convex-functions defines
its tools with defineTools instead; see MIGRATING.md.
In the internal function, replace the access argument with the principal
and check it live. Before, it declared
args: { access: v.object({ subject: v.string(), clientId: v.string(), scopes: v.array(v.string()) }) }.
import { mcpPrincipalValidator } from '@lupinum/better-convex-nuxt/better-auth/server'
import { internalQuery } from './_generated/server'
import { auth } from './auth'
export const list = internalQuery({
args: { principal: mcpPrincipalValidator },
handler: async (ctx, { principal }) => {
const { user } = await auth.requireMcpPrincipal(ctx, principal, { scope: 'notes:read' })
const notes = await ctx.db
.query('notes')
.withIndex('by_owner', (q) => q.eq('ownerId', user.id))
.order('desc')
.take(20)
return notes.map((note) => ({ id: note._id, title: note.title }))
},
})Other MCP changes:
- A custom
McpAccessVerifiercan returnprincipalnext toaccessandexpiresAt.handleMcpRequestpasses it toconfigureServer. - The verifier reads signing keys from the auth component. The
jwksUrloption is gone. runMcpToolistools.runTool(name, operation)insideconfigureServer. Set the annotations andscopeChallenge: tools.requireScopes(...)in the tool config.- Add error codes that the model may see to
exposeErrorCodes. - Requests must send the
MCP-Protocol-Versionheader. Without it, the SDK answers HTTP400. - Let users disconnect hosts with
auth.oauthConnections.listandauth.oauthConnections.revoke. - Every OAuth access token carries the ID of the consent that issued it, also
with
renewal: false. A token stops working when that consent is revoked, even if the person later grants the same access again. Tokens issued by a beta without this claim are rejected; hosts sign in again. - Disabling an OAuth resource now rejects access tokens that were already issued, not only refresh.
@lupinum/better-convex-agentsdeclares@modelcontextprotocol/serveras an exact peer dependency. Install it in your application:pnpm add @lupinum/better-convex-agents @lupinum/better-convex-functions @modelcontextprotocol/server@2.3.1.
Add MCP to your application shows the complete new setup.
16. Update component tests
setupBetterConvexTest() from @lupinum/better-convex-nuxt/test now runs the
real composables against an in-memory Convex connection. The composables
map is gone. Install the runtime's plugin, and bind only useConvexAuth:
// Before
mockNuxtImport(
'useConvexQuery',
() =>
(...args) =>
testState.call('useConvexQuery', args),
)
mockNuxtImport(
'useConvexMutation',
() =>
(...args) =>
testState.call('useConvexMutation', args),
)
mockNuxtImport(
'useConvexAuth',
() =>
(...args) =>
testState.call('useConvexAuth', args),
)
// After
mockNuxtImport('useConvexAuth', () => () => testState.convex!.auth)
const wrapper = await mountSuspended(ClientScreen, {
global: { plugins: [testState.convex!.plugin] },
})Other changes:
- Every request stays pending until the test answers it. A one-shot query without an answer no longer throws.
- Each entry of a mutation or action control's
callshasargs,identity,state,resolve(), andreject(). Query calls haveidentity, and theirkind'refresh'is now'query'. - New
respond(fn)andnextCall()on every control.reset()no longer rejects pending requests. - The upload control uses the real upload code:
progress(loaded, total?)instead ofprogress({ loaded, total, percent }), and newfail(status)andnextCall().reject(error)now fails the upload-URL mutation. - Plain Vue tests import
setupBetterConvexTestfrom@lupinum/better-convex-vue/test.
New options you can use
These are not breaking, but they often replace application code:
definePageMeta({ convexAuth: 'guest' })for sign-in pages,useConvexAuthReturnTo(), andnormalizeLocalRedirectPath(). See Route protection.convex.auth.routes: 'protected'andconvex.auth.defaultQueryAuthfor application-wide defaults.getConvexUser(event),requireConvexUser(event), andtoConvexH3Error(error)in Nitro handlers.blockedBy,immediate,lazy, andexecute()on queries.useConvexOperation(work), imported from@lupinum/better-convex-nuxt/experimental, for several calls and uploads that must run for one signed-in user. See Multi-step operations.signInAsfrom@lupinum/better-convex-nuxt/better-auth/test.