@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.
- package/dist/agent/AGENTS.md +2 -2
- package/dist/agent/pages/docs/build/agents/limits.md +1 -0
- package/dist/agent/pages/docs/build/agents/mcp-apps.md +4 -2
- package/dist/agent/pages/docs/build/agents/mcp-door.md +164 -0
- package/dist/agent/pages/docs/build/application-behavior/devtools.md +6 -0
- package/dist/agent/pages/docs/build/application-behavior/error-handling.md +1 -1
- package/dist/agent/pages/docs/build/authentication/cacheable-public-pages.md +12 -0
- package/dist/agent/pages/docs/build/authentication/sign-in-and-sign-out.md +2 -0
- package/dist/agent/pages/docs/build/files/upload-files.md +4 -0
- package/dist/agent/pages/docs/build/functions/threat-model.md +3 -1
- package/dist/agent/pages/docs/build/queries/pagination.md +2 -2
- package/dist/agent/pages/docs/build/queries/queries.md +2 -2
- package/dist/agent/pages/docs/build/queries/ssr-options.md +1 -1
- package/dist/agent/pages/docs/build/server/credentials-and-security.md +1 -1
- package/dist/agent/pages/docs/build/server/server-convex.md +4 -0
- package/dist/agent/pages/docs/build/server/server-routes.md +7 -3
- package/dist/agent/pages/docs/build/server/webhooks-and-jobs.md +5 -3
- package/dist/agent/pages/docs/concepts/errors-and-failures.md +1 -1
- package/dist/agent/pages/docs/concepts/request-lifecycle.md +1 -1
- package/dist/agent/pages/docs/concepts/server-and-client-boundaries.md +1 -1
- package/dist/agent/pages/docs/concepts/ssr-hydration-realtime.md +1 -1
- package/dist/agent/pages/docs/get-started/installation.md +5 -5
- package/dist/agent/pages/docs/get-started/plain-vue.md +91 -0
- package/dist/agent/pages/docs/operations/deploy-to-vercel.md +139 -62
- package/dist/agent/pages/docs/operations/deployment.md +49 -16
- package/dist/agent/pages/docs/operations/environment-variables.md +8 -5
- package/dist/agent/pages/docs/operations/release-compatibility.md +11 -2
- package/dist/agent/pages/docs/operations/upgrade-to-1-0.md +34 -0
- package/dist/agent/pages/docs/overview/comparison.md +4 -4
- package/dist/agent/pages/docs/overview/who-it-is-for.md +3 -3
- package/dist/agent/pages/docs/recipes/authenticated-server-route.md +3 -2
- package/dist/agent/pages/docs/recipes/error-messages.md +1 -1
- package/dist/agent/pages/docs/reference/api-surface.md +5 -5
- package/dist/agent/pages/docs/reference/composables.md +24 -5
- package/dist/agent/pages/docs/reference/error-types.md +2 -2
- package/dist/agent/pages/docs/reference/package-exports.md +3 -3
- package/dist/agent/pages/docs/reference/server-api.md +20 -11
- package/dist/index.d.mts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.mjs +2 -1
- package/dist/internal.d.mts +2 -2
- package/dist/internal.d.ts +2 -2
- package/dist/internal.mjs +2 -1
- package/dist/shared/{better-convex-functions.BXyIEZ9W.mjs → better-convex-functions.BCIQ7pMR.mjs} +45 -2
- package/dist/shared/{better-convex-functions.AOeEX0Gw.d.mts → better-convex-functions.BZdG2Xwh.d.mts} +169 -75
- package/dist/shared/better-convex-functions.D7xPX3b9.mjs +60 -0
- package/dist/shared/{better-convex-functions.D89tXIyj.d.ts → better-convex-functions.DrBgiAoE.d.ts} +169 -75
- package/dist/test.mjs +1 -1
- package/package.json +1 -1
package/dist/agent/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# @lupinum/better-convex-functions 0.1.0-rc.
|
|
1
|
+
# @lupinum/better-convex-functions 0.1.0-rc.3 documentation
|
|
2
2
|
|
|
3
|
-
These pages describe the installed version 0.1.0-rc.
|
|
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
|
|
107
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
118
|
-
const
|
|
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(
|
|
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)
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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` |
|
|
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.
|
|
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`:
|