better-convex-nuxt 0.2.7 → 0.2.9

package/dist/module.d.mts

@@ -44,6 +44,24 @@ interface QueryDefaults {
      */
     public?: boolean;
 }
+interface ConvexDebugOptions {
+    /**
+     * Enable detailed auth flow logs on both client and server plugins.
+     * Requires `logging: 'debug'` to print verbose phase logs.
+     * @default false
+     */
+    authFlow?: boolean;
+    /**
+     * Enable detailed auth flow logs on the client plugin only.
+     * @default false
+     */
+    clientAuthFlow?: boolean;
+    /**
+     * Enable detailed auth flow logs on the server plugin only.
+     * @default false
+     */
+    serverAuthFlow?: boolean;
+}
 interface ModuleOptions {
     /** Convex deployment URL (WebSocket) - e.g., https://your-app.convex.cloud */
     url?: string;
@@ -99,6 +117,12 @@ interface ModuleOptions {
      * @default false
      */
     logging?: LogLevel;
+    /**
+     * Optional debug channels for runtime plugins.
+     * Use this to enable high-verbosity trace logs without changing regular logger behavior.
+     * @default { authFlow: false, clientAuthFlow: false, serverAuthFlow: false }
+     */
+    debug?: ConvexDebugOptions;
     /**
      * SSR auth token caching configuration (opt-in).
      * Caches Convex JWT tokens server-side to reduce TTFB on subsequent requests.
@@ -148,4 +172,4 @@ interface ModuleOptions {
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { AuthCacheOptions, ModuleOptions, QueryDefaults };
+export type { AuthCacheOptions, ConvexDebugOptions, ModuleOptions, QueryDefaults };

package/dist/module.json

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

package/dist/module.mjs

@@ -35,6 +35,11 @@ const module$1 = defineNuxtModule({
     skipAuthRoutes: [],
     permissions: false,
     logging: false,
+    debug: {
+      authFlow: false,
+      clientAuthFlow: false,
+      serverAuthFlow: false
+    },
     authCache: {
       enabled: false,
       ttl: 900
@@ -72,6 +77,11 @@ const module$1 = defineNuxtModule({
         trustedOrigins: options.trustedOrigins ?? [],
         skipAuthRoutes: options.skipAuthRoutes ?? [],
         logging: options.logging ?? false,
+        debug: {
+          authFlow: options.debug?.authFlow ?? false,
+          clientAuthFlow: options.debug?.clientAuthFlow ?? false,
+          serverAuthFlow: options.debug?.serverAuthFlow ?? false
+        },
         authCache: {
           enabled: options.authCache?.enabled ?? false,
           ttl: options.authCache?.ttl ?? 900
@@ -91,7 +101,7 @@ const module$1 = defineNuxtModule({
       mode: "server"
     });
     addPlugin(resolver.resolve("./runtime/plugin.client"));
-    if (isAuthEnabled && nuxt.options.ssr) {
+    if (isAuthEnabled) {
       addServerHandler({
         route: `${authRoute}/**`,
         handler: resolver.resolve("./runtime/server/api/auth/[...]")

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

@@ -12,6 +12,19 @@ type AuthClient = ReturnType<typeof createAuthClient>;
  * but this is safe because auth operations (sign in, sign out) should only
  * be triggered by user interactions which only happen on the client.
  *
+ * ## Important: useSession() Cost
+ *
+ * Calling `authClient.useSession()` will trigger an additional `/api/auth/get-session`
+ * API call, which results in ~2 extra Convex database queries per page load.
+ * This is because Better Auth's useSession() fetches session data independently.
+ *
+ * **Recommended alternatives:**
+ * - Use `useConvexAuth()` for reading auth state (token, user, isAuthenticated)
+ * - Use `useConvexAuth().signOut()` for logging out (clears both Better Auth and Convex state)
+ *
+ * Only use `authClient.useSession()` if you specifically need Better Auth's
+ * reactive session features and are okay with the extra API call.
+ *
  * @example
  * ```vue
  * <script setup>
@@ -26,8 +39,10 @@ type AuthClient = ReturnType<typeof createAuthClient>;
  *   })
  * }
  *
+ * // For logout, prefer useConvexAuth().signOut() instead:
+ * const { signOut } = useConvexAuth()
  * async function logout() {
- *   await authClient?.signOut()
+ *   await signOut() // Clears both Better Auth AND Convex state
  * }
  * </script>
  * ```

package/dist/runtime/composables/useConvexAction.js

@@ -13,6 +13,7 @@ export function useConvexAction(action) {
   const logLevel = getLogLevel(config.public.convex ?? {});
   const logger = createLogger(logLevel);
   const fnName = getFunctionName(action);
+  const client = useConvex();
   const _status = ref("idle");
   const error = ref(null);
   const data = ref(void 0);
@@ -24,7 +25,6 @@ export function useConvexAction(action) {
     data.value = void 0;
   };
   const execute = async (args) => {
-    const client = useConvex();
     const startTime = Date.now();
     if (!client) {
       const err = new Error("ConvexClient not available - actions only work on client side");

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

@@ -12,12 +12,20 @@ export type { ConvexUser } from '../utils/types.js';
  * @example
  * ```vue
  * <script setup>
- * const { user, isAuthenticated, isPending } = useConvexAuth()
+ * const { user, isAuthenticated, isPending, signOut } = useConvexAuth()
+ *
+ * async function handleLogout() {
+ *   await signOut()
+ *   navigateTo('/login')
+ * }
  * </script>
  *
  * <template>
  *   <div v-if="isPending">Loading...</div>
- *   <div v-else-if="isAuthenticated">Welcome, {{ user?.name }}</div>
+ *   <div v-else-if="isAuthenticated">
+ *     Welcome, {{ user?.name }}
+ *     <button @click="handleLogout">Sign out</button>
+ *   </div>
  *   <div v-else>Please log in</div>
  * </template>
  * ```
@@ -49,4 +57,27 @@ export declare function useConvexAuth(): {
     isPending: Readonly<import("vue").Ref<boolean, boolean>>;
     /** Auth error message if authentication failed (e.g., 401/403) */
     authError: Readonly<import("vue").Ref<string | null, string | null>>;
+    /**
+     * Signs out the user from both Better Auth and Convex.
+     * Clears local state immediately and calls Better Auth's signOut().
+     */
+    signOut: () => Promise<{
+        data: {
+            success: boolean;
+        };
+        error: null;
+    } | {
+        data: null;
+        error: {
+            code?: string | undefined | undefined;
+            message?: string | undefined | undefined;
+            status: number;
+            statusText: string;
+        };
+    } | null>;
+    /**
+     * Force refresh Convex auth state after login.
+     * Triggers fresh token fetch and updates reactive state.
+     */
+    refreshAuth: () => Promise<void>;
 };

package/dist/runtime/composables/useConvexAuth.js

@@ -1,10 +1,55 @@
-import { useState, computed, readonly } from "#imports";
+import { useState, computed, readonly, useNuxtApp, watch } from "#imports";
 export function useConvexAuth() {
+  const nuxtApp = useNuxtApp();
   const token = useState("convex:token", () => null);
   const user = useState("convex:user", () => null);
-  const pending = useState("convex:pending", () => false);
+  const pending = useState("convex:pending", () => true);
   const authError = useState("convex:authError", () => null);
   const isAuthenticated = computed(() => !!token.value && !!user.value);
+  const signOut = async () => {
+    const authClient = nuxtApp.$auth;
+    token.value = null;
+    user.value = null;
+    authError.value = null;
+    if (authClient) {
+      try {
+        return await authClient.signOut();
+      } catch (e) {
+        console.warn("signOut request failed:", e);
+        return null;
+      }
+    }
+    return null;
+  };
+  const refreshAuth = async () => {
+    pending.value = true;
+    authError.value = null;
+    const refreshSignal = useState("convex:refreshSignal", () => 0);
+    refreshSignal.value++;
+    await new Promise((resolve) => {
+      let resolved = false;
+      let stopWatcher = null;
+      const cleanup = () => {
+        if (!resolved) {
+          resolved = true;
+          if (stopWatcher) stopWatcher();
+          resolve();
+        }
+      };
+      stopWatcher = watch(
+        [token, authError],
+        ([newToken, newError]) => {
+          if (newToken) {
+            cleanup();
+          } else if (newError && resolved === false) {
+            cleanup();
+          }
+        }
+      );
+      setTimeout(cleanup, 5e3);
+    });
+    pending.value = false;
+  };
   return {
     /** The JWT token for Convex authentication (readonly) */
     token: readonly(token),
@@ -15,6 +60,16 @@ export function useConvexAuth() {
     /** Whether an auth operation is pending */
     isPending: readonly(pending),
     /** Auth error message if authentication failed (e.g., 401/403) */
-    authError: readonly(authError)
+    authError: readonly(authError),
+    /**
+     * Signs out the user from both Better Auth and Convex.
+     * Clears local state immediately and calls Better Auth's signOut().
+     */
+    signOut,
+    /**
+     * Force refresh Convex auth state after login.
+     * Triggers fresh token fetch and updates reactive state.
+     */
+    refreshAuth
   };
 }

package/dist/runtime/composables/useConvexFileUpload.js

@@ -9,6 +9,7 @@ export function useConvexFileUpload(generateUploadUrlMutation, options) {
   const logLevel = getLogLevel(config.public.convex ?? {});
   const logger = createLogger(logLevel);
   const fnName = getFunctionName(generateUploadUrlMutation);
+  const client = useConvex();
   const _status = ref("idle");
   const error = ref(null);
   const data = ref(void 0);
@@ -33,7 +34,6 @@ export function useConvexFileUpload(generateUploadUrlMutation, options) {
     }
   });
   const upload = async (file, mutationArgs) => {
-    const client = useConvex();
     const startTime = Date.now();
     if (!client) {
       const err = new Error("ConvexClient not available - file uploads only work on client side");

package/dist/runtime/composables/useConvexMutation.js

@@ -20,6 +20,7 @@ export function useConvexMutation(mutation, options) {
   const logger = createLogger(logLevel);
   const fnName = getFunctionName(mutation);
   const hasOptimisticUpdate = !!options?.optimisticUpdate;
+  const client = useConvex();
   const _status = ref("idle");
   const error = ref(null);
   const data = ref(void 0);
@@ -31,7 +32,6 @@ export function useConvexMutation(mutation, options) {
     data.value = void 0;
   };
   const mutate = async (args) => {
-    const client = useConvex();
     const startTime = Date.now();
     if (!client) {
       const err = new Error("ConvexClient not available - mutations only work on client side");

package/dist/runtime/composables/useConvexPaginatedQuery.js

@@ -1,4 +1,4 @@
-import { useNuxtApp, useRuntimeConfig, useRequestEvent, useAsyncData } from "#imports";
+import { useNuxtApp, useRuntimeConfig, useRequestEvent, useAsyncData, useState } from "#imports";
 import {
   ref,
   computed,
@@ -75,6 +75,7 @@ export function useConvexPaginatedQuery(query, args, options) {
   const isSkipped = computed(() => getArgs() === "skip");
   const event = import.meta.server ? useRequestEvent() : null;
   const cookieHeader = event?.headers.get("cookie") || "";
+  const cachedToken = useState("convex:token");
   const currentPaginationId = ref(generatePaginationId());
   const pages = shallowRef([]);
   const globalError = ref(null);
@@ -108,7 +109,8 @@ export function useConvexPaginatedQuery(query, args, options) {
       authToken = await fetchAuthToken({
         isPublic,
         cookieHeader,
-        siteUrl
+        siteUrl,
+        cachedToken
       });
     }
     return executeQueryHttp(convexUrl, functionPath, fullArgs, authToken);

package/dist/runtime/composables/useConvexQuery.js

@@ -1,4 +1,4 @@
-import { useNuxtApp, useRuntimeConfig, useRequestEvent, useAsyncData } from "#imports";
+import { useNuxtApp, useRuntimeConfig, useRequestEvent, useAsyncData, useState } from "#imports";
 import { computed, watch, triggerRef, onUnmounted, toValue, isRef, isReactive } from "vue";
 import {
   getFunctionName,
@@ -74,6 +74,7 @@ export function useConvexQuery(query, args, options) {
   };
   const event = import.meta.server ? useRequestEvent() : null;
   const cookieHeader = event?.headers.get("cookie") || "";
+  const cachedToken = useState("convex:token");
   const asyncData = useAsyncData(
     cacheKey,
     async () => {
@@ -90,7 +91,8 @@ export function useConvexQuery(query, args, options) {
         const authToken = await fetchAuthToken({
           isPublic,
           cookieHeader,
-          siteUrl
+          siteUrl,
+          cachedToken
         });
         const result2 = await executeQueryHttp(convexUrl, fnName, currentArgs, authToken);
         return applyTransform(result2);

package/dist/runtime/devtools/auth-proxy-registry.d.ts

@@ -1,6 +1,14 @@
 /**
  * Registry for tracking auth proxy requests in dev mode.
  * This runs on the Nitro server and stores request data in global state.
+ *
+ * WARNING: This module uses globalThis state which IS shared across SSR requests.
+ * This is acceptable because:
+ * 1. It's only used in development mode for debugging
+ * 2. It only stores non-sensitive timing/stats data
+ * 3. The data is intentionally aggregated across requests for the DevTools panel
+ *
+ * Do NOT use this pattern for user-specific data in production.
  */
 import type { AuthProxyRequest, AuthProxyStats } from './types.js';
 declare global {

package/dist/runtime/devtools/auth-proxy-registry.js

@@ -1,3 +1,8 @@
+if (!import.meta.dev) {
+  throw new Error(
+    "[better-convex-nuxt] auth-proxy-registry is only available in development mode."
+  );
+}
 const MAX_REQUESTS = 20;
 function getRequests() {
   if (!globalThis.__convex_auth_proxy_requests__) {

package/dist/runtime/devtools/mutation-registry.d.ts

@@ -2,6 +2,9 @@
  * Mutation registry for DevTools integration.
  * Tracks in-flight and completed mutations with timeline data.
  * In-memory only, max 50 entries with LRU eviction.
+ *
+ * This module is client-only. Importing on the server will throw an error
+ * to prevent SSR state leakage between requests.
  */
 import type { MutationEntry } from './types.js';
 type RegistryCallback = (entries: MutationEntry[]) => void;

package/dist/runtime/devtools/mutation-registry.js

@@ -1,3 +1,8 @@
+if (import.meta.server) {
+  throw new Error(
+    "[better-convex-nuxt] DevTools mutation-registry must not be imported on server. This would cause state leakage between SSR requests."
+  );
+}
 const MAX_ENTRIES = 50;
 const mutationRegistry = /* @__PURE__ */ new Map();
 const subscribers = /* @__PURE__ */ new Set();

package/dist/runtime/devtools/query-registry.d.ts

@@ -1,6 +1,9 @@
 /**
  * Query registry for DevTools integration.
  * Tracks active queries with metadata for visualization.
+ *
+ * This module is client-only. Importing on the server will throw an error
+ * to prevent SSR state leakage between requests.
  */
 export type QueryStatus = 'pending' | 'success' | 'error' | 'idle';
 export type DataSource = 'ssr' | 'websocket' | 'cache';

package/dist/runtime/devtools/query-registry.js

@@ -1,3 +1,8 @@
+if (import.meta.server) {
+  throw new Error(
+    "[better-convex-nuxt] DevTools query-registry must not be imported on server. This would cause state leakage between SSR requests."
+  );
+}
 const queryRegistry = /* @__PURE__ */ new Map();
 const subscribers = /* @__PURE__ */ new Set();
 function notifySubscribers() {

package/dist/runtime/devtools/ui/dist/200.html

@@ -1 +1 @@
-<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Convex DevTools</title><link rel="stylesheet" href="/__convex_devtools__/_nuxt/entry.BiOLMZBG.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/BhO0ov6K.js"><script type="module" src="/__convex_devtools__/_nuxt/BhO0ov6K.js" crossorigin></script><script id="unhead:payload" type="application/json">{"title":"Convex DevTools"}</script></head><body><div id="__nuxt"></div><div id="teleports"></div><script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__convex_devtools__",buildId:"bb1b6fab-3dad-4ebb-bedd-8a7e8492b357",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1769017710929,false]</script></body></html>
+<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Convex DevTools</title><link rel="stylesheet" href="/__convex_devtools__/_nuxt/entry.BiOLMZBG.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/BhO0ov6K.js"><script type="module" src="/__convex_devtools__/_nuxt/BhO0ov6K.js" crossorigin></script><script id="unhead:payload" type="application/json">{"title":"Convex DevTools"}</script></head><body><div id="__nuxt"></div><div id="teleports"></div><script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__convex_devtools__",buildId:"df213a49-93a4-44f1-863e-5dc7de19c884",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1771229435100,false]</script></body></html>

package/dist/runtime/devtools/ui/dist/404.html

@@ -1 +1 @@
-<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Convex DevTools</title><link rel="stylesheet" href="/__convex_devtools__/_nuxt/entry.BiOLMZBG.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/BhO0ov6K.js"><script type="module" src="/__convex_devtools__/_nuxt/BhO0ov6K.js" crossorigin></script><script id="unhead:payload" type="application/json">{"title":"Convex DevTools"}</script></head><body><div id="__nuxt"></div><div id="teleports"></div><script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__convex_devtools__",buildId:"bb1b6fab-3dad-4ebb-bedd-8a7e8492b357",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1769017710929,false]</script></body></html>
+<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Convex DevTools</title><link rel="stylesheet" href="/__convex_devtools__/_nuxt/entry.BiOLMZBG.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/BhO0ov6K.js"><script type="module" src="/__convex_devtools__/_nuxt/BhO0ov6K.js" crossorigin></script><script id="unhead:payload" type="application/json">{"title":"Convex DevTools"}</script></head><body><div id="__nuxt"></div><div id="teleports"></div><script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__convex_devtools__",buildId:"df213a49-93a4-44f1-863e-5dc7de19c884",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1771229435101,false]</script></body></html>

package/dist/runtime/devtools/ui/dist/_nuxt/builds/latest.json

@@ -1 +1 @@
-{"id":"bb1b6fab-3dad-4ebb-bedd-8a7e8492b357","timestamp":1769017708682}
+{"id":"df213a49-93a4-44f1-863e-5dc7de19c884","timestamp":1771229432599}

package/dist/runtime/devtools/ui/dist/_nuxt/builds/meta/df213a49-93a4-44f1-863e-5dc7de19c884.json

@@ -0,0 +1 @@
+{"id":"df213a49-93a4-44f1-863e-5dc7de19c884","timestamp":1771229432599,"matcher":{"static":{},"wildcard":{},"dynamic":{}},"prerendered":[]}

package/dist/runtime/devtools/ui/dist/index.html

@@ -1 +1 @@
-<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Convex DevTools</title><link rel="stylesheet" href="/__convex_devtools__/_nuxt/entry.BiOLMZBG.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/BhO0ov6K.js"><script type="module" src="/__convex_devtools__/_nuxt/BhO0ov6K.js" crossorigin></script><script id="unhead:payload" type="application/json">{"title":"Convex DevTools"}</script></head><body><div id="__nuxt"></div><div id="teleports"></div><script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__convex_devtools__",buildId:"bb1b6fab-3dad-4ebb-bedd-8a7e8492b357",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1769017710929,false]</script></body></html>
+<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Convex DevTools</title><link rel="stylesheet" href="/__convex_devtools__/_nuxt/entry.BiOLMZBG.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/BhO0ov6K.js"><script type="module" src="/__convex_devtools__/_nuxt/BhO0ov6K.js" crossorigin></script><script id="unhead:payload" type="application/json">{"title":"Convex DevTools"}</script></head><body><div id="__nuxt"></div><div id="teleports"></div><script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/__convex_devtools__",buildId:"df213a49-93a4-44f1-863e-5dc7de19c884",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1771229435101,false]</script></body></html>

package/dist/runtime/plugin.client.js

@@ -11,7 +11,28 @@ export default defineNuxtPlugin((nuxtApp) => {
   const logLevel = getLogLevel(config.public.convex ?? {});
   const logger = createLogger(logLevel);
   const endInit = logger.time("plugin:init (client)");
-  if (nuxtApp._convexInitialized) return;
+  const debugConfig = config.public.convex?.debug;
+  const enableClientAuthTrace = logLevel === "debug" && (debugConfig?.authFlow === true || debugConfig?.clientAuthFlow === true);
+  const rawAuthLog = logger.auth.bind(logger);
+  logger.auth = (event) => {
+    rawAuthLog(event);
+    if (enableClientAuthTrace) {
+      console.log("[BCN_AUTH][client]", {
+        phase: event.phase,
+        outcome: event.outcome,
+        ...event.details,
+        error: event.error ? event.error.message : null
+      });
+    }
+  };
+  const convexAuthTraceId = useState(
+    "convex:authTraceId",
+    () => `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  if (nuxtApp._convexInitialized) {
+    logger.debug("plugin:init (client) skipped; already initialized", { traceId: convexAuthTraceId.value });
+    return;
+  }
   nuxtApp._convexInitialized = true;
   const convexUrl = config.public.convex?.url;
   const isAuthEnabled = config.public.convex?.auth;
@@ -27,7 +48,24 @@ export default defineNuxtPlugin((nuxtApp) => {
   const convexAuthError = useState("convex:authError");
   const client = new ConvexClient(convexUrl);
   let authClient = null;
-  const convexPending = useState("convex:pending", () => false);
+  const convexPending = useState("convex:pending", () => true);
+  let hasResolvedInitialAuth = false;
+  const resolveInitialAuth = () => {
+    if (!hasResolvedInitialAuth) {
+      hasResolvedInitialAuth = true;
+      convexPending.value = false;
+    }
+  };
+  const refreshSignal = useState("convex:refreshSignal", () => 0);
+  logger.auth({
+    phase: "client-init",
+    outcome: "success",
+    details: {
+      traceId: convexAuthTraceId.value,
+      serverRendered: Boolean(nuxtApp.payload?.serverRendered),
+      authEnabled: Boolean(isAuthEnabled)
+    }
+  });
   if (isAuthEnabled && siteUrl) {
     const rawAuthRoute = config.public.convex?.authRoute || "/api/auth";
     const authRoute = (rawAuthRoute.startsWith("/") ? rawAuthRoute : `/${rawAuthRoute}`).replace(/\/+$/, "");
@@ -43,37 +81,118 @@ export default defineNuxtPlugin((nuxtApp) => {
     const NULL_TOKEN_CACHE_MS = 5e3;
     const skipRoutes = config.public.convex?.skipAuthRoutes || [];
     const router = useRouter();
-    let currentAuthOperation = null;
     const fetchToken = async ({
       forceRefreshToken,
       signal
     }) => {
-      if (signal?.aborted) return null;
       const route = router.currentRoute.value;
+      const routePath = route.path;
+      logger.auth({
+        phase: "client-fetchToken:start",
+        outcome: "success",
+        details: {
+          traceId: convexAuthTraceId.value,
+          path: routePath,
+          forceRefreshToken,
+          hasHydratedToken: Boolean(convexToken.value),
+          hasHydratedUser: Boolean(convexUser.value)
+        }
+      });
+      if (signal?.aborted) {
+        logger.auth({
+          phase: "client-fetchToken:abort",
+          outcome: "skip",
+          details: { traceId: convexAuthTraceId.value, reason: "signal-aborted-before-start", path: routePath }
+        });
+        return null;
+      }
       if (route.meta?.skipConvexAuth === true) {
+        logger.auth({
+          phase: "client-fetchToken:skip",
+          outcome: "skip",
+          details: { traceId: convexAuthTraceId.value, reason: "page-meta-skip", path: routePath }
+        });
+        resolveInitialAuth();
         return null;
       }
       if (matchesSkipRoute(route.path, skipRoutes)) {
+        logger.auth({
+          phase: "client-fetchToken:skip",
+          outcome: "skip",
+          details: { traceId: convexAuthTraceId.value, reason: "skip-auth-route", path: routePath }
+        });
+        resolveInitialAuth();
         return null;
       }
       if (convexToken.value && !forceRefreshToken) {
         lastTokenValidation = Date.now();
+        logger.auth({
+          phase: "client-fetchToken:cache",
+          outcome: "success",
+          details: { traceId: convexAuthTraceId.value, source: "hydrated-token", path: routePath }
+        });
+        resolveInitialAuth();
         return convexToken.value;
       }
       const timeSinceValidation = Date.now() - lastTokenValidation;
       if (convexToken.value && forceRefreshToken && timeSinceValidation < TOKEN_CACHE_MS) {
+        logger.auth({
+          phase: "client-fetchToken:cache",
+          outcome: "success",
+          details: {
+            traceId: convexAuthTraceId.value,
+            source: "recent-token-cache",
+            ageMs: timeSinceValidation,
+            path: routePath
+          }
+        });
+        resolveInitialAuth();
         return convexToken.value;
       }
       const wasServerRendered = !!nuxtApp.payload?.serverRendered;
       if (wasServerRendered && !convexToken.value && !convexUser.value && !forceRefreshToken) {
+        logger.auth({
+          phase: "client-fetchToken:skip",
+          outcome: "skip",
+          details: {
+            traceId: convexAuthTraceId.value,
+            reason: "ssr-rendered-no-hydrated-session",
+            path: routePath
+          }
+        });
+        resolveInitialAuth();
         return null;
       }
-      if (!convexToken.value && Date.now() - lastNullTokenCheck < NULL_TOKEN_CACHE_MS) {
+      const timeSinceNullCheck = Date.now() - lastNullTokenCheck;
+      if (!convexToken.value && timeSinceNullCheck < NULL_TOKEN_CACHE_MS) {
+        logger.auth({
+          phase: "client-fetchToken:cache",
+          outcome: "miss",
+          details: {
+            traceId: convexAuthTraceId.value,
+            source: "negative-cache",
+            ageMs: timeSinceNullCheck,
+            path: routePath
+          }
+        });
+        resolveInitialAuth();
         return null;
       }
       try {
+        logger.auth({
+          phase: "client-fetchToken:request",
+          outcome: "success",
+          details: { traceId: convexAuthTraceId.value, endpoint: `${authRoute}/convex/token`, path: routePath }
+        });
         const response = await authClient.convex.token();
-        if (signal?.aborted) return null;
+        if (signal?.aborted) {
+          logger.auth({
+            phase: "client-fetchToken:abort",
+            outcome: "skip",
+            details: { traceId: convexAuthTraceId.value, reason: "signal-aborted-after-request", path: routePath }
+          });
+          return null;
+        }
         if (response.error || !response.data?.token) {
           convexToken.value = null;
           convexUser.value = null;
@@ -82,6 +201,16 @@ export default defineNuxtPlugin((nuxtApp) => {
             convexAuthError.value = errorMsg;
           }
           lastNullTokenCheck = Date.now();
+          logger.auth({
+            phase: "client-fetchToken:response",
+            outcome: "miss",
+            details: {
+              traceId: convexAuthTraceId.value,
+              path: routePath,
+              hasError: Boolean(response.error)
+            }
+          });
+          resolveInitialAuth();
           return null;
         }
         const token = response.data.token;
@@ -91,49 +220,68 @@ export default defineNuxtPlugin((nuxtApp) => {
         if (!convexUser.value) {
           convexUser.value = decodeUserFromJwt(token);
         }
+        logger.auth({
+          phase: "client-fetchToken:response",
+          outcome: "success",
+          details: {
+            traceId: convexAuthTraceId.value,
+            path: routePath,
+            userHydrated: Boolean(convexUser.value)
+          }
+        });
+        resolveInitialAuth();
         return token;
       } catch (e) {
-        if (signal?.aborted) return null;
+        if (signal?.aborted) {
+          logger.auth({
+            phase: "client-fetchToken:abort",
+            outcome: "skip",
+            details: { traceId: convexAuthTraceId.value, reason: "signal-aborted-after-error", path: routePath }
+          });
+          return null;
+        }
         convexToken.value = null;
         convexUser.value = null;
         convexAuthError.value = e instanceof Error ? e.message : "Authentication request failed";
         lastNullTokenCheck = Date.now();
+        logger.auth({
+          phase: "client-fetchToken:response",
+          outcome: "error",
+          details: { traceId: convexAuthTraceId.value, path: routePath },
+          error: e instanceof Error ? e : new Error("Authentication request failed")
+        });
+        resolveInitialAuth();
         return null;
       }
     };
     client.setAuth(fetchToken, (isAuthenticated) => {
-      logger.debug(`Auth state: ${isAuthenticated ? "authenticated" : "unauthenticated"}`);
+      logger.auth({
+        phase: "client-setAuth",
+        outcome: "success",
+        details: {
+          traceId: convexAuthTraceId.value,
+          state: isAuthenticated ? "authenticated" : "unauthenticated",
+          hasToken: Boolean(convexToken.value),
+          hasUser: Boolean(convexUser.value)
+        }
+      });
     });
-    const session = authClient.useSession();
-    watch(
-      () => session.value.data,
-      async (sessionData, oldSessionData) => {
-        currentAuthOperation?.abort();
-        currentAuthOperation = new AbortController();
-        const { signal } = currentAuthOperation;
-        const hadSession = !!oldSessionData;
-        const hasSession = !!sessionData;
-        if (hasSession && !hadSession) {
-          convexPending.value = true;
-          try {
-            lastNullTokenCheck = 0;
-            lastTokenValidation = 0;
-            await fetchToken({ forceRefreshToken: true, signal });
-            logger.auth({ phase: "login", outcome: "success" });
-          } finally {
-            if (!signal.aborted) {
-              convexPending.value = false;
-            }
-          }
-        } else if (!hasSession && hadSession) {
-          convexPending.value = false;
-          convexToken.value = null;
-          convexUser.value = null;
-          convexAuthError.value = null;
-          logger.auth({ phase: "logout", outcome: "success" });
+    watch(refreshSignal, () => {
+      logger.auth({
+        phase: "client-refresh",
+        outcome: "success",
+        details: {
+          traceId: convexAuthTraceId.value,
+          refreshSignal: refreshSignal.value
         }
-      }
-    );
+      });
+      lastTokenValidation = 0;
+      lastNullTokenCheck = 0;
+      client.setAuth(fetchToken, (_isAuthenticated) => {
+      });
+    });
+  } else {
+    convexPending.value = false;
   }
   nuxtApp.provide("convex", client);
   if (authClient) {
@@ -151,7 +299,14 @@ export default defineNuxtPlugin((nuxtApp) => {
   if (convexToken.value) {
     logger.auth({ phase: "hydrate", outcome: "success", details: { source: "ssr" } });
   } else if (isAuthEnabled) {
-    logger.debug("Client initialized (auth enabled, no session)");
+    logger.auth({
+      phase: "hydrate",
+      outcome: "miss",
+      details: {
+        traceId: convexAuthTraceId.value,
+        source: "client-init"
+      }
+    });
   } else {
     logger.debug("Client initialized (auth disabled)");
   }

package/dist/runtime/plugin.server.js

@@ -21,6 +21,20 @@ export default defineNuxtPlugin(async () => {
   const logLevel = getLogLevel(config.public.convex ?? {});
   const logger = createLogger(logLevel);
   const endInit = logger.time("plugin:init (server)");
+  const debugConfig = config.public.convex?.debug;
+  const enableServerAuthTrace = logLevel === "debug" && (debugConfig?.authFlow === true || debugConfig?.serverAuthFlow === true);
+  const rawAuthLog = logger.auth.bind(logger);
+  logger.auth = (event2) => {
+    rawAuthLog(event2);
+    if (enableServerAuthTrace) {
+      console.log("[BCN_AUTH][server]", {
+        phase: event2.phase,
+        outcome: event2.outcome,
+        ...event2.details,
+        error: event2.error ? event2.error.message : null
+      });
+    }
+  };
   const isAuthEnabled = config.public.convex?.auth;
   if (!isAuthEnabled) {
     endInit();
@@ -32,6 +46,9 @@ export default defineNuxtPlugin(async () => {
     logger.auth({ phase: "init", outcome: "error", error: new Error("No request event available") });
     return;
   }
+  const requestPath = event.path || event.node.req.url || "(unknown)";
+  const requestMethod = event.method || "GET";
+  const requestId = crypto.randomUUID();
   const siteUrl = config.public.convex?.siteUrl;
   if (!siteUrl) {
     endInit();
@@ -39,7 +56,17 @@ export default defineNuxtPlugin(async () => {
     return;
   }
   const logAuth = (phase, outcome, details, error) => {
-    logger.auth({ phase, outcome, details, error });
+    logger.auth({
+      phase,
+      outcome,
+      details: {
+        requestId,
+        method: requestMethod,
+        path: requestPath,
+        ...details
+      },
+      error
+    });
   };
   const convexToken = useState("convex:token", () => null);
   const convexUser = useState("convex:user", () => null);
@@ -48,14 +75,20 @@ export default defineNuxtPlugin(async () => {
   const waterfallStart = trackWaterfall ? Date.now() : 0;
   const phases = [];
   let cacheHit = false;
+  const authCacheConfig = config.public.convex?.authCache;
   const sessionCheckStart = trackWaterfall ? Date.now() : 0;
   const cookieHeader = event.headers.get("cookie");
   const sessionToken = getCookie(cookieHeader, SECURE_SESSION_COOKIE_NAME) || getCookie(cookieHeader, SESSION_COOKIE_NAME);
+  logAuth("server-init", "success", {
+    hasCookieHeader: Boolean(cookieHeader),
+    hasSessionToken: Boolean(sessionToken),
+    cacheEnabled: Boolean(authCacheConfig?.enabled)
+  });
   if (!cookieHeader || !sessionToken) {
     if (trackWaterfall) {
       phases.push(buildPhase("session-check", sessionCheckStart, waterfallStart, "miss", "No session cookie"));
       convexAuthWaterfall.value = {
-        requestId: crypto.randomUUID(),
+        requestId,
         timestamp: waterfallStart,
         phases,
         totalDuration: Date.now() - waterfallStart,
@@ -70,7 +103,6 @@ export default defineNuxtPlugin(async () => {
   if (trackWaterfall) {
     phases.push(buildPhase("session-check", sessionCheckStart, waterfallStart, "success", "Cookie found"));
   }
-  const authCacheConfig = config.public.convex?.authCache;
   try {
     let token = null;
     if (authCacheConfig?.enabled && sessionToken) {
@@ -89,7 +121,7 @@ export default defineNuxtPlugin(async () => {
             buildPhase("jwt-decode", decodeStart, waterfallStart, convexUser.value ? "success" : "error")
           );
           convexAuthWaterfall.value = {
-            requestId: crypto.randomUUID(),
+            requestId,
             timestamp: waterfallStart,
             phases,
             totalDuration: Date.now() - waterfallStart,
@@ -161,7 +193,7 @@ export default defineNuxtPlugin(async () => {
     }
     if (trackWaterfall) {
       convexAuthWaterfall.value = {
-        requestId: crypto.randomUUID(),
+        requestId,
         timestamp: waterfallStart,
         phases,
         totalDuration: Date.now() - waterfallStart,
@@ -174,7 +206,7 @@ export default defineNuxtPlugin(async () => {
     convexUser.value = null;
     if (trackWaterfall) {
       convexAuthWaterfall.value = {
-        requestId: crypto.randomUUID(),
+        requestId,
         timestamp: waterfallStart,
         phases,
         totalDuration: Date.now() - waterfallStart,

package/dist/runtime/server/api/auth/[...].js

@@ -34,13 +34,13 @@ export default defineEventHandler(async (event) => {
   const authRoute = (rawAuthRoute.startsWith("/") ? rawAuthRoute : `/${rawAuthRoute}`).replace(/\/+$/, "");
   const startTime = import.meta.dev ? Date.now() : 0;
   const requestId = import.meta.dev ? crypto.randomUUID() : "";
+  const requestUrl = getRequestURL(event);
   if (!siteUrl) {
     throw createError({
       statusCode: 500,
       message: "Convex site URL not configured"
     });
   }
-  const requestUrl = getRequestURL(event);
   const authRoutePattern = new RegExp(`^${authRoute.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
   const path = requestUrl.pathname.replace(authRoutePattern, "") || "/";
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;

package/dist/runtime/types.d.ts

@@ -1,5 +1,6 @@
 import type { createAuthClient } from 'better-auth/vue'
 import type { ConvexClient } from 'convex/browser'
+import type { LogLevel } from './utils/logger'
 
 type AuthClient = ReturnType<typeof createAuthClient>
 
@@ -13,10 +14,13 @@ export interface ConvexPublicRuntimeConfig {
   siteUrl?: string
   /** Routes that should skip auth checks */
   skipAuthRoutes?: string[]
-  /** Logging options */
-  logging?: {
-    enabled?: boolean | 'debug'
-    format?: 'pretty' | 'json'
+  /** Logging level */
+  logging?: LogLevel
+  /** Optional debug channels for high-verbosity traces */
+  debug?: {
+    authFlow?: boolean
+    clientAuthFlow?: boolean
+    serverAuthFlow?: boolean
   }
   /** Index signature for compatibility with Record<string, unknown> */
   [key: string]: unknown

package/dist/runtime/utils/convex-cache.d.ts

@@ -1,4 +1,4 @@
-import { type useNuxtApp } from '#app';
+import type { useNuxtApp } from '#app';
 export { type QueryStatus, parseConvexResponse, computeQueryStatus, getFunctionName, hashArgs, getQueryKey, } from './convex-shared.js';
 type NuxtApp = ReturnType<typeof useNuxtApp>;
 /**
@@ -20,20 +20,33 @@ export interface FetchAuthTokenOptions {
     cookieHeader: string;
     /** Site URL for auth endpoint */
     siteUrl: string | undefined;
+    /** Cached token state (must be obtained at setup time via useState) */
+    cachedToken: {
+        value: string | null;
+    };
 }
 /**
  * Fetch auth token for SSR queries.
- * Uses caching via useState to avoid redundant fetches.
+ * Uses caching via the provided cachedToken ref to avoid redundant fetches.
+ *
+ * IMPORTANT: The cachedToken parameter must be obtained at component setup time
+ * using useState('convex:token') before being passed to this function.
+ * Calling useState inside an async function loses Vue context and will fail.
  *
  * @param options - Auth token fetch options
  * @returns The auth token if available, undefined otherwise
  *
  * @example
  * ```ts
+ * // At setup time (synchronous):
+ * const cachedToken = useState<string | null>('convex:token')
+ *
+ * // Later, in async context:
  * const authToken = await fetchAuthToken({
  *   isPublic: false,
  *   cookieHeader: event?.headers.get('cookie') || '',
  *   siteUrl: config.public.convex?.siteUrl,
+ *   cachedToken,
  * })
  * ```
  */

package/dist/runtime/utils/convex-cache.js

@@ -1,4 +1,3 @@
-import { useState } from "#app";
 export {
   parseConvexResponse,
   computeQueryStatus,
@@ -8,14 +7,13 @@ export {
 } from "./convex-shared.js";
 const subscriptionRegistry = /* @__PURE__ */ new WeakMap();
 export async function fetchAuthToken(options) {
-  const { isPublic, cookieHeader, siteUrl } = options;
+  const { isPublic, cookieHeader, siteUrl, cachedToken } = options;
   if (isPublic) {
     return void 0;
   }
   if (!cookieHeader.includes("better-auth.session_token")) {
     return void 0;
   }
-  const cachedToken = useState("convex:token");
   if (cachedToken.value) {
     return cachedToken.value;
   }

package/dist/types.d.mts

@@ -2,4 +2,4 @@ export { type LogLevel } from '../dist/runtime/utils/logger.js'
 
 export { default } from './module.mjs'
 
-export { type AuthCacheOptions, type ModuleOptions, type QueryDefaults } from './module.mjs'
+export { type AuthCacheOptions, type ConvexDebugOptions, type ModuleOptions, type QueryDefaults } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-convex-nuxt",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Full-featured Convex integration for Nuxt with SSR, real-time subscriptions, authentication, and permissions",
   "keywords": [
     "authentication",

package/dist/runtime/devtools/ui/dist/_nuxt/builds/meta/bb1b6fab-3dad-4ebb-bedd-8a7e8492b357.json

@@ -1 +0,0 @@
-{"id":"bb1b6fab-3dad-4ebb-bedd-8a7e8492b357","timestamp":1769017708682,"matcher":{"static":{},"wildcard":{},"dynamic":{}},"prerendered":[]}