use-convex 0.0.2 → 1.1.0

package/README.md

@@ -6,8 +6,10 @@ SSR snapshots hydrate through the Nuxt payload, then the browser overlays a live
 
 ## Install
 
+[`use-convex` on npm](https://www.npmjs.com/package/use-convex)
+
 ```bash
-pnpm add use-convex convex
+npm i use-convex convex
 ```
 
 ```ts
@@ -24,7 +26,7 @@ export default defineNuxtConfig({
 <script setup lang="ts">
 import { api } from '~~/convex/_generated/api'
 
-const { data, pending, error } = await useConvexQuery(api.tasks.list, {})
+const { data, pending, error } = await useConvexQuery(api.tasks.list, {}, { authenticated: true })
 </script>
 ```
 
@@ -56,17 +58,18 @@ Set `convex.server: false` to skip SSR snapshots globally, or pass `{ server: fa
 const { data, pending, error, refresh } = await useConvexQuery(
   api.tasks.list,
   {}, // args, a ref / getter, or 'skip'
+  { authenticated: true }, // wait for Convex auth before live subscribe
 )
 ```
 
-| Option | Default | Purpose |
-|---|---|---|
-| `key` | function name + args | Nuxt payload / cache key |
-| `server` | `convex.server` (`true`) | SSR HttpClient snapshot |
-| `lazy` | `false` | Non-blocking on client navigation |
-| `live` | `true` | Subscribe after hydration |
-| `authenticated` | `false` | Wait for Convex auth before live subscribe |
-| `token` | cookie / none | Per-request JWT for SSR |
+| Option          | Default                  | Purpose                                    |
+| --------------- | ------------------------ | ------------------------------------------ |
+| `key`           | function name + args     | Nuxt payload / cache key                   |
+| `server`        | `convex.server` (`true`) | SSR HttpClient snapshot                    |
+| `lazy`          | `false`                  | Non-blocking on client navigation          |
+| `live`          | `true`                   | Subscribe after hydration                  |
+| `authenticated` | `false`                  | Wait for Convex auth before live subscribe |
+| `token`         | cookie / none            | Per-request JWT for SSR                    |
 
 Args accept the query's `FunctionArgs`, `'skip'`, or a `MaybeRefOrGetter` of either.
 
@@ -82,13 +85,14 @@ prewarmQuery(api.tasks.list, {})
 
 ### Several queries
 
+Browser-only live map (no SSR). Each value is `data | undefined` (loading) | `Error`. Combine with `useConvexQuery` when you need an SSR snapshot for known queries.
+
 ```ts
 const results = useConvexQueries(() => ({
-  inbox: { query: api.messages.list, args: { channel: 'inbox' } },
-  later: selectedId.value
-    ? { query: api.messages.get, args: { id: selectedId.value } }
-    : 'skip',
+  tasks: { query: api.tasks.list, args: {} },
+  files: showFiles.value ? { query: api.files.list, args: {} } : 'skip',
 }))
+// results.value.tasks
 ```
 
 ### Pagination
@@ -97,8 +101,9 @@ const results = useConvexQueries(() => ({
 const { results, status, isLoading, loadMore } = await useConvexPaginatedQuery(
   api.tasks.listPaginated,
   {},
-  { initialNumItems: 20 },
+  { initialNumItems: 20, authenticated: true },
 )
+// loadMore() when status === 'CanLoadMore'
 ```
 
 The first page is SSR'd. On the browser, every loaded page stays live. `loadMore` fetches the next page.
@@ -115,10 +120,10 @@ const { mutate, pending, error } = useConvexMutation(api.tasks.create, {
     ])
   },
 })
-await mutate({ text: 'Ship it' })
+await mutate({ text: 'Ship it' }) // browser-only
 
-const { run } = useConvexAction(api.ai.summarize)
-await run({ text: '…' })
+const { run, pending, error } = useConvexAction(api.tasks.shout)
+const shouted = await run({ text: 'hello' }) // browser-only
 ```
 
 For paginated lists:
@@ -133,7 +138,48 @@ insertAtTop({
 
 Also available: `insertAtBottomIfLoaded`, `insertAtPosition`, `optimisticallyUpdateValueInPaginatedQuery`.
 
-`useConvex()` returns the browser `ConvexClient` when you need an escape hatch. `useConvexConnectionState()` is a reactive WebSocket `ConnectionState`.
+`useConvex()` returns the browser `ConvexClient` when you need an escape hatch. `useConvexConnectionState()` is a reactive `ShallowRef<ConnectionState | null>` (WebSocket status: `isWebSocketConnected`, `hasInflightRequests`, …).
+
+## File uploads
+
+Convex file storage is a three-step client flow: generate a short-lived upload URL, `POST` the file bytes, then save the returned `storageId` in a mutation. `useConvexFileUpload` wraps that for Nuxt (browser-only, with `pending` / `error` / `progress`).
+
+```ts
+const { upload, pending, error, progress } = useConvexFileUpload({
+  generateUploadUrl: api.files.generateUploadUrl,
+  saveFile: api.files.save, // ({ storageId, name, contentType, size, ... }) => Id<"files">
+})
+
+await upload(file) // progress: 0..1 while bytes fly
+// optional extra save args: await upload(file, { caption: '…' })
+```
+
+Your Convex mutations must enforce auth — never expose an unauthenticated `generateUploadUrl`. Prefer storing `storageId` (and resolving URLs with `ctx.storage.getUrl`) over persisting raw public URLs. See the playground `files` module and the `/files` page for a full list/upload/delete example.
+
+### Cloudflare R2 (`@convex-dev/r2`)
+
+For larger objects or R2-backed apps, use `useConvexR2Upload` — the Vue counterpart of `@convex-dev/r2/react`'s `useUploadFile`. It does not depend on the R2 package at runtime; pass the `clientApi()` exports from your Convex app:
+
+```ts
+// convex/r2.ts
+import { R2 } from '@convex-dev/r2'
+import { components } from './_generated/api'
+
+const r2 = new R2(components.r2)
+export const { generateUploadUrl, syncMetadata } = r2.clientApi({
+  checkUpload: async (ctx) => {
+    /* auth */
+  },
+})
+```
+
+```ts
+// Pass r2.clientApi() exports: { generateUploadUrl, syncMetadata }
+const { upload, pending, error, progress } = useConvexR2Upload(api.r2)
+const key = await upload(file) // R2 object key
+```
+
+That runs `generateUploadUrl` → `PUT` to the signed URL → `syncMetadata({ key })`, with XHR progress. Use built-in `useConvexFileUpload` for Convex storage; use this helper when you adopt the R2 component.
 
 ## Auth
 
@@ -158,6 +204,7 @@ const { signIn, signOut } = useAuth()
 
 <template>
   <AuthLoading>Resolving…</AuthLoading>
+  <AuthRefreshing>Refreshing session…</AuthRefreshing>
   <Authenticated>
     <!-- signed-in shell -->
   </Authenticated>
@@ -167,7 +214,7 @@ const { signIn, signOut } = useAuth()
 </template>
 ```
 
-Prefer `<Authenticated>` (or `showAuthedUi`) so SSR HTML does not flash the sign-in form. Gate private queries with `{ authenticated: true }`.
+Prefer `<Authenticated>` (or `showAuthedUi`) so SSR HTML does not flash the sign-in form. Gate private queries with `{ authenticated: true }`. `<AuthRefreshing>` shows only while an authenticated session is refreshing a rejected token (same as React).
 
 ```ts
 await signIn('password', { email, password, flow: 'signIn' })
@@ -214,7 +261,7 @@ export default defineNuxtRouteMiddleware(() => {
 })
 ```
 
-`useAuthToken()` returns the current JWT for authenticated HTTP calls. `useConvexGate()` exposes `{ showAuthedUi, showLoading, showSignedOut, showRefreshing }` if you prefer flags over layout components.
+`useAuthToken()` returns the current JWT for authenticated HTTP calls. `useConvexGate()` exposes `{ showAuthedUi, showLoading, showSignedOut, showRefreshing }` if you prefer flags over layout components (`Authenticated` / `Unauthenticated` / `AuthLoading` / `AuthRefreshing`).
 
 ### Bring your own (Clerk, Auth0, custom)
 
@@ -236,7 +283,9 @@ const { data } = await useConvexQuery(api.tasks.list, {}, { authenticated: true
 Optional SSR cookie (you must write the JWT after sign-in):
 
 ```ts
-auth: { cookie: 'convex_jwt' }
+auth: {
+  cookie: 'convex_jwt'
+}
 ```
 
 ## Server routes
@@ -260,6 +309,15 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
+```ts
+// server/api/shout.post.ts
+export default defineEventHandler(async (event) => {
+  requireConvexAuth(event)
+  const { text } = await readBody(event)
+  return await fetchAction(api.tasks.shout, { text }, { event })
+})
+```
+
 `fetchAction` uses the same options. Each helper builds a fresh `ConvexHttpClient`. Override with `{ token }` when you already have a JWT. `getConvexToken(event)` reads the cookie without throwing.
 
 ## Config
@@ -280,6 +338,19 @@ convex: {
 
 `url` also reads `NUXT_PUBLIC_CONVEX_URL` via `runtimeConfig.public.convex.url`, so you can change the deployment without rebuilding.
 
+## Nuxt DevTools
+
+In development, a **Convex** tab appears in [Nuxt DevTools](https://devtools.nuxt.com). It embeds the official [hosted dashboard](https://docs.convex.dev/platform-apis/embedded-dashboard) for `*.convex.cloud` URLs and shows module config / tips.
+
+- **Open dashboard** deep-links to `dashboard.convex.dev` (uses your existing Convex login).
+- **Auto-login** in the embed needs `CONVEX_DEPLOY_KEY` in the Nuxt process environment (e.g. `.env.local`). Without it, the iframe shows Convex’s credential form.
+- A deploy key inlined into the DevTools page is visible to anyone who can reach your local `nuxt dev` server — only set it for trusted local machines.
+- Local / self-hosted backends are not embedded; use the Open dashboard link or the CLI dashboard instead.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Lint/format/test use **Vite+** (`vp`) — Oxlint, Oxfmt, and Vitest — while Nuxt module build/dev stay on `nuxt-module-build` / `nuxi`.
+
 ## Playground
 
 `playground/` is a normal Nuxt app that consumes this module (workspace-linked).
@@ -287,7 +358,7 @@ convex: {
 ```bash
 pnpm install
 
-# Terminal 1 — Convex backend (writes NUXT_PUBLIC_CONVEX_URL to .env.local)
+# Terminal 1 — Convex backend (writes CONVEX_URL to playground/.env.local)
 pnpm run dev:backend
 # first time: npx @convex-dev/auth   # JWT_PRIVATE_KEY + JWKS
 
@@ -295,27 +366,36 @@ pnpm run dev:backend
 pnpm run dev
 ```
 
-| Route | What it shows |
-|---|---|
-| `/` | SSR snapshot + live overlay (sign up, CRUD todos) |
-| `/server` | Nitro `fetchQuery` / `fetchMutation` / `fetchAction` |
-| `/extras` | `live: false`, pagination, action, connection state |
+| Route     | What it shows                                         |
+| --------- | ----------------------------------------------------- |
+| `/`       | Shell session: features + composable call-shape demos |
+| `/live`   | SSR snapshot + live overlay (sign up, CRUD todos)     |
+| `/server` | Nitro `fetchQuery` / `fetchMutation` / `fetchAction`  |
+| `/files`  | `useConvexFileUpload` (upload, list, preview, delete) |
+| `/extras` | `live: false`, pagination, action, connection state   |
 
 On `/server`: `GET /api/health` is public; `GET`/`POST /api/tasks` use the cookie JWT; `POST /api/shout` is a public `fetchAction` demo.
 
 ## Releasing
 
-Releases run from `.github/workflows/release.yml` when commits land on `main`. Version bumps follow [conventional commits](https://www.conventionalcommits.org/):
+Releases run from `.github/workflows/release.yml` when commits that touch `src/` land on `main` (or when the workflow is run manually). Version bumps follow [conventional commits](https://www.conventionalcommits.org/):
 
-| Commit | Release |
-|---|---|
-| `fix:` | patch |
-| `feat:` | minor |
-| `feat!:` or `BREAKING CHANGE:` | major |
-| `chore:`, `docs:`, `ci:`, … | none |
+| Commit                         | Release |
+| ------------------------------ | ------- |
+| `feat!:` or `BREAKING CHANGE:` | major   |
+| `feat:`                        | minor   |
+| anything else under `src/`     | patch   |
 
 semantic-release publishes `use-convex` to npm, tags `vX.Y.Z`, and opens a GitHub Release. The repo `package.json` version is not committed back.
 
+Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC), not an `NPM_TOKEN`. On [the `use-convex` package settings](https://www.npmjs.com/package/use-convex?activeTab=settings) add a GitHub Actions trusted publisher:
+
+- **Organization or user:** `jrmybtlr`
+- **Repository:** `convex-nuxt`
+- **Workflow filename:** `release.yml`
+- **Environment:** leave empty
+- **Allowed actions:** include **`npm publish`** (new publishers default to staged publish only)
+
 ## License
 
 MIT

package/dist/module.d.mts

@@ -3,9 +3,11 @@ import * as convex_browser from 'convex/browser';
 export { AuthTokens, SignInResult, UseAuthReturn } from '../dist/runtime/composables/useAuth.js';
 export { ConvexQueryArgs, UseConvexQueryOptions, UseConvexQueryReturn } from '../dist/runtime/composables/useConvexQuery.js';
 export { AuthTokenFetcher, UseConvexAuthReturn, UseConvexAuthSetupOptions } from '../dist/runtime/composables/useConvexAuth.js';
-export { UseConvexMutationOptions } from '../dist/runtime/composables/useConvexMutation.js';
-export { PaginatedQueryReference, PaginationStatus, UseConvexPaginatedQueryOptions, UseConvexPaginatedQueryReturn } from '../dist/runtime/composables/useConvexPaginatedQuery.js';
-export { ConvexQueriesRequest, ConvexQueriesResult } from '../dist/runtime/composables/useConvexQueries.js';
+export { OptimisticUpdate, UseConvexMutationOptions } from '../dist/runtime/composables/useConvexMutation.js';
+export { ConvexFileUploadExtraArgs, ConvexFileUploadMeta, UseConvexFileUploadOptions } from '../dist/runtime/composables/useConvexFileUpload.js';
+export { ConvexR2UploadApi, ConvexR2UploadProgress } from '../dist/runtime/composables/useConvexR2Upload.js';
+export { PaginatedQueryArgs, PaginatedQueryItem, PaginatedQueryReference, PaginationStatus, UseConvexPaginatedQueryOptions, UseConvexPaginatedQueryReturn } from '../dist/runtime/composables/useConvexPaginatedQuery.js';
+export { ConvexQueriesRequest, ConvexQueriesResult, ConvexQueryRequestEntry } from '../dist/runtime/composables/useConvexQueries.js';
 export { ConvexFetchOptions } from '../dist/runtime/server/fetch.js';
 export { ConvexAuthContext, ConvexNuxtContext } from '../dist/runtime/utils/context.js';
 export { ConnectionState } from '../dist/runtime/composables/useConvexConnectionState.js';

package/dist/module.mjs

@@ -1,6 +1,8 @@
 import { defineNuxtModule, createResolver, addPlugin, addComponent, addServerScanDir, addServerHandler, addImports, addServerImports, addTypeTemplate } from '@nuxt/kit';
 import { defu } from 'defu';
 import { resolveAuthCookieName } from '../dist/runtime/utils/authStorage.js';
+import { suggestedCloudUrlFromMismatch } from '../dist/runtime/utils/convexDashboard.js';
+import { warnStaleLocalConvexUrl } from '../dist/runtime/utils/errors.js';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -26,6 +28,25 @@ const module$1 = defineNuxtModule({
       client: options.client,
       auth
     });
+    if (nuxt.options.dev) {
+      const publicUrl = nuxt.options.runtimeConfig.public.convex?.url ?? "";
+      const suggestedCloudUrl = suggestedCloudUrlFromMismatch(
+        publicUrl,
+        process.env.CONVEX_DEPLOYMENT
+      );
+      if (suggestedCloudUrl) {
+        warnStaleLocalConvexUrl(publicUrl, suggestedCloudUrl);
+      }
+      nuxt.options.runtimeConfig.convexDevtools = defu(
+        nuxt.options.runtimeConfig.convexDevtools ?? {},
+        {
+          deployKey: process.env.CONVEX_DEPLOY_KEY ?? "",
+          deployment: process.env.CONVEX_DEPLOYMENT ?? "",
+          // Fallback when public.convex.url was empty at config eval time.
+          url: process.env.NUXT_PUBLIC_CONVEX_URL ?? process.env.CONVEX_URL ?? ""
+        }
+      );
+    }
     const resolver = createResolver(import.meta.url);
     const runtimeDir = resolver.resolve("./runtime");
     const useConvexAuthProvider = auth?.provider === "convex-auth";
@@ -57,7 +78,12 @@ const module$1 = defineNuxtModule({
         mode: "client"
       });
     }
-    for (const name of ["Authenticated", "Unauthenticated", "AuthLoading"]) {
+    for (const name of [
+      "Authenticated",
+      "Unauthenticated",
+      "AuthLoading",
+      "AuthRefreshing"
+    ]) {
       addComponent({
         name,
         filePath: resolver.resolve(`./runtime/components/${name}.vue`)
@@ -103,6 +129,14 @@ const module$1 = defineNuxtModule({
         name: "useConvexMutation",
         from: resolver.resolve("./runtime/composables/useConvexMutation")
       },
+      {
+        name: "useConvexFileUpload",
+        from: resolver.resolve("./runtime/composables/useConvexFileUpload")
+      },
+      {
+        name: "useConvexR2Upload",
+        from: resolver.resolve("./runtime/composables/useConvexR2Upload")
+      },
       {
         name: "useConvexAction",
         from: resolver.resolve("./runtime/composables/useConvexAction")

package/dist/runtime/composables/useAuth.d.ts

@@ -43,17 +43,17 @@ export declare function signIn(provider?: string, params?: FormData | Record<str
  * Sign out and clear local tokens + SSR JWT cookie.
  */
 export declare function signOut(): Promise<void>;
-/** @internal Used by the Convex Auth client plugin. */
+/** @internal */
 export declare function hydrateAuthFromStorage(): void;
-/** @internal Token fetcher for `useConvexAuth({ fetchToken })`. */
+/** @internal */
 export declare function getAuthToken({ forceRefreshToken, }: {
     forceRefreshToken: boolean;
 }): Promise<string | null>;
-/** @internal Sync check for OAuth `?code=` + stored verifier (no await). */
+/** @internal */
 export declare function hasPendingOAuthCallback(): boolean;
-/** @internal Used by the Convex Auth client plugin. */
+/** @internal */
 export declare function consumeOAuthCodeFromUrl(): Promise<boolean>;
-/** @internal Provider session flags for `useConvexAuth`. */
+/** @internal */
 export declare function useAuthProviderState(): {
     isLoading: ComputedRef<boolean>;
     hasSession: ComputedRef<boolean>;

package/dist/runtime/composables/useAuth.js

@@ -1,19 +1,11 @@
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
-import {
-  computed,
-  nextTick
-} from "vue";
-import {
-  useRuntimeConfig,
-  useState
-} from "nuxt/app";
+import { computed, nextTick } from "vue";
+import { useRuntimeConfig, useState } from "nuxt/app";
 import { useConvexAuth } from "./useConvexAuth.js";
+import { missingConvexUrlError, unreachableConvexUrlError } from "../utils/errors.js";
 import { withRefreshMutex } from "../utils/authMutex.js";
-import {
-  useAuthJwtCookie,
-  useAuthPresentCookie
-} from "../utils/authCookie.js";
+import { useAuthJwtCookie, useAuthPresentCookie } from "../utils/authCookie.js";
 import {
   flattenSignInParams,
   isHttpOnlyAuth,
@@ -28,9 +20,7 @@ import {
 import { tryUseConvexContext } from "../utils/context.js";
 import { parseOAuthRedirect } from "../utils/oauthRedirect.js";
 const authSignIn = makeFunctionReference("auth:signIn");
-const authSignOut = makeFunctionReference(
-  "auth:signOut"
-);
+const authSignOut = makeFunctionReference("auth:signOut");
 const RETRY_BACKOFF = [500, 2e3];
 const RETRY_JITTER = 100;
 export function useAuth() {
@@ -65,7 +55,7 @@ export async function signIn(provider, params) {
   const session = useAuthSession();
   const convexUrl = session.convexUrl;
   if (!convexUrl) {
-    throw new Error("Convex URL is not configured");
+    throw missingConvexUrlError("signIn");
   }
   session.pending.value = true;
   session.error.value = null;
@@ -94,7 +84,7 @@ export async function signIn(provider, params) {
     }
     return { signingIn: false };
   } catch (cause) {
-    const message = cause instanceof Error ? cause.message : "Authentication failed";
+    const message = isNetworkError(cause) && convexUrl ? unreachableConvexUrlError(convexUrl).message : cause instanceof Error ? cause.message : "Authentication failed";
     session.error.value = message;
     throw cause;
   } finally {
@@ -319,13 +309,10 @@ async function fetchAuthSession() {
 }
 async function fetchAuthSessionToken() {
   try {
-    return await $fetch(
-      AUTH_SESSION_PATH,
-      {
-        method: "POST",
-        body: { getToken: true }
-      }
-    );
+    return await $fetch(AUTH_SESSION_PATH, {
+      method: "POST",
+      body: { getToken: true }
+    });
   } catch {
     return { hasSession: false, token: null };
   }

package/dist/runtime/composables/useAuthToken.d.ts

@@ -21,4 +21,4 @@ export declare function useAuthToken(): ComputedRef<string | null>;
  */
 export declare function requireConvexAuthMiddleware(options?: {
     redirectTo?: string;
-}): ReturnType<typeof navigateTo> | void;
+}): ReturnType<typeof navigateTo> | undefined;

package/dist/runtime/composables/useAuthToken.js

@@ -1,9 +1,5 @@
 import { navigateTo } from "nuxt/app";
-import {
-  computed,
-  ref,
-  watch
-} from "vue";
+import { computed, ref, watch } from "vue";
 import { useConvexAuth } from "./useConvexAuth.js";
 import { tryUseConvexContext } from "../utils/context.js";
 export function useAuthToken() {
@@ -42,11 +38,7 @@ export function useAuthToken() {
     }
   };
   watch(
-    [
-      () => auth.isAuthenticated.value,
-      () => auth.isRefreshing.value,
-      () => auth.isLoading.value
-    ],
+    [() => auth.isAuthenticated.value, () => auth.isRefreshing.value, () => auth.isLoading.value],
     () => {
       void refresh();
     },

package/dist/runtime/composables/useConvex.js

@@ -3,7 +3,7 @@ export function useConvex() {
   const ctx = useConvexContext();
   if (!ctx.client) {
     throw new Error(
-      "[convex-nuxt] useConvex() is only available in the browser. Use fetchQuery on the server."
+      "[use-convex] useConvex() is only available in the browser. Use fetchQuery on the server."
     );
   }
   return ctx.client;

package/dist/runtime/composables/useConvexAction.js

@@ -1,30 +1,18 @@
-import { computed, ref, toValue } from "vue";
+import { toValue } from "vue";
 import { useConvexContext } from "../utils/context.js";
+import { createPendingErrorState } from "../utils/pendingError.js";
 export function useConvexAction(action) {
   const ctx = useConvexContext();
-  const error = ref(null);
-  const pendingCount = ref(0);
+  const { error, pending, withPending } = createPendingErrorState();
   const run = async (args = {}) => {
     if (import.meta.server || !ctx.client) {
-      throw new Error(
-        "[convex-nuxt] useConvexAction can only run in the browser."
-      );
-    }
-    pendingCount.value++;
-    error.value = null;
-    try {
-      return await ctx.client.action(action, toValue(args));
-    } catch (cause) {
-      const err = cause instanceof Error ? cause : new Error(String(cause));
-      error.value = err;
-      throw err;
-    } finally {
-      pendingCount.value--;
+      throw new Error("[use-convex] useConvexAction can only run in the browser.");
     }
+    return await withPending(() => ctx.client.action(action, toValue(args)));
   };
   return {
     run,
     error,
-    pending: computed(() => pendingCount.value > 0)
+    pending
   };
 }

package/dist/runtime/composables/useConvexAuth.js

@@ -1,8 +1,4 @@
-import {
-  computed,
-  toValue,
-  watch
-} from "vue";
+import { computed, toValue, watch } from "vue";
 import { useHasSsrSessionRef } from "../utils/authCookie.js";
 import { useConvexContext } from "../utils/context.js";
 import { resolveConvexAuthState } from "../utils/authState.js";
@@ -10,9 +6,7 @@ export function useConvexAuth(setup) {
   const ctx = useConvexContext();
   const auth = ctx.auth;
   const hasSsrSession = useHasSsrSessionRef();
-  const showAuthedUi = computed(
-    () => auth.isAuthenticated.value || hasSsrSession.value
-  );
+  const showAuthedUi = computed(() => auth.isAuthenticated.value || hasSsrSession.value);
   if (setup) {
     if (import.meta.server) {
       return {
@@ -26,7 +20,7 @@ export function useConvexAuth(setup) {
     const client = ctx.client;
     if (!client) {
       throw new Error(
-        "[convex-nuxt] useConvexAuth({ fetchToken }) requires ConvexClient (browser only)."
+        "[use-convex] useConvexAuth({ fetchToken }) requires ConvexClient (browser only)."
       );
     }
     auth.fetchToken = setup.fetchToken;
@@ -67,10 +61,7 @@ export function useConvexAuth(setup) {
       );
     };
     watch(
-      () => [
-        toValue(setup.isLoading) ?? false,
-        toValue(setup.isAuthenticated) ?? true
-      ],
+      () => [toValue(setup.isLoading) ?? false, toValue(setup.isAuthenticated) ?? true],
       syncFromProvider,
       { immediate: true }
     );

package/dist/runtime/composables/useConvexFileUpload.d.ts

@@ -0,0 +1,43 @@
+import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+/** Built-in fields the composable always passes into `saveFile`. */
+export type ConvexFileUploadMeta = {
+    storageId: string;
+    name: string;
+    contentType: string;
+    size: number;
+};
+export type ConvexFileUploadExtraArgs<SaveFile extends FunctionReference<'mutation'>> = Omit<FunctionArgs<SaveFile>, 'storageId' | 'name' | 'contentType' | 'size'>;
+export interface UseConvexFileUploadOptions<GenerateUploadUrl extends FunctionReference<'mutation'>, SaveFile extends FunctionReference<'mutation'>> {
+    /**
+     * Mutation that returns a short-lived Convex upload URL
+     * (`ctx.storage.generateUploadUrl()`). Must enforce auth itself.
+     */
+    generateUploadUrl: GenerateUploadUrl;
+    /**
+     * Mutation that persists `storageId` + file metadata after the POST succeeds.
+     * Must accept at least `storageId`, `name`, `contentType`, and `size`.
+     */
+    saveFile: SaveFile;
+}
+/**
+ * POST a file to a Convex-generated upload URL with upload progress.
+ * Convex expects `Content-Type` matching the file and returns `{ storageId }`.
+ */
+export declare function postFileToUploadUrl(uploadUrl: string, file: File, onProgress?: (fraction: number) => void): Promise<string>;
+/**
+ * Browser helper for Convex's three-step file upload flow:
+ * generate upload URL → POST file → save `storageId` via mutation.
+ *
+ * Returns `{ upload, pending, error, progress }`. `progress` is `0..1` while
+ * the bytes are in flight, otherwise `null`.
+ *
+ * Safe to call during SSR setup — work only runs when `upload()` is invoked
+ * in the browser. Your Convex mutations must enforce auth; never expose an
+ * unauthenticated `generateUploadUrl`.
+ */
+export declare function useConvexFileUpload<GenerateUploadUrl extends FunctionReference<'mutation'>, SaveFile extends FunctionReference<'mutation'>>(options: UseConvexFileUploadOptions<GenerateUploadUrl, SaveFile>): {
+    upload: (file: File, extra?: ConvexFileUploadExtraArgs<SaveFile> extends Record<string, never> ? undefined : ConvexFileUploadExtraArgs<SaveFile>) => Promise<FunctionReturnType<SaveFile>>;
+    error: import("vue").Ref<Error | null, Error | null>;
+    pending: import("vue").ComputedRef<boolean>;
+    progress: import("vue").ComputedRef<number | null>;
+};