better-convex-nuxt 0.2.3 → 0.2.5

package/dist/module.d.mts

@@ -36,7 +36,7 @@ interface AuthCacheOptions {
 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. */
+    /** Convex site URL (HTTP/Auth) - e.g., https://your-app.convex.site. Required for authentication. */
     siteUrl?: string;
     /**
      * Additional trusted origins for CORS validation on the auth proxy.

package/dist/module.json

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

package/dist/module.mjs

@@ -42,7 +42,7 @@ const module$1 = defineNuxtModule({
     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 derivedSiteUrl = options.siteUrl || "";
     const convexConfig = defu(
       nuxt.options.runtimeConfig.public.convex,
       {

package/dist/runtime/composables/useConvexQuery.js

@@ -8,9 +8,8 @@ import {
   computeQueryStatus,
   fetchAuthToken,
   registerSubscription,
-  hasSubscription,
-  removeFromSubscriptionCache,
-  cleanupSubscription
+  getSubscription,
+  releaseSubscription
 } from "../utils/convex-cache.js";
 import { createModuleLogger, getLoggingOptions } from "../utils/logger.js";
 let devToolsRegistryPromise = null;
@@ -130,12 +129,14 @@ export function useConvexQuery(query, args, options) {
   const status = computed(() => {
     return computeQueryStatus(
       isSkipped.value,
-      asyncData.error.value !== null,
+      asyncData.error.value != null,
+      // != catches both null AND undefined (strict !== would fail on undefined)
       pending.value,
-      asyncData.data.value !== null && asyncData.data.value !== void 0
+      asyncData.data.value != null
+      // Simplified: != null covers both null and undefined
     );
   });
-  let unsubscribeFn = null;
+  let registeredCacheKey = null;
   if (import.meta.client && subscribe) {
     const setupSubscription = () => {
       const currentArgs = getArgs();
@@ -147,12 +148,15 @@ export function useConvexQuery(query, args, options) {
         return;
       }
       const currentCacheKey = getCacheKey();
-      if (hasSubscription(nuxtApp, currentCacheKey)) {
+      const existingEntry = getSubscription(nuxtApp, currentCacheKey);
+      if (existingEntry) {
+        existingEntry.refCount++;
+        registeredCacheKey = currentCacheKey;
         return;
       }
       try {
         updateCount = 0;
-        unsubscribeFn = convex.onUpdate(
+        const unsubscribeFn = convex.onUpdate(
           query,
           currentArgs,
           (result) => {
@@ -194,6 +198,7 @@ export function useConvexQuery(query, args, options) {
           }
         );
         registerSubscription(nuxtApp, currentCacheKey, unsubscribeFn);
+        registeredCacheKey = currentCacheKey;
         logger.event({
           event: "subscription:change",
           env: "client",
@@ -238,17 +243,18 @@ export function useConvexQuery(query, args, options) {
         () => toValue(args),
         (newArgs, oldArgs) => {
           if (hashArgs(newArgs) !== hashArgs(oldArgs)) {
-            if (oldArgs !== "skip" && unsubscribeFn) {
-              const oldCacheKey = getQueryKey(query, oldArgs);
-              logger.event({
-                event: "subscription:change",
-                env: "client",
-                name: fnName,
-                state: "unsubscribed",
-                updates_received: updateCount
-              });
-              cleanupSubscription(nuxtApp, oldCacheKey);
-              unsubscribeFn = null;
+            if (oldArgs !== "skip" && registeredCacheKey) {
+              const wasUnsubscribed = releaseSubscription(nuxtApp, registeredCacheKey);
+              if (wasUnsubscribed) {
+                logger.event({
+                  event: "subscription:change",
+                  env: "client",
+                  name: fnName,
+                  state: "unsubscribed",
+                  updates_received: updateCount
+                });
+              }
+              registeredCacheKey = null;
             }
             if (newArgs !== "skip") {
               setupSubscription();
@@ -259,19 +265,19 @@ export function useConvexQuery(query, args, options) {
       );
     }
     onUnmounted(() => {
-      if (unsubscribeFn) {
-        const currentCacheKey = getCacheKey();
-        logger.event({
-          event: "subscription:change",
-          env: "client",
-          name: fnName,
-          state: "unsubscribed",
-          updates_received: updateCount
-        });
-        removeFromSubscriptionCache(nuxtApp, currentCacheKey);
-        unsubscribeFn();
-        unsubscribeFn = null;
-        devToolsRegistry?.unregisterQuery(currentCacheKey);
+      if (registeredCacheKey) {
+        const wasUnsubscribed = releaseSubscription(nuxtApp, registeredCacheKey);
+        if (wasUnsubscribed) {
+          logger.event({
+            event: "subscription:change",
+            env: "client",
+            name: fnName,
+            state: "unsubscribed",
+            updates_received: updateCount
+          });
+          devToolsRegistry?.unregisterQuery(registeredCacheKey);
+        }
+        registeredCacheKey = null;
       }
     });
   }

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.CXPHzcHp.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/DRR5kXdS.js"><script type="module" src="/__convex_devtools__/_nuxt/DRR5kXdS.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:"2402f38c-d12f-4c0b-846f-2ad2f104951f",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1768333345265,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.CXPHzcHp.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/DRR5kXdS.js"><script type="module" src="/__convex_devtools__/_nuxt/DRR5kXdS.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:"e830e57d-37c5-4c85-b066-5cda3df527f3",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1768510467224,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.CXPHzcHp.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/DRR5kXdS.js"><script type="module" src="/__convex_devtools__/_nuxt/DRR5kXdS.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:"2402f38c-d12f-4c0b-846f-2ad2f104951f",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1768333345266,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.CXPHzcHp.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/DRR5kXdS.js"><script type="module" src="/__convex_devtools__/_nuxt/DRR5kXdS.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:"e830e57d-37c5-4c85-b066-5cda3df527f3",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1768510467224,false]</script></body></html>

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

@@ -1 +1 @@
-{"id":"2402f38c-d12f-4c0b-846f-2ad2f104951f","timestamp":1768333343049}
+{"id":"e830e57d-37c5-4c85-b066-5cda3df527f3","timestamp":1768510464889}

package/dist/runtime/devtools/ui/dist/_nuxt/builds/meta/e830e57d-37c5-4c85-b066-5cda3df527f3.json

@@ -0,0 +1 @@
+{"id":"e830e57d-37c5-4c85-b066-5cda3df527f3","timestamp":1768510464889,"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.CXPHzcHp.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/DRR5kXdS.js"><script type="module" src="/__convex_devtools__/_nuxt/DRR5kXdS.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:"2402f38c-d12f-4c0b-846f-2ad2f104951f",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1768333345266,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.CXPHzcHp.css" crossorigin><link rel="modulepreload" as="script" crossorigin href="/__convex_devtools__/_nuxt/DRR5kXdS.js"><script type="module" src="/__convex_devtools__/_nuxt/DRR5kXdS.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:"e830e57d-37c5-4c85-b066-5cda3df527f3",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script><script type="application/json" data-nuxt-data="nuxt-app" data-ssr="false" id="__NUXT_DATA__">[{"prerenderedAt":1,"serverRendered":2},1768510467224,false]</script></body></html>

package/dist/runtime/plugin.client.js

@@ -34,7 +34,7 @@ export default defineNuxtPlugin((nuxtApp) => {
   if (nuxtApp._convexInitialized) return;
   nuxtApp._convexInitialized = true;
   const convexUrl = config.public.convex?.url;
-  const siteUrl = config.public.convex?.siteUrl || convexUrl?.replace(".convex.cloud", ".convex.site");
+  const siteUrl = config.public.convex?.siteUrl;
   if (!convexUrl) {
     logger.event({
       event: "plugin:init",

package/dist/runtime/types.d.ts

@@ -3,6 +3,25 @@ import type { ConvexClient } from 'convex/browser'
 
 type AuthClient = ReturnType<typeof createAuthClient>
 
+/**
+ * Convex module public runtime config
+ */
+export interface ConvexPublicRuntimeConfig {
+  /** Convex deployment URL (WebSocket) */
+  url?: string
+  /** Convex site URL (HTTP/Auth) */
+  siteUrl?: string
+  /** Routes that should skip auth checks */
+  skipAuthRoutes?: string[]
+  /** Logging options */
+  logging?: {
+    enabled?: boolean | 'debug'
+    format?: 'pretty' | 'json'
+  }
+  /** Index signature for compatibility with Record<string, unknown> */
+  [key: string]: unknown
+}
+
 declare module '#app' {
   interface NuxtApp {
     $convex: ConvexClient
@@ -19,4 +38,19 @@ declare module 'vue' {
   }
 }
 
+declare module 'nuxt/schema' {
+  interface PublicRuntimeConfig {
+    convex?: ConvexPublicRuntimeConfig
+  }
+  interface RuntimeConfig {
+    convexDevtoolsPath?: string
+  }
+  interface NuxtConfig {
+    convex?: ConvexPublicRuntimeConfig
+  }
+  interface NuxtOptions {
+    convex?: ConvexPublicRuntimeConfig
+  }
+}
+
 export {}

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

@@ -1,10 +1,18 @@
 import { type useNuxtApp } from '#app';
 export { type QueryStatus, parseConvexResponse, computeQueryStatus, getFunctionName, hashArgs, getQueryKey, } from './convex-shared.js';
 type NuxtApp = ReturnType<typeof useNuxtApp>;
+/**
+ * Subscription entry with reference counting.
+ * Multiple components can share the same subscription.
+ */
+export interface SubscriptionEntry {
+    unsubscribe: () => void;
+    refCount: number;
+}
 /**
  * Subscription cache stored on NuxtApp
  */
-export type SubscriptionCache = Record<string, (() => void) | undefined>;
+export type SubscriptionCache = Record<string, SubscriptionEntry | undefined>;
 export interface FetchAuthTokenOptions {
     /** Whether this is a public query (skip auth) */
     isPublic: boolean;
@@ -58,13 +66,15 @@ export declare function getCachedAuthToken(): string | undefined;
  */
 export declare function getSubscriptionCache(nuxtApp: NuxtApp): SubscriptionCache;
 /**
- * Register a subscription in the cache.
+ * Register a subscription in the cache with reference counting.
+ * If a subscription already exists, increments the ref count instead of replacing.
  *
  * @param nuxtApp - The NuxtApp instance
  * @param cacheKey - Unique key for this subscription
  * @param unsubscribe - The unsubscribe function
+ * @returns true if this component should manage the subscription (first registrant), false if joining existing
  */
-export declare function registerSubscription(nuxtApp: NuxtApp, cacheKey: string, unsubscribe: () => void): void;
+export declare function registerSubscription(nuxtApp: NuxtApp, cacheKey: string, unsubscribe: () => void): boolean;
 /**
  * Check if a subscription already exists in the cache.
  *
@@ -73,23 +83,35 @@ export declare function registerSubscription(nuxtApp: NuxtApp, cacheKey: string,
  * @returns True if subscription exists
  */
 export declare function hasSubscription(nuxtApp: NuxtApp, cacheKey: string): boolean;
+/**
+ * Get the current subscription entry from the cache.
+ *
+ * @param nuxtApp - The NuxtApp instance
+ * @param cacheKey - Unique key for this subscription
+ * @returns The subscription entry if it exists, undefined otherwise
+ */
+export declare function getSubscription(nuxtApp: NuxtApp, cacheKey: string): SubscriptionEntry | undefined;
+/**
+ * Decrement reference count and cleanup subscription if no more references.
+ * Returns true if the subscription was actually unsubscribed.
+ *
+ * @param nuxtApp - The NuxtApp instance
+ * @param cacheKey - Unique key for this subscription
+ * @returns true if subscription was unsubscribed, false if still has references
+ */
+export declare function releaseSubscription(nuxtApp: NuxtApp, cacheKey: string): boolean;
 /**
  * Clean up a subscription from the cache.
  * Calls the unsubscribe function and removes from cache.
+ * DEPRECATED: Use releaseSubscription for ref-counted cleanup.
  *
  * @param nuxtApp - The NuxtApp instance
  * @param cacheKey - Unique key for this subscription
- *
- * @example
- * ```ts
- * // In cleanup/unmount
- * cleanupSubscription(nuxtApp, cacheKey)
- * ```
  */
 export declare function cleanupSubscription(nuxtApp: NuxtApp, cacheKey: string): void;
 /**
  * Remove a subscription from the cache without calling unsubscribe.
- * Use this when you've already called unsubscribe manually.
+ * DEPRECATED: Use releaseSubscription for ref-counted cleanup.
  *
  * @param nuxtApp - The NuxtApp instance
  * @param cacheKey - Unique key for this subscription

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

@@ -46,17 +46,41 @@ export function getSubscriptionCache(nuxtApp) {
 }
 export function registerSubscription(nuxtApp, cacheKey, unsubscribe) {
   const cache = getSubscriptionCache(nuxtApp);
-  cache[cacheKey] = unsubscribe;
+  const existing = cache[cacheKey];
+  if (existing) {
+    existing.refCount++;
+    return false;
+  }
+  cache[cacheKey] = { unsubscribe, refCount: 1 };
+  return true;
 }
 export function hasSubscription(nuxtApp, cacheKey) {
   const cache = getSubscriptionCache(nuxtApp);
   return !!cache[cacheKey];
 }
+export function getSubscription(nuxtApp, cacheKey) {
+  const cache = getSubscriptionCache(nuxtApp);
+  return cache[cacheKey];
+}
+export function releaseSubscription(nuxtApp, cacheKey) {
+  const cache = getSubscriptionCache(nuxtApp);
+  const entry = cache[cacheKey];
+  if (!entry) {
+    return false;
+  }
+  entry.refCount--;
+  if (entry.refCount <= 0) {
+    entry.unsubscribe();
+    cache[cacheKey] = void 0;
+    return true;
+  }
+  return false;
+}
 export function cleanupSubscription(nuxtApp, cacheKey) {
   const cache = getSubscriptionCache(nuxtApp);
-  const unsubscribe = cache[cacheKey];
-  if (unsubscribe) {
-    unsubscribe();
+  const entry = cache[cacheKey];
+  if (entry) {
+    entry.unsubscribe();
     cache[cacheKey] = void 0;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-convex-nuxt",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Full-featured Convex integration for Nuxt with SSR, real-time subscriptions, authentication, and permissions",
   "keywords": [
     "authentication",
@@ -57,7 +57,7 @@
     "dev": "npm run dev:prepare && nuxi dev playground",
     "dev:build": "nuxi build playground",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
-    "release": "npm run lint && npm run test && npm run prepack && git fetch --prune --prune-tags --tags --force origin && changelogen --release && npm publish && git push --follow-tags",
+    "release": "npm run lint && npm run test && npm run prepack && git tag -l | xargs git tag -d && git fetch --tags origin && changelogen --release && npm publish && git push --follow-tags",
     "lint": "eslint .",
     "format": "oxfmt",
     "format:check": "oxfmt --check",

package/dist/runtime/devtools/ui/dist/_nuxt/builds/meta/2402f38c-d12f-4c0b-846f-2ad2f104951f.json

@@ -1 +0,0 @@
-{"id":"2402f38c-d12f-4c0b-846f-2ad2f104951f","timestamp":1768333343049,"matcher":{"static":{},"wildcard":{},"dynamic":{}},"prerendered":[]}