Skip to main content

Experimental APIs

APIs whose shape may still change, how to import them, and how they become stable.

Some APIs are useful already, but real applications have not yet shown that their shape is right. Experimental composables live in a separate entry point:

PackageImport
@lupinum/better-convex-nuxt@lupinum/better-convex-nuxt/experimental
@lupinum/better-convex-vue@lupinum/better-convex-vue/experimental
ts
import { useConvexOperation } from '@lupinum/better-convex-nuxt/experimental'

Rules

  • Semantic versioning does not cover experimental APIs. A minor release can change or remove one. The changelog names every such change.
  • Nuxt never auto-imports an experimental API. The explicit import shows at the call site that the code depends on one.
  • Experimental options live under experimental: convex.experimental in nuxt.config.ts (the convex.client options go straight to the Convex client), and experimental.anonymous in createBetterConvexAuth.
  • Experimental APIs follow the same security rules as stable ones. A user change cancels their work, and Convex functions still decide what a user may read or change.

How an API becomes stable

When three real applications use an API in the same way, it moves to the main entry point. The experimental import then keeps working as an alias until the next major version, so code that used it early does not break.

Current experimental APIs

APIWhat it does
useConvexOperationRuns several calls and uploads as one operation for the current user. Reference
insertAtTopInserts an item into the first matching loaded page. Guide
optimisticallyUpdateValueInPaginatedQueryUpdates items on every matching loaded page. Guide
createBetterConvexAuth option experimental.anonymousGives guests Better Auth users and sessions. Recipe
experimental.keepAliveKeeps stopped query subscriptions open for a bounded time. Configuration