better-convex-nuxt 0.2.5 → 0.2.6

package/dist/module.d.mts

@@ -1,22 +1,7 @@
 import * as _nuxt_schema from '@nuxt/schema';
+import { LogLevel } from '../dist/runtime/utils/logger.js';
+export { LogLevel } from '../dist/runtime/utils/logger.js';
 
-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.
@@ -33,11 +18,57 @@ interface AuthCacheOptions {
      */
     ttl?: number;
 }
+/**
+ * Default options for query composables (useConvexQuery, useConvexPaginatedQuery).
+ * These can be overridden on a per-query basis.
+ */
+interface QueryDefaults {
+    /**
+     * Run query on server during SSR.
+     * @default true
+     */
+    server?: boolean;
+    /**
+     * Don't block navigation, load in background.
+     * @default false
+     */
+    lazy?: boolean;
+    /**
+     * Subscribe to real-time updates via WebSocket.
+     * @default true
+     */
+    subscribe?: boolean;
+    /**
+     * Skip auth checks for public queries.
+     * @default false
+     */
+    public?: boolean;
+}
 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. Required for authentication. */
+    /**
+     * Convex site URL (HTTP Actions) - e.g., https://your-app.convex.site.
+     * Used for HTTP Actions (webhooks, etc.) and required for authentication.
+     * If not provided, automatically derived from `url` by replacing .convex.cloud with .convex.site.
+     */
     siteUrl?: string;
+    /**
+     * Enable authentication features.
+     * When true, enables auth composables (useConvexAuth, useAuthClient) and SSR token exchange.
+     * In SSR mode, automatically creates the auth proxy route.
+     * Requires a valid Convex URL (to derive siteUrl) or an explicit siteUrl.
+     * Set to false to disable auth if you only need Convex without Better Auth.
+     * @default true
+     */
+    auth?: boolean;
+    /**
+     * Custom route path for the auth proxy.
+     * Defaults to '/api/auth'.
+     * The module will register a catch-all handler at `${authRoute}/**`.
+     * @default '/api/auth'
+     */
+    authRoute?: string;
     /**
      * Additional trusted origins for CORS validation on the auth proxy.
      * By default, only requests from the origin matching siteUrl are allowed.
@@ -60,10 +91,13 @@ interface ModuleOptions {
      */
     permissions?: boolean;
     /**
-     * Configure module logging behavior.
-     * Emits canonical log events for debugging SSR, auth, queries, and mutations.
+     * Enable module logging.
+     * - false: No logs (production default)
+     * - 'info': Simple logs for everyday use
+     * - 'debug': Detailed logs with timing for deep debugging
+     * @default false
      */
-    logging?: LoggingOptions;
+    logging?: LogLevel;
     /**
      * SSR auth token caching configuration (opt-in).
      * Caches Convex JWT tokens server-side to reduce TTFB on subsequent requests.
@@ -91,8 +125,26 @@ interface ModuleOptions {
      * ```
      */
     authCache?: AuthCacheOptions;
