@lupinum/better-convex-functions 0.1.0-rc.2 → 0.1.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/dist/agent/AGENTS.md +2 -2
  2. package/dist/agent/pages/docs/build/agents/limits.md +1 -0
  3. package/dist/agent/pages/docs/build/agents/mcp-apps.md +4 -2
  4. package/dist/agent/pages/docs/build/agents/mcp-door.md +164 -0
  5. package/dist/agent/pages/docs/build/application-behavior/devtools.md +6 -0
  6. package/dist/agent/pages/docs/build/application-behavior/error-handling.md +1 -1
  7. package/dist/agent/pages/docs/build/authentication/cacheable-public-pages.md +12 -0
  8. package/dist/agent/pages/docs/build/authentication/sign-in-and-sign-out.md +2 -0
  9. package/dist/agent/pages/docs/build/files/upload-files.md +4 -0
  10. package/dist/agent/pages/docs/build/functions/threat-model.md +3 -1
  11. package/dist/agent/pages/docs/build/queries/pagination.md +2 -2
  12. package/dist/agent/pages/docs/build/queries/queries.md +2 -2
  13. package/dist/agent/pages/docs/build/queries/ssr-options.md +1 -1
  14. package/dist/agent/pages/docs/build/server/credentials-and-security.md +1 -1
  15. package/dist/agent/pages/docs/build/server/server-convex.md +4 -0
  16. package/dist/agent/pages/docs/build/server/server-routes.md +7 -3
  17. package/dist/agent/pages/docs/build/server/webhooks-and-jobs.md +5 -3
  18. package/dist/agent/pages/docs/concepts/errors-and-failures.md +1 -1
  19. package/dist/agent/pages/docs/concepts/request-lifecycle.md +1 -1
  20. package/dist/agent/pages/docs/concepts/server-and-client-boundaries.md +1 -1
  21. package/dist/agent/pages/docs/concepts/ssr-hydration-realtime.md +1 -1
  22. package/dist/agent/pages/docs/get-started/installation.md +5 -5
  23. package/dist/agent/pages/docs/get-started/plain-vue.md +91 -0
  24. package/dist/agent/pages/docs/operations/deploy-to-vercel.md +139 -62
  25. package/dist/agent/pages/docs/operations/deployment.md +49 -16
  26. package/dist/agent/pages/docs/operations/environment-variables.md +8 -5
  27. package/dist/agent/pages/docs/operations/release-compatibility.md +11 -2
  28. package/dist/agent/pages/docs/operations/upgrade-to-1-0.md +34 -0
  29. package/dist/agent/pages/docs/overview/comparison.md +4 -4
  30. package/dist/agent/pages/docs/overview/who-it-is-for.md +3 -3
  31. package/dist/agent/pages/docs/recipes/authenticated-server-route.md +3 -2
  32. package/dist/agent/pages/docs/recipes/error-messages.md +1 -1
  33. package/dist/agent/pages/docs/reference/api-surface.md +5 -5
  34. package/dist/agent/pages/docs/reference/composables.md +24 -5
  35. package/dist/agent/pages/docs/reference/error-types.md +2 -2
  36. package/dist/agent/pages/docs/reference/package-exports.md +3 -3
  37. package/dist/agent/pages/docs/reference/server-api.md +20 -11
  38. package/dist/index.d.mts +1 -1
  39. package/dist/index.d.ts +1 -1
  40. package/dist/index.mjs +2 -1
  41. package/dist/internal.d.mts +2 -2
  42. package/dist/internal.d.ts +2 -2
  43. package/dist/internal.mjs +2 -1
  44. package/dist/shared/{better-convex-functions.BXyIEZ9W.mjs → better-convex-functions.BCIQ7pMR.mjs} +45 -2
  45. package/dist/shared/{better-convex-functions.AOeEX0Gw.d.mts → better-convex-functions.BZdG2Xwh.d.mts} +169 -75
  46. package/dist/shared/better-convex-functions.D7xPX3b9.mjs +60 -0
  47. package/dist/shared/{better-convex-functions.D89tXIyj.d.ts → better-convex-functions.DrBgiAoE.d.ts} +169 -75
  48. package/dist/test.mjs +1 -1
  49. package/package.json +1 -1
@@ -1,6 +1,6 @@
1
- # @lupinum/better-convex-functions 0.1.0-rc.2 documentation
1
+ # @lupinum/better-convex-functions 0.1.0-rc.3 documentation
2
2
 
3
- These pages describe the installed version 0.1.0-rc.2. Prefer them over the
3
+ These pages describe the installed version 0.1.0-rc.3. Prefer them over the
4
4
  website and over knowledge of earlier versions: the API changed during the 1.0 betas.
5
5
 
6
6
  ## Start here
