better-convex-nuxt 0.1.8 → 0.2.0

package/README.md

@@ -8,7 +8,12 @@
 Full-featured [Convex](https://convex.dev) integration for [Nuxt](https://nuxt.com) with SSR, real-time subscriptions, authentication, and permissions.
 
 - [Documentation](https://better-convex-nuxt.vercel.app)
-- [Online Playground](https://stackblitz.com/github/lupinum-dev/better-convex-nuxt?file=playground%2Fapp.vue)
+
+> [!NOTE]
+> **Work In Progress**
+> This module is rapidly evolving. While we are using it in our own apps, features and APIs are subject to change as we refine the best patterns for Nuxt + Convex.
+
+Contributions and PRs to help improve the library, playground or docs are highly appreciated! 🙏
 
 ## Features
 
@@ -24,7 +29,7 @@ Full-featured [Convex](https://convex.dev) integration for [Nuxt](https://nuxt.c
 Install the module:
 
 ```bash
-npx nuxi module add better-convex-nuxt
+pnpm add better-convex-nuxt
 ```
 
 Add your Convex URL to `.env`:
@@ -113,6 +118,8 @@ async function handleLogin() {
 | `useConvexMutation`        | Execute mutations with optimistic updates            |
 | `useConvexAction`          | Execute Convex actions                               |
 | `useConvexPaginatedQuery`  | Paginated queries with `loadMore()`                  |
+| `useConvexFileUpload`      | Upload files to Convex storage with progress         |
+| `useConvexStorageUrl`      | Get reactive URLs for stored files                   |
 | `useConvexAuth`            | Authentication state (user, token, isAuthenticated)  |
 | `useConvexConnectionState` | WebSocket connection status                          |
 | `useConvexCached`          | Read cached query data                               |
@@ -155,6 +162,10 @@ pnpm test
 pnpm lint
 ```
 
+## Acknowledgements
+
+- File upload composables inspired by [nuxt-convex](https://github.com/onmax/nuxt-convex) by [@onmax](https://github.com/onmax)
+
 ## License
 
 [MIT](./LICENSE)

package/dist/module.d.mts

@@ -1,16 +1,50 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
-interface BetterAuthOptions {
-    /** @deprecated Use siteUrl instead */
-    url?: string;
+interface LoggingOptions {
+    /**
+     * Enable module logging.
+     * - false: No logs (production default)
+     * - true: Info-level logs (canonical events only)
+     * - 'debug': Include debug-level details
+     * @default false
+     */
+    enabled?: boolean | 'debug';
+    /**
+     * Output format for logs.
+     * - 'pretty': Human-readable with icons (default)
+     * - 'json': Structured JSON for log aggregation
+     * @default 'pretty'
+     */
+    format?: 'pretty' | 'json';
+}
+interface AuthCacheOptions {
+    /**
+     * Enable SSR auth token caching.
+     * When enabled, Convex JWT tokens are cached to reduce TTFB on subsequent SSR requests.
+     * Uses Nitro Storage (memory by default, configurable to Redis for multi-instance deployments).
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Cache TTL in seconds.
+     * Determines how long tokens are cached before requiring a fresh fetch.
+     * Shorter TTL = more security, longer TTL = better performance.
+     * @default 900 (15 minutes)
+     */
+    ttl?: number;
 }
 interface ModuleOptions {
     /** Convex deployment URL (WebSocket) - e.g., https://your-app.convex.cloud */
     url?: string;
     /** Convex site URL (HTTP/Auth) - e.g., https://your-app.convex.site. Auto-derived from url if not set. */
     siteUrl?: string;
-    /** @deprecated Use siteUrl instead */
-    auth?: BetterAuthOptions;
+    /**
+     * Additional trusted origins for CORS validation on the auth proxy.
+     * By default, only requests from the origin matching siteUrl are allowed.
+     * Supports wildcards for preview deployments (e.g., 'https://preview-*.vercel.app').
+     * @default []
+     */
+    trustedOrigins?: string[];
     /**
      * Enable permission composables (createPermissions factory).
      * When true, auto-imports createPermissions for building usePermissions.
@@ -18,13 +52,39 @@ interface ModuleOptions {
      */
     permissions?: boolean;
     /**
-     * Enable verbose logging for debugging.
-     * When true, logs detailed information about queries, mutations, auth, and SSR operations.
-     * @default false
+     * Configure module logging behavior.
+     * Emits canonical log events for debugging SSR, auth, queries, and mutations.
+     */
+    logging?: LoggingOptions;
+    /**
+     * SSR auth token caching configuration (opt-in).
+     * Caches Convex JWT tokens server-side to reduce TTFB on subsequent requests.
+     *
+     * @example
+     * ```ts
+     * // nuxt.config.ts
+     * export default defineNuxtConfig({
+     *   convex: {
+     *     authCache: {
+     *       enabled: true,
+     *       ttl: 900 // 15 minutes
+     *     }
+     *   },
+     *   // For multi-instance deployments, configure Redis:
+     *   nitro: {
+     *     storage: {
+     *       'cache:convex:auth': {
+     *         driver: 'redis',
+     *         url: process.env.REDIS_URL
+     *       }
+     *     }
+     *   }
+     * })
+     * ```
      */
-    verbose?: boolean;
+    authCache?: AuthCacheOptions;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { BetterAuthOptions, ModuleOptions };
+export type { AuthCacheOptions, LoggingOptions, ModuleOptions };

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0"
   },
-  "version": "0.1.8",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,6 +1,15 @@
-import { defineNuxtModule, createResolver, addPlugin, addServerHandler, addTemplate, addImports, addServerImports, addComponentsDir } from '@nuxt/kit';
+import { useLogger, defineNuxtModule, createResolver, addPlugin, addServerHandler, addTemplate, addImports, addServerImports, addComponentsDir } from '@nuxt/kit';
 import { defu } from 'defu';
 
+const logger = useLogger("better-convex-nuxt");
+function isValidUrl(url) {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
 const module$1 = defineNuxtModule({
   meta: {
     name: "better-convex-nuxt",
@@ -12,21 +21,40 @@ const module$1 = defineNuxtModule({
   defaults: {
     url: process.env.CONVEX_URL,
     siteUrl: process.env.CONVEX_SITE_URL,
+    trustedOrigins: [],
     permissions: false,
-    verbose: false
+    logging: {
+      enabled: false,
+      format: "pretty"
+    },
+    authCache: {
+      enabled: false,
+      ttl: 900
+      // 15 minutes
+    }
   },
   setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
-    const derivedSiteUrl = options.siteUrl || options.auth?.url || (options.url?.replace(".convex.cloud", ".convex.site") ?? "");
+    if (options.url && !isValidUrl(options.url)) {
+      logger.warn(`Invalid Convex URL format: "${options.url}". Expected a valid URL like "https://your-app.convex.cloud"`);
+    }
+    if (options.siteUrl && !isValidUrl(options.siteUrl)) {
+      logger.warn(`Invalid Convex site URL format: "${options.siteUrl}". Expected a valid URL like "https://your-app.convex.site"`);
+    }
+    const derivedSiteUrl = options.siteUrl || (options.url?.replace(".convex.cloud", ".convex.site") ?? "");
     const convexConfig = defu(
       nuxt.options.runtimeConfig.public.convex,
       {
         url: options.url || "",
         siteUrl: derivedSiteUrl,
-        verbose: options.verbose ?? false,
-        // Keep auth.url for backwards compatibility
-        auth: {
-          url: options.auth?.url || derivedSiteUrl
+        trustedOrigins: options.trustedOrigins ?? [],
+        logging: {
+          enabled: options.logging?.enabled ?? false,
+          format: options.logging?.format ?? "pretty"
+        },
+        authCache: {
+          enabled: options.authCache?.enabled ?? false,
+          ttl: options.authCache?.ttl ?? 900
         }
       }
     );
@@ -75,12 +103,7 @@ export {}
       { name: "useConvexAction", from: resolver.resolve("./runtime/composables/useConvexAction") },
       { name: "useAuthClient", from: resolver.resolve("./runtime/composables/useAuthClient") },
       { name: "useConvexQuery", from: resolver.resolve("./runtime/composables/useConvexQuery") },
-      { name: "useConvexCached", from: resolver.resolve("./runtime/composables/useConvexCached") },
-      { name: "useConvexData", from: resolver.resolve("./runtime/composables/useConvexData") },
-      {
-        name: "useLazyConvexQuery",
-        from: resolver.resolve("./runtime/composables/useLazyConvexQuery")
-      },
+      { name: "getQueryKey", from: resolver.resolve("./runtime/composables/useConvexQuery") },
       {
         name: "useConvexPaginatedQuery",
         from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
@@ -120,6 +143,15 @@ export {}
       {
         name: "deleteFromPaginatedQuery",
         from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
+      },
+      // File upload composables
+      {
+        name: "useConvexFileUpload",
+        from: resolver.resolve("./runtime/composables/useConvexFileUpload")
+      },
+      {
+        name: "useConvexStorageUrl",
+        from: resolver.resolve("./runtime/composables/useConvexStorageUrl")
       }
     ]);
     if (options.permissions) {
@@ -133,7 +165,8 @@ export {}
     addServerImports([
       { name: "fetchQuery", from: resolver.resolve("./runtime/server/utils/convex") },
       { name: "fetchMutation", from: resolver.resolve("./runtime/server/utils/convex") },
-      { name: "fetchAction", from: resolver.resolve("./runtime/server/utils/convex") }
+      { name: "fetchAction", from: resolver.resolve("./runtime/server/utils/convex") },
+      { name: "clearAuthCache", from: resolver.resolve("./runtime/server/utils/auth-cache") }
     ]);
     addComponentsDir({
       path: resolver.resolve("./runtime/components"),
@@ -144,7 +177,33 @@ export {}
         path: resolver.resolve(nuxt.options.buildDir, "types/better-convex-nuxt.d.ts")
       });
     });
+    if (nuxt.options.dev) {
+      setupDevTools(nuxt, resolver);
+    }
   }
 });
+async function setupDevTools(nuxt, resolver) {
+  try {
+    const { addCustomTab } = await import('@nuxt/devtools-kit');
+    addCustomTab({
+      name: "convex",
+      title: "Convex",
+      icon: "carbon:data-base",
+      category: "app",
+      view: {
+        type: "iframe",
+        src: "/__convex_devtools__",
+        persistent: true
+      }
+    }, nuxt);
+    addServerHandler({
+      route: "/__convex_devtools__",
+      handler: resolver.resolve("./runtime/devtools/server")
+    });
+    logger.info("Nuxt DevTools integration enabled");
+  } catch {
+    logger.debug("Nuxt DevTools integration skipped (devtools-kit not available)");
+  }
+}
 
 export { module$1 as default };

package/dist/runtime/components/ConvexAuthError.d.vue.ts

@@ -0,0 +1,19 @@
+/**
+ * Retry authentication by reloading the page
+ */
+declare function retry(): void;
+declare var __VLS_1: {
+    retry: typeof retry;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/ConvexAuthError.vue

@@ -0,0 +1,18 @@
+<script setup>
+import { computed } from "vue";
+import { useConvexAuth } from "../composables/useConvexAuth";
+const { isAuthenticated, isPending, token, user } = useConvexAuth();
+const hasError = computed(() => {
+  if (isPending.value) return false;
+  if (isAuthenticated.value) return false;
+  if (token.value && !user.value) return true;
+  return false;
+});
+function retry() {
+  window.location.reload();
+}
+</script>
+
+<template>
+  <slot v-if="hasError" :retry="retry" />
+</template>

package/dist/runtime/components/ConvexAuthError.vue.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Retry authentication by reloading the page
+ */
+declare function retry(): void;
+declare var __VLS_1: {
+    retry: typeof retry;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -1,11 +1,12 @@
-export { useConvexAuth } from './useConvexAuth.js';
+export { useConvexAuth, type ConvexUser } from './useConvexAuth.js';
 export { useConvex } from './useConvex.js';
-export { useConvexConnectionState, type ConnectionState, type UseConvexConnectionStateOptions, } from './useConvexConnectionState.js';
+export { useConvexConnectionState, type ConnectionState, } from './useConvexConnectionState.js';
 export { useConvexMutation, type MutationStatus, type UseConvexMutationReturn, type UseConvexMutationOptions, updateQuery, setQueryData, updateAllQueries, deleteFromQuery, type UpdateQueryOptions, type SetQueryDataOptions, type UpdateAllQueriesOptions, type DeleteFromQueryOptions, } from './useConvexMutation.js';
 export type { OptimisticLocalStore } from 'convex/browser';
-export { useConvexAction, type ActionStatus, type UseConvexActionReturn, type UseConvexActionOptions, } from './useConvexAction.js';
+export { useConvexAction, type ActionStatus, type UseConvexActionReturn, } from './useConvexAction.js';
 export { useAuthClient } from './useAuthClient.js';
-export { useConvexQuery, type QueryStatus, type UseConvexQueryReturn, type UseConvexQueryData, type UseConvexQueryOptions, } from './useConvexQuery.js';
-export { useConvexCached } from './useConvexCached.js';
+export { useConvexQuery, getQueryKey, type QueryStatus, type UseConvexQueryOptions, } from './useConvexQuery.js';
 export { useConvexPaginatedQuery, type PaginationStatus, type UseConvexPaginatedQueryOptions, type UseConvexPaginatedQueryReturn, type PaginatedQueryReference, type PaginatedQueryArgs, type PaginatedQueryItem, insertAtTop, insertAtPosition, insertAtBottomIfLoaded, optimisticallyUpdateValueInPaginatedQuery, deleteFromPaginatedQuery, type InsertAtTopOptions, type InsertAtPositionOptions, type InsertAtBottomIfLoadedOptions, type UpdateInPaginatedQueryOptions, type DeleteFromPaginatedQueryOptions, } from './useConvexPaginatedQuery.js';
+export { useConvexFileUpload, type UploadStatus, type UseConvexFileUploadReturn, type UseConvexFileUploadOptions, } from './useConvexFileUpload.js';
+export { useConvexStorageUrl } from './useConvexStorageUrl.js';
 export { createPermissions, type PermissionContext, type Resource, type CheckPermissionFn, type CreatePermissionsOptions, type UsePermissionsReturn, type UsePermissionGuardOptions, } from './usePermissions.js';

package/dist/runtime/composables/index.js

@@ -15,9 +15,9 @@ export {
 } from "./useConvexAction.js";
 export { useAuthClient } from "./useAuthClient.js";
 export {
-  useConvexQuery
+  useConvexQuery,
+  getQueryKey
 } from "./useConvexQuery.js";
-export { useConvexCached } from "./useConvexCached.js";
 export {
   useConvexPaginatedQuery,
   insertAtTop,
@@ -26,6 +26,10 @@ export {
   optimisticallyUpdateValueInPaginatedQuery,
   deleteFromPaginatedQuery
 } from "./useConvexPaginatedQuery.js";
+export {
+  useConvexFileUpload
+} from "./useConvexFileUpload.js";
+export { useConvexStorageUrl } from "./useConvexStorageUrl.js";
 export {
   createPermissions
 } from "./usePermissions.js";

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

@@ -1,16 +1,5 @@
 import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
 import { type Ref, type ComputedRef } from 'vue';
-/**
- * Options for useConvexAction
- */
-export interface UseConvexActionOptions {
-    /**
-     * Enable verbose logging for debugging.
-     * Logs action lifecycle events: start, success, error.
-     * @default false
-     */
-    verbose?: boolean;
-}
 /**
  * Action status representing the current state of the action
  * - 'idle': not yet called or reset
@@ -102,4 +91,4 @@ export interface UseConvexActionReturn<Args, Result> {
  * </template>
  * ```
  */
-export declare function useConvexAction<Action extends FunctionReference<'action'>>(action: Action, options?: UseConvexActionOptions): UseConvexActionReturn<FunctionArgs<Action>, FunctionReturnType<Action>>;
+export declare function useConvexAction<Action extends FunctionReference<'action'>>(action: Action): UseConvexActionReturn<FunctionArgs<Action>, FunctionReturnType<Action>>;

package/dist/runtime/composables/useConvexAction.js

@@ -1,47 +1,114 @@
 import { ref, computed } from "vue";
-import { createActionLogger, getVerboseFlag } from "../utils/logger.js";
+import { useRuntimeConfig } from "#imports";
+import { getFunctionName } from "../utils/convex-cache.js";
+import { createModuleLogger, getLoggingOptions, createTimer, formatArgsPreview } from "../utils/logger.js";
 import { useConvex } from "./useConvex.js";
-export function useConvexAction(action, options) {
+let devToolsMutationRegistryPromise = null;
+let devToolsMutationRegistry = null;
+if (import.meta.client && import.meta.dev) {
+  devToolsMutationRegistryPromise = import("../devtools/mutation-registry.js");
+  devToolsMutationRegistryPromise.then((module) => {
+    devToolsMutationRegistry = module;
+  }).catch(() => {
+  });
+}
+export function useConvexAction(action) {
   const config = useRuntimeConfig();
-  const verbose = getVerboseFlag(config, options?.verbose);
-  const log = createActionLogger(verbose, "useConvexAction", action);
-  log("Initialized");
+  const loggingOptions = getLoggingOptions(config.public.convex ?? {});
+  const logger = createModuleLogger(loggingOptions);
+  const fnName = getFunctionName(action);
   const _status = ref("idle");
   const error = ref(null);
   const data = ref(void 0);
   const status = computed(() => _status.value);
   const pending = computed(() => _status.value === "pending");
   const reset = () => {
-    log("Reset");
     _status.value = "idle";
     error.value = null;
     data.value = void 0;
   };
   const execute = async (args) => {
     const client = useConvex();
+    const timer = createTimer();
     if (!client) {
-      const err = new Error(
-        "[bcn] ConvexClient not available - actions only work on client side"
-      );
-      log("Error: Client not available");
+      const err = new Error("ConvexClient not available - actions only work on client side");
       _status.value = "error";
       error.value = err;
+      logger.event({
+        event: "operation:complete",
+        env: "client",
+        type: "action",
+        name: fnName,
+        duration_ms: timer(),
+        outcome: "error",
+        error: { type: "ClientError", message: err.message }
+      });
       throw err;
     }
-    log("Starting action", args);
     _status.value = "pending";
     error.value = null;
+    const startTime = Date.now();
+    let actionId = null;
+    if (devToolsMutationRegistry) {
+      actionId = devToolsMutationRegistry.registerMutation({
+        name: fnName,
+        type: "action",
+        args,
+        state: "pending",
+        hasOptimisticUpdate: false,
+        startedAt: startTime
+      });
+    }
     try {
       const result = await client.action(action, args);
-      log("Success", result);
       _status.value = "success";
       data.value = result;
+      const settledAt = Date.now();
+      if (devToolsMutationRegistry && actionId) {
+        devToolsMutationRegistry.updateMutationState(actionId, {
+          state: "success",
+          result,
+          settledAt,
+          duration: settledAt - startTime
+        });
+      }
+      logger.event({
+        event: "operation:complete",
+        env: "client",
+        type: "action",
+        name: fnName,
+        duration_ms: timer(),
+        outcome: "success",
+        args_preview: formatArgsPreview(args)
+      });
       return result;
     } catch (e) {
       const err = e instanceof Error ? e : new Error(String(e));
-      log("Error", err.message);
       _status.value = "error";
       error.value = err;
+      const settledAt = Date.now();
+      if (devToolsMutationRegistry && actionId) {
+        devToolsMutationRegistry.updateMutationState(actionId, {
+          state: "error",
+          error: err.message,
+          settledAt,
+          duration: settledAt - startTime
+        });
+      }
+      logger.event({
+        event: "operation:complete",
+        env: "client",
+        type: "action",
+        name: fnName,
+        duration_ms: timer(),
+        outcome: "error",
+        args_preview: formatArgsPreview(args),
+        error: {
+          type: err.name,
+          message: err.message,
+          retriable: false
+        }
+      });
       throw err;
     }
   };

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

@@ -1,3 +1,4 @@
+export type { ConvexUser } from '../utils/types.js';
 /**
  * Composable for accessing Convex authentication state.
  *

package/dist/runtime/composables/useConvexAuth.js

@@ -1,21 +1,9 @@
-import { useState, computed, readonly, useRuntimeConfig } from "#imports";
-import { createLogger, getVerboseFlag } from "../utils/logger.js";
+import { useState, computed, readonly } from "#imports";
 export function useConvexAuth() {
   const token = useState("convex:token", () => null);
   const user = useState("convex:user", () => null);
   const isPending = useState("convex:pending", () => false);
   const isAuthenticated = computed(() => !!token.value && !!user.value);
-  const config = useRuntimeConfig();
-  const log = createLogger({
-    verbose: getVerboseFlag(config),
-    prefix: "[bcn:auth]"
-  });
-  log("useConvexAuth called", {
-    hasToken: !!token.value,
-    hasUser: !!user.value,
-    isAuthenticated: isAuthenticated.value,
-    isPending: isPending.value
-  });
   return {
     /** The JWT token for Convex authentication (readonly) */
     token: readonly(token),

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

@@ -19,17 +19,6 @@ export interface ConnectionState {
     /** Number of pending actions */
     inflightActions: number;
 }
-/**
- * Options for useConvexConnectionState
- */
-export interface UseConvexConnectionStateOptions {
-    /**
-     * Enable verbose logging for debugging.
-     * Logs connection state changes.
-     * @default false
-     */
-    verbose?: boolean;
-}
 /**
  * Monitor the Convex WebSocket connection state.
  * Useful for showing offline/reconnecting UI.
@@ -47,7 +36,7 @@ export interface UseConvexConnectionStateOptions {
  * </template>
  * ```
  */
-export declare function useConvexConnectionState(options?: UseConvexConnectionStateOptions): {
+export declare function useConvexConnectionState(): {
     /** Full connection state object */
     state: Readonly<import("vue").Ref<{
         readonly hasInflightRequests: boolean;