+    /**
+     * Default options for query composables (useConvexQuery, useConvexPaginatedQuery).
+     * Per-query options override these defaults.
+     *
+     * @example
+     * ```ts
+     * // nuxt.config.ts
+     * export default defineNuxtConfig({
+     *   convex: {
+     *     defaults: {
+     *       server: false,  // Disable SSR globally
+     *       lazy: true      // Enable lazy loading globally
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    defaults?: QueryDefaults;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { AuthCacheOptions, LoggingOptions, ModuleOptions };
+export type { AuthCacheOptions, ModuleOptions, QueryDefaults };

package/dist/module.json

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

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { useLogger, defineNuxtModule, createResolver, addPlugin, addServerHandler, addTemplate, addImports, addServerImports, addComponentsDir } from '@nuxt/kit';
+import { useLogger, defineNuxtModule, createResolver, addPlugin, addServerHandler, addTemplate, addImports, addComponentsDir, addServerImports } from '@nuxt/kit';
 import { defu } from 'defu';
 
 const logger = useLogger("better-convex-nuxt");
@@ -10,6 +10,13 @@ function isValidUrl(url) {
     return false;
   }
 }
+function deriveSiteUrl(url) {
+  if (!url) return void 0;
+  if (url.includes(".convex.cloud")) {
+    return url.replace(".convex.cloud", ".convex.site");
+  }
+  return void 0;
+}
 const module$1 = defineNuxtModule({
   meta: {
     name: "better-convex-nuxt",
@@ -21,17 +28,24 @@ const module$1 = defineNuxtModule({
   defaults: {
     url: process.env.CONVEX_URL,
     siteUrl: process.env.CONVEX_SITE_URL,
+    auth: true,
+    // Enabled by default - this is a better-auth integration module
+    authRoute: "/api/auth",
     trustedOrigins: [],
     skipAuthRoutes: [],
     permissions: false,
-    logging: {
-      enabled: false,
-      format: "pretty"
-    },
+    logging: false,
     authCache: {
       enabled: false,
       ttl: 900
       // 15 minutes
+    },
+    defaults: {
+      server: true,
+      // SSR enabled by default (like Nuxt's useFetch)
+      lazy: false,
+      subscribe: true,
+      public: false
     }
   },
   setup(options, nuxt) {
@@ -39,24 +53,35 @@ const module$1 = defineNuxtModule({
     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 resolvedSiteUrl = options.siteUrl || deriveSiteUrl(options.url || "");
+    if (resolvedSiteUrl && !isValidUrl(resolvedSiteUrl)) {
+      logger.warn(`Invalid Convex site URL format: "${resolvedSiteUrl}". Expected a valid URL like "https://your-app.convex.site"`);
+    }
+    const isAuthEnabled = options.auth === true;
+    const authRoute = options.authRoute || "/api/auth";
+    if (isAuthEnabled && !resolvedSiteUrl && options.url) {
+      logger.warn("auth: true but could not derive siteUrl from url. Set siteUrl explicitly for custom domains.");
     }
-    const derivedSiteUrl = options.siteUrl || "";
     const convexConfig = defu(
       nuxt.options.runtimeConfig.public.convex,
       {
         url: options.url || "",
-        siteUrl: derivedSiteUrl,
+        siteUrl: resolvedSiteUrl || "",
+        auth: isAuthEnabled,
+        authRoute,
         trustedOrigins: options.trustedOrigins ?? [],
         skipAuthRoutes: options.skipAuthRoutes ?? [],
-        logging: {
-          enabled: options.logging?.enabled ?? false,
-          format: options.logging?.format ?? "pretty"
-        },
+        logging: options.logging ?? false,
         authCache: {
           enabled: options.authCache?.enabled ?? false,
           ttl: options.authCache?.ttl ?? 900
+        },
+        defaults: {
+          server: options.defaults?.server ?? true,
+          // SSR enabled by default
+          lazy: options.defaults?.lazy ?? false,
+          subscribe: options.defaults?.subscribe ?? true,
+          public: options.defaults?.public ?? false
         }
       }
     );
@@ -66,10 +91,12 @@ const module$1 = defineNuxtModule({
       mode: "server"
     });
     addPlugin(resolver.resolve("./runtime/plugin.client"));
-    addServerHandler({
-      route: "/api/auth/**",
-      handler: resolver.resolve("./runtime/server/api/auth/[...]")
-    });
+    if (isAuthEnabled && nuxt.options.ssr) {
+      addServerHandler({
+        route: `${authRoute}/**`,
+        handler: resolver.resolve("./runtime/server/api/auth/[...]")
+      });
+    }
     addTemplate({
       filename: "types/better-convex-nuxt.d.ts",
       getContents: () => `
@@ -104,14 +131,12 @@ export {}
 `
     });
     addImports([
-      { name: "useConvexAuth", from: resolver.resolve("./runtime/composables/useConvexAuth") },
       { name: "useConvex", from: resolver.resolve("./runtime/composables/useConvex") },
       {
         name: "useConvexMutation",
         from: resolver.resolve("./runtime/composables/useConvexMutation")
       },
       { 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: "getQueryKey", from: resolver.resolve("./runtime/composables/useConvexQuery") },
       {
@@ -133,7 +158,7 @@ export {}
         name: "deleteFromQuery",
         from: resolver.resolve("./runtime/composables/useConvexMutation")
       },
-      // Optimistic update helpers for paginated queries (already available from useConvexPaginatedQuery)
+      // Optimistic update helpers for paginated queries
       {
         name: "insertAtTop",
         from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
@@ -164,6 +189,16 @@ export {}
         from: resolver.resolve("./runtime/composables/useConvexStorageUrl")
       }
     ]);
+    if (isAuthEnabled) {
+      addImports([
+        { name: "useConvexAuth", from: resolver.resolve("./runtime/composables/useConvexAuth") },
+        { name: "useAuthClient", from: resolver.resolve("./runtime/composables/useAuthClient") }
+      ]);
+      addComponentsDir({
+        path: resolver.resolve("./runtime/components"),
+        global: true
+      });
+    }
     if (options.permissions) {
       addImports([
         {
@@ -178,10 +213,6 @@ export {}
       { 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"),
-      global: true
-    });
     nuxt.hook("prepare:types", (opts) => {
       opts.references.push({
         path: resolver.resolve(nuxt.options.buildDir, "types/better-convex-nuxt.d.ts")

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

@@ -4,6 +4,7 @@
 declare function retry(): void;
 declare var __VLS_1: {
     retry: typeof retry;
+    error: string | null;
 };
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;

package/dist/runtime/components/ConvexAuthError.vue

@@ -1,10 +1,11 @@
 <script setup>
 import { computed } from "vue";
 import { useConvexAuth } from "../composables/useConvexAuth";
-const { isAuthenticated, isPending, token, user } = useConvexAuth();
+const { isAuthenticated, isPending, token, user, authError } = useConvexAuth();
 const hasError = computed(() => {
   if (isPending.value) return false;
   if (isAuthenticated.value) return false;
+  if (authError.value) return true;
   if (token.value && !user.value) return true;
   return false;
 });
@@ -14,5 +15,5 @@ function retry() {
 </script>
 
 <template>
-  <slot v-if="hasError" :retry="retry" />
+  <slot v-if="hasError" :retry="retry" :error="authError" />
 </template>

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

@@ -4,6 +4,7 @@
 declare function retry(): void;
 declare var __VLS_1: {
     retry: typeof retry;
+    error: string | null;
 };
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;