better-convex-nuxt 0.1.6 → 0.1.8

package/dist/module.d.mts

@@ -17,6 +17,12 @@ interface ModuleOptions {
      * @default false
      */
     permissions?: boolean;
+    /**
+     * Enable verbose logging for debugging.
+     * When true, logs detailed information about queries, mutations, auth, and SSR operations.
+     * @default false
+     */
+    verbose?: boolean;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

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

package/dist/module.mjs

@@ -12,7 +12,8 @@ const module$1 = defineNuxtModule({
   defaults: {
     url: process.env.CONVEX_URL,
     siteUrl: process.env.CONVEX_SITE_URL,
-    permissions: false
+    permissions: false,
+    verbose: false
   },
   setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
@@ -22,6 +23,7 @@ const module$1 = defineNuxtModule({
       {
         url: options.url || "",
         siteUrl: derivedSiteUrl,
+        verbose: options.verbose ?? false,
         // Keep auth.url for backwards compatibility
         auth: {
           url: options.auth?.url || derivedSiteUrl

package/dist/runtime/composables/useConvexAction.js

@@ -1,18 +1,10 @@
 import { ref, computed } from "vue";
-import { getFunctionName } from "../utils/convex-cache.js";
+import { createActionLogger, getVerboseFlag } from "../utils/logger.js";
 import { useConvex } from "./useConvex.js";
 export function useConvexAction(action, options) {
-  const verbose = options?.verbose ?? false;
-  const fnName = getFunctionName(action);
-  const log = verbose ? (message, data2) => {
-    const prefix = `[useConvexAction] ${fnName}: `;
-    if (data2 !== void 0) {
-      console.log(prefix + message, data2);
-    } else {
-      console.log(prefix + message);
-    }
-  } : () => {
-  };
+  const config = useRuntimeConfig();
+  const verbose = getVerboseFlag(config, options?.verbose);
+  const log = createActionLogger(verbose, "useConvexAction", action);
   log("Initialized");
   const _status = ref("idle");
   const error = ref(null);

package/dist/runtime/composables/useConvexAuth.js

@@ -1,20 +1,15 @@
-import { useState, computed, readonly } from "#imports";
-const log = (message, data) => {
-  if (import.meta.dev) {
-    const env = import.meta.server ? "[SSR]" : "[Client]";
-    const prefix = `[bcn:auth] ${env} `;
-    if (data !== void 0) {
-      console.log(prefix + message, data);
-    } else {
-      console.log(prefix + message);
-    }
-  }
-};
+import { useState, computed, readonly, useRuntimeConfig } from "#imports";
+import { createLogger, getVerboseFlag } from "../utils/logger.js";
 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,

package/dist/runtime/composables/useConvexConnectionState.js

@@ -1,4 +1,5 @@
 import { ref, readonly, computed, onMounted, onUnmounted } from "vue";
+import { createLogger, getVerboseFlag } from "../utils/logger.js";
 import { useConvex } from "./useConvex.js";
 const DEFAULT_STATE = {
   hasInflightRequests: false,
@@ -12,16 +13,12 @@ const DEFAULT_STATE = {
 };
 export function useConvexConnectionState(options) {
   const client = useConvex();
-  const verbose = options?.verbose ?? false;
-  const log = verbose ? (message, data) => {
-    const prefix = "[useConvexConnectionState]: ";
-    if (data !== void 0) {
-      console.log(prefix + message, data);
-    } else {
-      console.log(prefix + message);
-    }
-  } : () => {
-  };
+  const config = useRuntimeConfig();
+  const verbose = getVerboseFlag(config, options?.verbose);
+  const log = createLogger({
+    verbose,
+    prefix: "[bcn:useConvexConnectionState]"
+  });
   log("Initialized", { hasClient: !!client, isClient: import.meta.client });
   const state = ref({ ...DEFAULT_STATE });
   const isConnected = computed(() => state.value.isWebSocketConnected);

package/dist/runtime/composables/useConvexMutation.js

@@ -1,5 +1,5 @@
 import { ref, computed } from "vue";
-import { getFunctionName } from "../utils/convex-cache.js";
+import { createMutationLogger, getVerboseFlag } from "../utils/logger.js";
 import { useConvex } from "./useConvex.js";
 export function updateQuery(options) {
   const { query, args, localQueryStore, updater } = options;
@@ -44,17 +44,9 @@ function argsMatch(queryArgs, filterArgs) {
   return true;
 }
 export function useConvexMutation(mutation, options) {
-  const verbose = options?.verbose ?? false;
-  const fnName = getFunctionName(mutation);
-  const log = verbose ? (message, data2) => {
-    const prefix = `[useConvexMutation] ${fnName}: `;
-    if (data2 !== void 0) {
-      console.log(prefix + message, data2);
-    } else {
-      console.log(prefix + message);
-    }
-  } : () => {
-  };
+  const config = useRuntimeConfig();
+  const verbose = getVerboseFlag(config, options?.verbose);
+  const log = createMutationLogger(verbose, "useConvexMutation", mutation);
   log("Initialized", { hasOptimisticUpdate: !!options?.optimisticUpdate });
   const _status = ref("idle");
   const error = ref(null);

package/dist/runtime/composables/useConvexPaginatedQuery.js

@@ -11,6 +11,7 @@ import {
   triggerRef
 } from "vue";
 import { getFunctionName, stableStringify, getQueryKey } from "../utils/convex-cache.js";
+import { getVerboseFlag } from "../utils/logger.js";
 import {
   createQueryLogger,
   fetchAuthToken,
@@ -33,7 +34,7 @@ export function useConvexPaginatedQuery(query, args, options) {
   const lazy = options?.lazy ?? false;
   const subscribe = options?.subscribe ?? true;
   const isPublic = options?.public ?? false;
-  const verbose = options?.verbose ?? false;
+  const verbose = getVerboseFlag(config, options?.verbose);
   const fnName = getFunctionName(query);
   const log = createQueryLogger(verbose, "useConvexPaginatedQuery", query);
   log("Initializing", { initialNumItems, server, lazy, subscribe, public: isPublic });

package/dist/runtime/composables/useConvexQuery.js

@@ -23,6 +23,7 @@ import {
   removeFromSubscriptionCache,
   buildThenableResult
 } from "../utils/query-helpers.js";
+import { getVerboseFlag } from "../utils/logger.js";
 export { parseConvexResponse, computeQueryStatus };
 export async function executeQueryHttp(convexUrl, functionPath, args, authToken) {
   const headers = {
@@ -59,7 +60,7 @@ export function useConvexQuery(query, args, options) {
   const lazy = options?.lazy ?? false;
   const server = options?.server ?? true;
   const subscribe = options?.subscribe ?? true;
-  const verbose = options?.verbose ?? false;
+  const verbose = getVerboseFlag(config, options?.verbose);
   const isPublic = options?.public ?? false;
   const fnName = getFunctionName(query);
   const log = createQueryLogger(verbose, "useConvexQuery", query);

package/dist/runtime/plugin.client.js

@@ -2,24 +2,19 @@ import { defineNuxtPlugin, useRuntimeConfig, useState } from "#app";
 import { convexClient } from "@convex-dev/better-auth/client/plugins";
 import { createAuthClient } from "better-auth/vue";
 import { ConvexClient } from "convex/browser";
-const log = (message, data) => {
-  if (import.meta.dev) {
-    const prefix = "[bcn:client] ";
-    if (data !== void 0) {
-      console.log(prefix + message, data);
-    } else {
-      console.log(prefix + message);
-    }
-  }
-};
+import { createLogger, getVerboseFlag } from "./utils/logger.js";
 export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig();
+  const log = createLogger({
+    verbose: getVerboseFlag(config),
+    prefix: "[bcn:client]"
+  });
   log("Plugin starting");
   if (nuxtApp._convexInitialized) {
     log("Already initialized (HMR), skipping");
     return;
   }
   nuxtApp._convexInitialized = true;
-  const config = useRuntimeConfig();
   const convexUrl = config.public.convex?.url;
   const siteUrl = config.public.convex?.siteUrl || config.public.convex?.auth?.url || (convexUrl?.replace(".convex.cloud", ".convex.site") ?? "");
   log("Config loaded", { convexUrl, siteUrl });

package/dist/runtime/plugin.server.js

@@ -1,22 +1,17 @@
 import { defineNuxtPlugin, useState, useRuntimeConfig, useRequestEvent } from "#app";
-const log = (message, data) => {
-  if (import.meta.dev) {
-    const prefix = "[bcn:ssr] ";
-    if (data !== void 0) {
-      console.log(prefix + message, data);
-    } else {
-      console.log(prefix + message);
-    }
-  }
-};
+import { createLogger, getVerboseFlag } from "./utils/logger.js";
 export default defineNuxtPlugin(async () => {
+  const config = useRuntimeConfig();
+  const log = createLogger({
+    verbose: getVerboseFlag(config),
+    prefix: "[bcn:ssr]"
+  });
   log("Plugin starting");
   const event = useRequestEvent();
   if (!event) {
     log("No request event available, skipping");
     return;
   }
-  const config = useRuntimeConfig();
   const siteUrl = config.public.convex?.siteUrl || config.public.convex?.auth?.url;
   if (!siteUrl) {
     log("No siteUrl configured, skipping auth");

package/dist/runtime/server/utils/convex.js

@@ -1,16 +1,15 @@
+import { useRuntimeConfig } from "nitropack/runtime";
 import { parseConvexResponse, getFunctionName } from "../../utils/convex-cache.js";
+import { createLogger, getVerboseFlag } from "../../utils/logger.js";
 export async function fetchQuery(convexUrl, query, args, options) {
   const functionPath = getFunctionName(query);
-  const verbose = options?.verbose ?? false;
-  const log = verbose ? (message, data) => {
-    const prefix = `[fetchQuery] ${functionPath}: `;
-    if (data !== void 0) {
-      console.log(prefix + message, data);
-    } else {
-      console.log(prefix + message);
-    }
-  } : () => {
-  };
+  const config = useRuntimeConfig();
+  const verbose = getVerboseFlag(config, options?.verbose);
+  const log = createLogger({
+    verbose,
+    prefix: "[bcn:fetchQuery]",
+    functionName: functionPath
+  });
   log("Starting", { args, hasAuth: !!options?.authToken });
   const headers = {
     "Content-Type": "application/json"
@@ -37,16 +36,13 @@ export async function fetchQuery(convexUrl, query, args, options) {
 }
 export async function fetchMutation(convexUrl, mutation, args, options) {
   const functionPath = getFunctionName(mutation);
-  const verbose = options?.verbose ?? false;
-  const log = verbose ? (message, data) => {
-    const prefix = `[fetchMutation] ${functionPath}: `;
-    if (data !== void 0) {
-      console.log(prefix + message, data);
-    } else {
-      console.log(prefix + message);
-    }
-  } : () => {
-  };
+  const config = useRuntimeConfig();
+  const verbose = getVerboseFlag(config, options?.verbose);
+  const log = createLogger({
+    verbose,
+    prefix: "[bcn:fetchMutation]",
+    functionName: functionPath
+  });
   log("Starting", { args, hasAuth: !!options?.authToken });
   const headers = {
     "Content-Type": "application/json"
@@ -73,16 +69,13 @@ export async function fetchMutation(convexUrl, mutation, args, options) {
 }
 export async function fetchAction(convexUrl, action, args, options) {
   const functionPath = getFunctionName(action);
-  const verbose = options?.verbose ?? false;
-  const log = verbose ? (message, data) => {
-    const prefix = `[fetchAction] ${functionPath}: `;
-    if (data !== void 0) {
-      console.log(prefix + message, data);
-    } else {
-      console.log(prefix + message);
-    }
-  } : () => {
-  };
+  const config = useRuntimeConfig();
+  const verbose = getVerboseFlag(config, options?.verbose);
+  const log = createLogger({
+    verbose,
+    prefix: "[bcn:fetchAction]",
+    functionName: functionPath
+  });
   log("Starting", { args, hasAuth: !!options?.authToken });
   const headers = {
     "Content-Type": "application/json"

package/dist/runtime/types.d.ts

@@ -10,6 +10,23 @@ declare module '#app' {
     /** Internal cache for WebSocket subscriptions (prevents duplicates) */
     _convexSubscriptions?: Record<string, () => void>
   }
+
+  interface RuntimeConfig {
+    public: {
+      convex: {
+        /** Convex deployment URL (WebSocket) */
+        url: string
+        /** Convex site URL (HTTP/Auth) */
+        siteUrl: string
+        /** Enable verbose logging for debugging */
+        verbose: boolean
+        /** @deprecated Use siteUrl instead */
+        auth?: {
+          url: string
+        }
+      }
+    }
+  }
 }
 
 declare module 'vue' {

package/dist/runtime/utils/logger.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared logging utilities for better-convex-nuxt
+ *
+ * Provides consistent logging patterns across all composables, plugins, and utilities.
+ * Logs are prefixed with context information and can be enabled/disabled via config.
+ */
+import type { FunctionReference } from 'convex/server';
+/**
+ * Logger function type for debug logging
+ */
+export type Logger = (message: string, data?: unknown) => void;
+/**
+ * Options for creating a logger
+ */
+export interface LoggerOptions {
+    /** Whether logging is enabled */
+    verbose: boolean;
+    /** Prefix for log messages (e.g., '[bcn:auth]', '[useConvexQuery]') */
+    prefix: string;
+    /** Optional function name to include in prefix (for query/mutation/action loggers) */
+    functionName?: string;
+    /** Optional function reference to extract name from */
+    functionRef?: FunctionReference<'query' | 'mutation' | 'action'>;
+}
+/**
+ * Create a logger function with consistent formatting.
+ *
+ * @param options - Logger configuration options
+ * @returns Logger function that logs with prefix and environment info, or no-op if verbose is false
+ *
+ * @example
+ * ```ts
+ * // Simple logger
+ * const log = createLogger({
+ *   verbose: config.public.convex?.verbose ?? false,
+ *   prefix: '[bcn:auth]',
+ * })
+ * log('User authenticated', { userId: '123' })
+ *
+ * // Function logger (for queries/mutations)
+ * const log = createLogger({
+ *   verbose: true,
+ *   prefix: '[bcn:useConvexQuery]',
+ *   functionRef: api.tasks.list,
+ * })
+ * log('Fetching tasks', { status: 'active' })
+ * ```
+ */
+export declare function createLogger(options: LoggerOptions): Logger;
+/**
+ * Create a logger for query composables.
+ * This is a convenience wrapper around createLogger with query-specific defaults.
+ *
+ * @param verbose - Whether logging is enabled
+ * @param composableName - Name of the composable (e.g., 'useConvexQuery')
+ * @param query - The Convex query function reference
+ * @returns Logger function
+ *
+ * @example
+ * ```ts
+ * const log = createQueryLogger(verbose, 'useConvexQuery', api.tasks.list)
+ * // Logs will have prefix: [bcn:useConvexQuery] [SSR] tasks:list: ...
+ * log('Initializing', { lazy, server })
+ * ```
+ */
+export declare function createQueryLogger(verbose: boolean, composableName: string, query: FunctionReference<'query'>): Logger;
+/**
+ * Create a logger for mutation composables.
+ *
+ * @param verbose - Whether logging is enabled
+ * @param composableName - Name of the composable (e.g., 'useConvexMutation')
+ * @param mutation - The Convex mutation function reference
+ * @returns Logger function
+ */
+export declare function createMutationLogger(verbose: boolean, composableName: string, mutation: FunctionReference<'mutation'>): Logger;
+/**
+ * Create a logger for action composables.
+ *
+ * @param verbose - Whether logging is enabled
+ * @param composableName - Name of the composable (e.g., 'useConvexAction')
+ * @param action - The Convex action function reference
+ * @returns Logger function
+ */
+export declare function createActionLogger(verbose: boolean, composableName: string, action: FunctionReference<'action'>): Logger;
+/**
+ * Get verbose flag from runtime config with fallback.
+ * This is a convenience function to avoid repeating the same pattern.
+ *
+ * @param config - Runtime config from useRuntimeConfig()
+ * @param config.public - Public runtime config
+ * @param config.public.convex - Convex-specific public config
+ * @param config.public.convex.verbose - Verbose logging flag
+ * @param override - Optional override value (from options)
+ * @returns Whether verbose logging is enabled
+ */
+export declare function getVerboseFlag(config: {
+    public?: {
+        convex?: {
+            verbose?: boolean;
+        };
+    };
+}, override?: boolean): boolean;

package/dist/runtime/utils/logger.js

@@ -0,0 +1,49 @@
+import { getFunctionName } from "./convex-cache.js";
+export function createLogger(options) {
+  if (!options.verbose) {
+    return () => {
+    };
+  }
+  let fnName = options.functionName;
+  if (!fnName && options.functionRef) {
+    try {
+      fnName = getFunctionName(options.functionRef);
+    } catch {
+      fnName = "unknown";
+    }
+  }
+  const env = import.meta.server ? "[SSR]" : "[Client]";
+  const basePrefix = options.prefix;
+  const fullPrefix = fnName ? `${basePrefix} ${env} ${fnName}: ` : `${basePrefix} ${env} `;
+  return (message, data) => {
+    if (data !== void 0) {
+      console.log(fullPrefix + message, data);
+    } else {
+      console.log(fullPrefix + message);
+    }
+  };
+}
+export function createQueryLogger(verbose, composableName, query) {
+  return createLogger({
+    verbose,
+    prefix: `[bcn:${composableName}]`,
+    functionRef: query
+  });
+}
+export function createMutationLogger(verbose, composableName, mutation) {
+  return createLogger({
+    verbose,
+    prefix: `[bcn:${composableName}]`,
+    functionRef: mutation
+  });
+}
+export function createActionLogger(verbose, composableName, action) {
+  return createLogger({
+    verbose,
+    prefix: `[bcn:${composableName}]`,
+    functionRef: action
+  });
+}
+export function getVerboseFlag(config, override) {
+  return override ?? (config.public?.convex?.verbose ?? false);
+}

package/dist/runtime/utils/query-helpers.d.ts

@@ -1,33 +1,16 @@
 import type { useNuxtApp } from '#imports';
-import type { FunctionReference } from 'convex/server';
+import { createQueryLogger, type Logger } from './logger.js';
+export type QueryLogger = Logger;
+export { createQueryLogger };
 type NuxtApp = ReturnType<typeof useNuxtApp>;
 /**
  * Shared utilities for useConvexQuery and useConvexPaginatedQuery.
  * Extracted to reduce code duplication between the two composables.
  */
-/**
- * Logger function type for debug logging
- */
-export type QueryLogger = (message: string, data?: unknown) => void;
 /**
  * Subscription cache stored on NuxtApp
  */
 export type SubscriptionCache = Record<string, (() => void) | undefined>;
-/**
- * Create a debug logger for query composables.
- *
- * @param verbose - Whether logging is enabled
- * @param composableName - Name of the composable (e.g., 'useConvexQuery')
- * @param query - The Convex query function reference
- * @returns Logger function that logs with environment prefix
- *
- * @example
- * ```ts
- * const log = createQueryLogger(options?.verbose ?? false, 'useConvexQuery', query)
- * log('Initializing', { lazy, server })
- * ```
- */
-export declare function createQueryLogger(verbose: boolean, composableName: string, query: FunctionReference<'query'>): QueryLogger;
 export interface FetchAuthTokenOptions {
     /** Whether this is a public query (skip auth) */
     isPublic: boolean;
@@ -133,4 +116,3 @@ export declare function removeFromSubscriptionCache(nuxtApp: NuxtApp, cacheKey:
  * ```
  */
 export declare function buildThenableResult<T extends object>(resolvePromise: Promise<void>, resultData: T): T & Promise<T>;
-export {};

package/dist/runtime/utils/query-helpers.js

@@ -1,26 +1,6 @@
 import { useState } from "#imports";
-import { getFunctionName } from "./convex-cache.js";
-export function createQueryLogger(verbose, composableName, query) {
-  if (!verbose) {
-    return () => {
-    };
-  }
-  let fnName;
-  try {
-    fnName = getFunctionName(query);
-  } catch {
-    fnName = "unknown";
-  }
-  return (message, data) => {
-    const env = import.meta.server ? "[SSR]" : "[Client]";
-    const prefix = `[${composableName}] ${env} ${fnName}: `;
-    if (data !== void 0) {
-      console.log(prefix + message, data);
-    } else {
-      console.log(prefix + message);
-    }
-  };
-}
+import { createQueryLogger } from "./logger.js";
+export { createQueryLogger };
 export async function fetchAuthToken(options) {
   const { isPublic, cookieHeader, siteUrl, log } = options;
   if (isPublic) {

package/package.json

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