@@ -38,6 +38,7 @@ In-app agent runs are experimental in 0.1: their API may change in a minor relea
38
38
  | Finished in-app agent runs | kept 30 days, with their messages | deleted by `housekeeping` |
39
39
  | Length of a tool name | 1 to 64 letters, digits, `_` or `-` | error when the module loads |
40
40
  | Text of an approval summary | one line, 300 characters | longer text is cut |
41
+ | Unclaimed upload links and files | 100 per agent connection | `RATE_LIMITED`; see [Files from agents](./mcp-door.md#files-from-agents) |
41
42
 
42
43
  Read tools have no rate limit. Convex's own limits apply to them, and a page
43
44
  reads at most 100 rows.
@@ -103,8 +103,10 @@ await writeFile(
103
103
  }
104
104
  ```
105
105
 
106
- Run `pnpm build:mcp-ui` before you run `pnpm exec better-convex convex dev` or
107
- `pnpm exec better-convex convex deploy`.
106
+ Run `pnpm build:mcp-ui` before you run `pnpm exec better-convex convex dev`,
107
+ and commit the generated `convex/mcp/notesCardHtml.ts`. A production build
108
+ that deploys Convex, as in [Deploy to Vercel](../../operations/deploy-to-vercel.md),
109
+ deploys the committed file.
108
110
 
109
111
  ## Connect the card to the host
110
112
 
@@ -157,6 +157,170 @@ Signing out of the application ends the session that granted consent, so it
157
157
  disconnects the person's hosts too. The person connects them again after the
158
158
  next sign-in.
159
159
 
160
+ ## Files from agents
161
+
162
+ An MCP request carries at most 64 KiB, so a file cannot travel inside a tool
163
+ call. An agent sends a file in three steps instead:
164
+
165
+ 1. It calls the built-in tool `request_upload` and gets one-time upload tokens.
166
+ 2. It sends each file's bytes to the application's upload route, with one token per file. The route answers with an `uploadId`.
167
+ 3. It calls one of your tools with the `uploadId`. The tool calls `claimUpload`, which hands it the stored file.
168
+
169
+ Only agents that can read local files and send HTTP requests can do this,
170
+ for example Claude Code or Codex. A chat app such as Claude on the web or
171
+ ChatGPT cannot send a file from the person's computer.
172
+
173
+ ### Why a claim
174
+
175
+ A storage ID gives whoever holds it the file (see
176
+ [Threat model](../functions/threat-model.md)). An `uploadId` does not.
177
+ `claimUpload` passes only when all of these are true:
178
+
179
+ - The call comes from the same actor that asked for the link: the same agent connection of the same person.
180
+ - The file was not claimed before.
181
+ - The file arrived less than 24 hours ago.
182
+ - The type and size are ones the tool allows. The route decides the type from the file's first bytes, never from its name.
183
+
184
+ A missing, foreign or already claimed upload fails with `NOT_FOUND`. A type or
185
+ size the tool does not allow fails with `INVALID_INPUT`, and the file stays
186
+ claimable for another call.
187
+
188
+ ### Turn uploads on
189
+
190
+ Add `uploads` to `defineTools`. `scopes` names the OAuth scopes whose
191
+ connections may ask for links; a read-only connection does not see the tool.
192
+ The samples in this section come from an expense app with an `expenses` table.
193
+
194
+ ```ts
195
+ // convex/agents.ts
196
+ import { defineTools } from '@lupinum/better-convex-agents'
197
+
198
+ import { internal } from './_generated/api'
199
+ import { fns } from './functions'
200
+ import * as receipts from './receipts'
201
+
202
+ export const tools = defineTools(
203
+ fns,
204
+ { receipts },
205
+ {
206
+ functions: internal.agents,
207
+ uploads: { scopes: ['write'], types: ['application/pdf'], maxBytes: 10 * 1024 * 1024 },
208
+ },
209
+ )
210
+
211
+ export const {
212
+ attach_receipt,
213
+ check_approval,
214
+ housekeeping,
215
+ request_upload,
216
+ upload_ticket,
217
+ upload_stored,
218
+ } = tools.functions
219
+ ```
220
+
221
+ `types` takes `application/pdf`, `image/png`, `image/jpeg`, `image/webp` and
222
+ `text/csv`. A CSV file has no signature: the route accepts UTF-8 text without
223
+ control characters other than tab and line breaks, and your parser checks the
224
+ rest. `maxBytes` is at most 20 MiB, the request limit of a Convex HTTP action.
225
+
226
+ Add the upload route to `convex/http.ts`, next to the MCP door:
227
+
228
+ ```ts
229
+ import { uploadRoute } from '@lupinum/better-convex-agents'
230
+
231
+ // POST /mcp/upload, or the `path` you set in `uploads`.
232
+ http.route(uploadRoute(agents))
233
+ ```
234
+
235
+ ### Take a file in a tool
236
+
237
+ Call `claimUpload` inside a mutation operation, in the same transaction as the
238
+ write that stores the file. Read the target row first, so the row rules decide
239
+ whether this caller may change it.
240
+
241
+ ```ts
242
+ // convex/receipts.ts
243
+ import { claimUpload, fail } from '@lupinum/better-convex-functions'
244
+ import { v } from 'convex/values'
245
+
246
+ import { mutation } from './functions'
247
+
248
+ export const attach = mutation({
249
+ action: 'receipts.attach',
250
+ args: { expenseId: v.id('expenses'), uploadId: v.string() },
251
+ returns: v.null(),
252
+ tool: {
253
+ name: 'attach_receipt',
254
+ description: 'Attach a receipt PDF you sent with request_upload to an expense.',
255
+ },
256
+ handler: async (ctx, { expenseId, uploadId }) => {
257
+ const expense = await ctx.db.get(expenseId)
258
+ if (!expense) fail('NOT_FOUND', 'No expense with this ID.')
259
+ const file = await claimUpload(ctx, uploadId, {
260
+ types: ['application/pdf'],
261
+ maxBytes: 10 * 1024 * 1024,
262
+ })
263
+ await ctx.db.patch(expenseId, { receipt: file.storageId, receiptSha256: file.sha256 })
264
+ return null
265
+ },
266
+ })
267
+ ```
268
+
269
+ `claimUpload` returns `{ storageId, type, size, sha256 }`. The same file sent
270
+ twice has the same `sha256`, so a tool can find a duplicate with an index on
271
+ it. A tool that needs a person's approval claims the file when the person
272
+ approves, as the same agent connection.
273
+
274
+ ### What the agent sees
275
+
276
+ `request_upload` takes `count`, from 1 to 20 files, and returns the URL, the
277
+ tokens and short instructions:
278
+
279
+ ```json
280
+ {
281
+ "url": "https://happy-otter-123.convex.site/mcp/upload",
282
+ "method": "POST",
283
+ "tokens": ["bcu_…"],
284
+ "expiresAt": "2026-10-15T09:30:00.000Z",
285
+ "maxBytes": 10485760,
286
+ "types": ["application/pdf"]
287
+ }
288
+ ```
289
+
290
+ The agent sends each file as the raw request body:
291
+
292
+ ```bash
293
+ curl -X POST --data-binary @receipt.pdf -H "Authorization: Bearer bcu_…" https://happy-otter-123.convex.site/mcp/upload
294
+ ```
295
+
296
+ The route answers `201` with `{ uploadId, type, size, sha256 }`. It answers
297
+ `401` for a token that expired, was used or never existed, `413` for a file
298
+ over `maxBytes`, and `415` for a file of another type. A refused file is not
299
+ stored. Without a valid token the route reads at most 4 MiB of a refused
300
+ body, so a larger file may get a `520` from Convex instead of the `401`.
301
+
302
+ ### Limits and cleanup
303
+
304
+ | Limit | Value | When reached |
305
+ | --- | --- | --- |
306
+ | Links in one `request_upload` call | 1 to 20 | `INVALID_INPUT` |
307
+ | Links and files a connection leaves unclaimed | 100 | `RATE_LIMITED`; use them, or wait until they expire |
308
+ | Time to send a file with a link | 15 minutes | the route answers `401` |
309
+ | Time to claim a stored file | 24 hours | `NOT_FOUND`; `housekeeping` deletes the file |
310
+ | Record of a claimed upload | 30 days | `housekeeping` deletes the record; the file stays |
311
+
312
+ `request_upload` counts against the 60 writes a minute of the connection.
313
+ `housekeeping` deletes expired links and unclaimed files in the same run as
314
+ the other retention work, and account deletion removes a person's links and
315
+ unclaimed files. A claimed file belongs to the row that stores its ID: delete
316
+ it with that row.
317
+
318
+ ### Cost
319
+
320
+ - `request_upload`: reads up to 202 upload rows of the connection by index, writes one row per link and one rate-limit row.
321
+ - The upload route: one query, one storage write and one mutation that writes one row.
322
+ - `claimUpload`: reads and writes one row. It invalidates no query of the application.
323
+
160
324
  ## Connect a host
161
325
 
162
326
  Create one OAuth client for each host with `auth.oauthOperator.createHostClient`,
@@ -23,6 +23,12 @@ export default defineNuxtConfig({
23
23
 
24
24
  Open Nuxt DevTools and select the Better Convex Nuxt panel.
25
25
 
26
+ Nuxt 4 includes `@nuxt/devtools`. Nuxt 5 does not. On Nuxt 5, install it to see the panel:
27
+
28
+ ```bash
29
+ pnpm add -D @nuxt/devtools
30
+ ```
31
+
26
32
  ## Query inspection
27
33
 
28
34
  Use the query list and detail view to inspect:
@@ -65,7 +65,7 @@ The codes that Better Convex raises itself include `IDENTITY_CHANGED`, `CANCELLE
65
65
 
66
66
  ## Errors from Nitro routes
67
67
 
68
- A route that rethrows with `toConvexH3Error` returns the serialized error. Revive it in the browser:
68
+ A route that rethrows with `toConvexH3Error` returns the serialized error as an HTTP error (`NuxtError`); on the server, check it with `isNuxtError(error)` from `nuxt/server` and read `error.status`. Revive it in the browser:
69
69
 
70
70
  ```ts
71
71
  import { normalizeConvexError } from '@lupinum/better-convex-nuxt/errors'
@@ -44,6 +44,18 @@ export default defineNuxtConfig({
44
44
 
45
45
  The rule `'/**'` also matches `/api/**`, which includes the sign-in routes under `/api/auth`. A cache must never store a response from these routes, because it could serve the session of one user to another visitor. List only your public page paths, not `'/**'`. The `/api/**` rule is a second guard that turns caching off for the auth routes.
46
46
 
47
+ On Nuxt 5, a cached route (`cache`, `swr`, `isr`) ignores the query string unless the rule sets `allowQuery`. On Nuxt 4, the cache key includes the query string. On both, do not cache a page whose HTML depends on a query, such as `?redirect=`.
48
+
49
+ A cache rule (`cache`, `swr`, `isr`) stores the rendered page and replaces the `Vary: Cookie` and `Cache-Control: private, no-store` headers that the module sets on pages for signed-in users. This is true on Nuxt 4 and Nuxt 5. On Nuxt 4, the cached render also runs without the request cookies, so SSR auth renders those pages signed out. On Nuxt 5, a `routeRules` `headers` rule or a server middleware that sets cache headers also overrides the module's headers; on Nuxt 4 the module's headers win over these. Set `convex: { ssrAuth: false }` on every cached route, or remove the cache rule.
50
+
51
+ The module checks the `routeRules` and `nitro.routeRules` of your `nuxt.config` at build time. It does not check server middleware, `defineRouteRules()` in page files, or rules that other modules add. For each of those checked rules that caches a page with SSR auth on, it logs this warning (here for `'/blog/**': { swr: 3600 }`):
52
+
53
+ ```text
54
+ Route rules "/blog/**" cache pages that resolve the Convex session during SSR. A cache rule replaces the `Vary: Cookie` and `Cache-Control: private, no-store` headers the module sets on signed-in pages, and on Nuxt 5 a `headers` rule with cache headers does too. Set `convex: { ssrAuth: false }` on cached routes or drop the cache rule.
55
+ ```
56
+
57
+ Check server middleware, page-level rules and rules from other modules that set cache headers yourself. A `cache-control` header that forbids storing (`no-store`, `private`, `no-cache`, `max-age=0`) is not a cache rule and gets no warning.
58
+
47
59
  ## Turn it off for all routes
48
60
 
49
61
  Set `auth.ssr: false`. A route rule with `convex: { ssrAuth: true }` turns it on again for matching routes.
@@ -113,6 +113,8 @@ await navigateTo('/')
113
113
 
114
114
  Your application decides where to navigate. The module orders the session operations, clears the previous user's query data, and replaces the Convex client.
115
115
 
116
+ Do not call `clearNuxtState()` without keys during sign-out. On Nuxt 5 it resets the module's `convex:*` state to its initial value. The auth state then shows as pending, nothing loads it again, and protected routes wait until their timeout and then treat the visitor as signed out. Pass the keys of your own state, for example `clearNuxtState(['cart'])`.
117
+
116
118
  ## Wait for the auth state
117
119
 
118
120
  Queries already wait for auth. Use `ready()` only when other code must wait until the first auth state is known:
@@ -189,6 +189,10 @@ When the signed-in user changes after the file was stored but before `complete`
189
189
 
190
190
  ## Attach the file safely
191
191
 
192
+ <note>
193
+ This recipe is for files a person sends from the browser. For a file an agent sends over MCP, use `claimUpload` from `@lupinum/better-convex-functions`: see [Files from agents](../agents/mcp-door.md#files-from-agents). The helper below has the same name but takes an owner ID and a storage ID.
194
+ </note>
195
+
192
196
  A storage ID from the browser is only a claim. The upload URL does not tie a file to a user or a document. Before a mutation uses a storage ID, it must check four things:
193
197
 
194
198
  1. The caller is signed in.
@@ -61,7 +61,9 @@ fail, so the `unguardedFunctions` test in
61
61
  `ctx.db`, never from the input, except to attach a file the caller just
62
62
  uploaded. Even then, a caller can attach the storage ID of someone else's
63
63
  file to their own row, so treat storage IDs as secrets and never show one
64
- to a person who may not have the file.
64
+ to a person who may not have the file. For a file from an agent, take an
65
+ upload ID instead and call `claimUpload`: it checks that the caller sent
66
+ the file (see [Files from agents](../agents/mcp-door.md#files-from-agents)).
65
67
  - **Effects outside the database.** An action has no transaction. A message
66
68
  sent or a payment made before a later step fails stays done.
67
69
  - **The auth component.** Sessions, OAuth tokens and consent are checked by
@@ -96,7 +96,7 @@ const {
96
96
 
97
97
  `auth: 'required'` only keeps the query from running while nobody is signed in. Convex rejects a user who is not a member of the channel.
98
98
 
99
- In Nuxt, the return value is also a native Promise. Await it only when surrounding setup must wait for the first page:
99
+ You can also await the return value. Await it only when surrounding setup must wait for the first page:
100
100
 
101
101
  ```ts
102
102
  const { data: messages, status } = await useConvexPaginatedQuery(api.messages.list, args, {
@@ -104,7 +104,7 @@ const { data: messages, status } = await useConvexPaginatedQuery(api.messages.li
104
104
  })
105
105
  ```
106
106
 
107
- The awaited value is a separate non-Promise view of the same refs. Initial success, error, skip, and `server: false` resolve; inspect its state for the outcome.
107
+ The awaited value holds the same refs. Initial success, error, skip, and `server: false` resolve; inspect its state for the outcome.
108
108
 
109
109
  ## Returned state
110
110
 
@@ -68,7 +68,7 @@ Vue consumers use the same API without `server` or `lazy`.
68
68
 
69
69
  ## Optional await
70
70
 
71
- The Nuxt return value is both the immediate state above and a native Promise. Await it only when surrounding setup must wait for the first result:
71
+ You can also await the state above. Await it only when the component must wait for the first result:
72
72
 
73
73
  ```ts
74
74
  const projects = useConvexQuery(api.projects.list, {})
@@ -79,7 +79,7 @@ if (settled.error.value) {
79
79
  }
80
80
  ```
81
81
 
82
- The awaited value is a separate non-Promise view of the same refs. Success, error, skip, and `server: false` all resolve; inspect `status` and `error` for the outcome.
82
+ The awaited value holds the same refs. Success, error, skip, and `server: false` all resolve; inspect `status` and `error` for the outcome. In plain Vue, a component that awaits renders only inside `<Suspense>`. [Plain Vue](../../get-started/plain-vue.md#wait-for-data-before-a-page-shows).
83
83
 
84
84
  ## Arguments and skip
85
85
 
@@ -31,7 +31,7 @@ There is no module-wide `server` default. The `server: false` choice stays visib
31
31
 
32
32
  ## Optional await
33
33
 
34
- Query refs exist immediately. Await the native Promise/state only when surrounding setup must wait for the first SSR or browser result:
34
+ Query refs exist immediately. Await the state only when surrounding setup must wait for the first SSR or browser result:
35
35
 
36
36
  ```ts
37
37
  const account = useConvexQuery(api.account.current, {}, { auth: 'required' })
@@ -46,7 +46,7 @@ Authentication and transport failures expose a stable category and safe message.
46
46
 
47
47
  Structured Convex application errors remain `server` errors and preserve their application data. Their `message` is the text from `ConvexError` data, never Convex's wire message.
48
48
 
49
- `toConvexH3Error` and `requireConvexUser` put only the serialized public error into the H3 response. When the auth backend fails, `getConvexUser` and `requireConvexUser` answer 502 without credential details instead of treating the request as anonymous.
49
+ `toConvexH3Error` and `requireConvexUser` put only the serialized public error into the HTTP error (`NuxtError`). When the auth backend fails, `getConvexUser` and `requireConvexUser` answer 502 without credential details instead of treating the request as anonymous.
50
50
 
51
51
  ## Trusted client IP headers
52
52
 
@@ -16,6 +16,7 @@ source: "ginko-content"
16
16
  `serverConvex(event)` creates one request-scoped caller with `query`, `mutation`, and `action` methods.
17
17
 
18
18
  ```ts [server/api/projects.get.ts]
19
+ import { defineEventHandler } from 'nuxt/server'
19
20
  import { api } from '#convex/api'
20
21
  import { serverConvex } from '#convex/server'
21
22
 
@@ -148,6 +149,9 @@ or operator failures.
148
149
  Use `getConvexUser(event)` to read the signed-in user for routing or rendering decisions, and `requireConvexUser(event)` to answer 401 for an anonymous request:
149
150
 
150
151
  ```ts [server/api/me.get.ts]
152
+ import { defineEventHandler } from 'nuxt/server'
153
+ import { requireConvexUser } from '#convex/server'
154
+
151
155
  export default defineEventHandler(async (event) => {
152
156
  const user = await requireConvexUser(event)
153
157
  return { id: user.id }
@@ -26,6 +26,7 @@ Do not wrap every Convex function in a Nuxt API route. Browser queries and mutat
26
26
  ## Validated route example
27
27
 
28
28
  ```ts [server/api/reports.post.ts]
29
+ import { createError, defineEventHandler, readBody } from 'nuxt/server'
29
30
  import { api } from '#convex/api'
30
31
  import { serverConvex, toConvexH3Error } from '#convex/server'
31
32
  import { z } from 'zod'
@@ -54,7 +55,7 @@ Validate at the HTTP boundary and again through Convex argument validators. The
54
55
 
55
56
  ## Return safe errors
56
57
 
57
- `toConvexH3Error(error)` turns any thrown value into an H3 error. The HTTP status follows the error kind:
58
+ `toConvexH3Error(error)` turns any thrown value into an HTTP error (`NuxtError`). Check it with `isNuxtError(error)` from `nuxt/server` and read `error.status`. The HTTP status follows the error kind:
58
59
 
59
60
  | Kind | HTTP status |
60
61
  | --- | --- |
@@ -86,16 +87,19 @@ Map the error to your own response instead when a route must not reveal the Conv
86
87
  `requireConvexUser(event)` throws the same serialized 401 error, with code `UNAUTHENTICATED`, when the request has no valid session:
87
88
 
88
89
  ```ts [server/api/account.get.ts]
90
+ import { defineEventHandler } from 'nuxt/server'
91
+ import { requireConvexUser } from '#convex/server'
92
+
89
93
  export default defineEventHandler(async (event) => {
90
94
  const user = await requireConvexUser(event)
91
- setHeader(event, 'cache-control', 'private, no-store')
95
+ event.res.headers.set('cache-control', 'private, no-store')
92
96
  return { id: user.id }
93
97
  })
94
98
  ```
95
99
 
96
100
  Use `getConvexUser(event)` when an anonymous request is valid. It returns `null` when nobody is signed in.
97
101
 
98
- Both helpers are auto-imported in Nitro code. They exchange the session cookie at most once per request, so `getConvexUser(event)` and `serverConvex(event)` authorize the same identity.
102
+ The module auto-imports these four names in server code: `serverConvex`, `getConvexUser`, `requireConvexUser`, and `toConvexH3Error`. Import everything else, such as `defineEventHandler`, from `nuxt/server`. The examples import the four names from `#convex/server` too, so they also work with `imports.autoImport: false`. Both user helpers exchange the session cookie at most once per request, so `getConvexUser(event)` and `serverConvex(event)` authorize the same identity.
99
103
 
100
104
  When `serverConvex(event)` or `getConvexUser(event)` reads the session, it sets `Vary: Cookie` and `Cache-Control: private, no-store`. A public route that must stay cacheable on a CDN uses `serverConvex(event, { auth: 'none' })`.
101
105
 
@@ -110,12 +110,14 @@ it with a server-only secret:
110
110
  `webhookIngestSecret: ''` to `runtimeConfig` in `nuxt.config.ts`.
111
111
 
112
112
  ```ts [server/api/webhooks/provider.post.ts]
113
+ import { createError, defineEventHandler, getRequestHeader, useRuntimeConfig } from 'nuxt/server'
113
114
  import { api } from '#convex/api'
114
115
  import { serverConvex } from '#convex/server'
115
116
 
116
117
  export default defineEventHandler(async (event) => {
117
- const rawBody = await readRawBody(event)
118
- const signature = getHeader(event, 'provider-signature')
118
+ // The exact bytes the provider signed. Use `event.req.arrayBuffer()` when the provider signs raw bytes.
119
+ const rawBody = await event.req.text()
120
+ const signature = getRequestHeader(event, 'provider-signature')
119
121
 
120
122
  if (!rawBody || !signature || !(await verifyProviderSignature(rawBody, signature))) {
121
123
  throw createError({ status: 401, statusText: 'Invalid signature' })
@@ -124,7 +126,7 @@ export default defineEventHandler(async (event) => {
124
126
  const payload = parseProviderEvent(rawBody)
125
127
 
126
128
  await serverConvex(event, { auth: 'none' }).mutation(api.webhooks.receive, {
127
- secret: useRuntimeConfig(event).webhookIngestSecret,
129
+ secret: useRuntimeConfig().webhookIngestSecret,
128
130
  providerEventId: payload.id,
129
131
  type: payload.type,
130
132
  })
@@ -98,7 +98,7 @@ Convex's own wire message is never used, because it can contain function stack f
98
98
 
99
99
  SSR errors cross the Nuxt payload as a public serialized shape. The client revives that shape as `ConvexCallError`, including `functionName`.
100
100
 
101
- A Nitro route can return the same shape, without `functionName`, with `toConvexH3Error(error)`. In the browser, `normalizeConvexError()` revives it from the `FetchError` of `$fetch` or `useFetch`. Revival accepts only the exact public shape; any other object stays `unknown`.
101
+ A Nitro route can return the same shape, without `functionName`, with `toConvexH3Error(error)`, an HTTP error (`NuxtError`). In the browser, `normalizeConvexError()` revives it from the `FetchError` of `$fetch` or `useFetch`. Revival accepts only the exact public shape; any other object stays `unknown`.
102
102
 
103
103
  `ConvexCallError` does not retain a raw upstream cause. JSON, structured clone,
104
104
  SSR HTML, normal inspection, and direct property access therefore cannot recover
@@ -63,6 +63,6 @@ When the Vue scope that created a listener ends, the listener stops. The per-app
63
63
 
64
64
  ## Optional await
65
65
 
66
- The return value is also a native Promise. `await projects` produces a separate non-Promise view of the same refs after the first result. Success, query error, skip, and `server: false` resolve; inspect state for the result.
66
+ You can also await the return value. `await projects` returns the same refs after the first result. Success, query error, skip, and `server: false` resolve; inspect state for the result.
67
67
 
68
68
  See [SSR, hydration, and real-time](./ssr-hydration-realtime.md) for the rendering decision.
@@ -72,7 +72,7 @@ import { serverConvex } from '@lupinum/better-convex-nuxt/server'
72
72
 
73
73
  `serverConvex` creates a request-scoped caller. Its query, mutation, and action calls do not hydrate browser composable state.
74
74
 
75
- The same entry exports `getConvexUser` and `requireConvexUser`, which read the request's signed-in user, and `toConvexH3Error`, which turns an error into a safe H3 response. The module auto-imports all four in Nitro code.
75
+ The same entry exports `getConvexUser` and `requireConvexUser`, which read the request's signed-in user, and `toConvexH3Error`, which turns an error into a safe HTTP error (`NuxtError`). The module auto-imports these four names in server code. Import everything else, such as `defineEventHandler`, from `nuxt/server`.
76
76
 
77
77
  ## Error entry
78
78
 
@@ -42,7 +42,7 @@ For the default lifecycle, the Convex dashboard may show an HTTP execution from
42
42
 
43
43
  ## Immediate state and optional await
44
44
 
45
- `useConvexQuery` returns refs immediately. Its Nuxt return is also a native Promise when navigation or suspense should wait for the first result:
45
+ `useConvexQuery` returns refs immediately. You can also await it when navigation or suspense should wait for the first result:
46
46
 
47
47
  ```ts
48
48
  const posts = useConvexQuery(api.posts.list)
@@ -13,17 +13,17 @@ source: "ginko-content"
13
13
 
14
14
  > Create a Nuxt app, install Better Convex Nuxt, and connect a Convex deployment.
15
15
 
16
- This page creates a Nuxt 4 app and connects it to Convex. Authentication stays off until [Add authentication](./add-authentication.md). For Vue without Nuxt, use the [plain Vue guide](./plain-vue.md).
16
+ This page creates a Nuxt app and connects it to Convex. Authentication stays off until [Add authentication](./add-authentication.md). For Vue without Nuxt, use the [plain Vue guide](./plain-vue.md).
17
17
 
18
18
  ## Prerequisites
19
19
 
20
- - Node.js `^22.19.0` or `^24.11.0`
20
+ - Node.js `^22.22.3`, `^24.15.0` or `>=26.0.0`
21
21
  - A [Convex account](https://dashboard.convex.dev), or none for local development
22
22
  - pnpm (npm and yarn also work; change the commands)
23
23
 
24
24
  ## Create the Nuxt app
25
25
 
26
- Skip this step if you already have a Nuxt 4 app.
26
+ Skip this step if you already have a Nuxt 4.6 or newer app.
27
27
 
28
28
  ```bash
29
29
  pnpm create nuxt@latest my-convex-app
@@ -45,10 +45,10 @@ The module needs these versions:
45
45
 
46
46
  | Package | Version |
47
47
  | --- | --- |
48
- | `nuxt` | `>=4.5.2 <5` |
48
+ | `nuxt` | `^4.6.0 \|\| ^5.0.0-0` |
49
49
  | `convex` | `>=1.42.2 <2` |
50
50
 
51
- Check that `nuxt` in your `package.json` is 4.5.2 or newer. Better Auth is not installed yet. You add it in the auth step.
51
+ Check that `nuxt` in your `package.json` is 4.6.0 or newer. The module is tested on Nuxt 4.6.1 and on the Nuxt 5 nightly; Nuxt 5 is a pre-release until it ships. Better Auth is not installed yet. You add it in the auth step.
52
52
 
53
53
  ## Connect a Convex deployment
54
54
 
@@ -160,6 +160,97 @@ pause a query. A skipped query stops its subscription and clears its data.
160
160
  Query `data` is `undefined` until a value exists. A backend `null` result is
161
161
  successful data, not a loading or skip sentinel.
162
162
 
163
+ ## Wait for data before a page shows
164
+
165
+ A page that loads its data after it appears flashes empty and then moves its
166
+ content. To show the page only when its data exists, await its queries and
167
+ render it inside Vue's `<Suspense>`. A component that awaits does not render
168
+ at all without a `<Suspense>` above it:
169
+
170
+ ```vue [src/App.vue]
171
+ <template>
172
+ <RouterView v-slot="{ Component }">
173
+ <Suspense>
174
+ <component :is="Component" />
175
+ </Suspense>
176
+ </RouterView>
177
+ </template>
178
+ ```
179
+
180
+ ```vue [src/pages/NotesPage.vue]
181
+ <script setup lang="ts">
182
+ import { api } from '../../convex/_generated/api'
183
+ import { useConvexQuery } from '@lupinum/better-convex-vue'
184
+
185
+ const { data: notes, error } = await useConvexQuery(api.notes.list, {})
186
+ </script>
187
+ ```
188
+
189
+ When the route shows a different page component, `<Suspense>` keeps the
190
+ previous page on the screen. It shows the new page when every awaited query in
191
+ it, also in its child components, has its first result or error. The refs stay
192
+ live after the await. A navigation to the same component with other parameters
193
+ reuses the page and does not wait again; it shows `pending` while the new
194
+ arguments load.
195
+
196
+ - Start all queries of a component before you await them, then use
197
+ `await Promise.all([first, second])`. Each separate `await` waits for the
198
+ query before it.
199
+ - A child component starts its queries only after its parent's await is
200
+ finished.
201
+ - The await never rejects. Read `error` for a failure.
202
+ - The await waits while authentication loads. It does not wait for a skipped
203
+ query, a query with `immediate: false`, or an `auth: 'required'` query
204
+ without a signed-in user or after an authentication error.
205
+
206
+ Vue marks `<Suspense>` as experimental.
207
+
208
+ ## Load data before a navigation finishes
209
+
210
+ `<Suspense>` waits after the router changed the URL, and child components load
211
+ only after their parent. To load a page's data before the navigation finishes,
212
+ preload it in a router guard. This needs Vue Router 4.2 or later:
213
+
214
+ ```ts [src/router.ts]
215
+ import { preloadConvexQuery } from '@lupinum/better-convex-vue'
216
+ import { createRouter, createWebHistory } from 'vue-router'
217
+ import { api } from '../convex/_generated/api'
218
+ import type { Id } from '../convex/_generated/dataModel'
219
+ import ProjectPage from './pages/ProjectPage.vue'
220
+
221
+ export const router = createRouter({
222
+ history: createWebHistory(),
223
+ routes: [{ path: '/projects/:id', name: 'project', component: ProjectPage }],
224
+ })
225
+
226
+ router.beforeResolve(async (to) => {
227
+ if (to.name === 'project') {
228
+ const id = to.params.id as Id<'projects'>
229
+ await Promise.all([
230
+ preloadConvexQuery(api.projects.get, { id }),
231
+ preloadConvexQuery(api.tasks.list, { projectId: id }),
232
+ ])
233
+ }
234
+ })
235
+ ```
236
+
237
+ The queries load in parallel. When the page and its child components call
238
+ `useConvexQuery` with the same function, arguments, and `auth`, they start with
239
+ the result. The page shows complete on its first render, and the router can
240
+ scroll to its content.
241
+
242
+ - Start every preload before the first `await` in the guard, as in
243
+ `Promise.all` above. After an `await`, Vue Router no longer provides the app,
244
+ and `preloadConvexQuery` throws.
245
+ - `preloadConvexQuery` resolves when the first result or error exists, or after
246
+ 5 seconds without one, for example while the app is offline. It never
247
+ rejects for a query failure. The page's own query reports the error one
248
+ moment after its first render.
249
+ - The subscription stays open for 5 seconds after the preload resolves, also
250
+ when the navigation is cancelled. A page that mounts later loads its data
251
+ again.
252
+ - Preload only data that the page reads on its first render.
253
+
163
254
  ## Client options
164
255
 
165
256
  Pass supported `ConvexClient` options with `clientOptions`: