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:
| Package | Import |
|---|---|
@lupinum/better-convex-nuxt | @lupinum/better-convex-nuxt/experimental |
@lupinum/better-convex-vue | @lupinum/better-convex-vue/experimental |
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.experimentalinnuxt.config.ts(theconvex.clientoptions go straight to the Convex client), andexperimental.anonymousincreateBetterConvexAuth. - 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
| API | What it does |
|---|---|
useConvexOperation | Runs several calls and uploads as one operation for the current user. Reference |
insertAtTop | Inserts an item into the first matching loaded page. Guide |
optimisticallyUpdateValueInPaginatedQuery | Updates items on every matching loaded page. Guide |
createBetterConvexAuth option experimental.anonymous | Gives guests Better Auth users and sessions. Recipe |
experimental.keepAlive | Keeps stopped query subscriptions open for a bounded time. Configuration |