use-convex 0.0.2

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

@@ -0,0 +1,53 @@
+import type { AuthTokenFetcher, ConvexClient, ConvexHttpClient } from 'convex/browser';
+import type { ComputedRef, InjectionKey, Ref } from 'vue';
+export interface ConvexAuthContext {
+    /**
+     * Whether useConvexAuth({ fetchToken }) has been called.
+     */
+    configured: boolean;
+    fetchToken: AuthTokenFetcher | null;
+    providerLoading: Ref<boolean>;
+    providerAuthenticated: Ref<boolean>;
+    /**
+     * Backend confirmation. `null` = waiting for Convex onChange.
+     */
+    isConvexAuthenticated: Ref<boolean | null>;
+    isRefreshingRaw: Ref<boolean>;
+    /** Derived UI flags (written by useConvexAuth). */
+    isLoading: Ref<boolean>;
+    isAuthenticated: Ref<boolean>;
+    isRefreshing: Ref<boolean>;
+}
+export interface ConvexNuxtContext {
+    url: string;
+    /**
+     * Live WebSocket client. Only available in the browser plugin.
+     */
+    client: ConvexClient | null;
+    /**
+     * JWT from the optional auth cookie. Reactive so sign-in/out updates
+     * HttpClient refreshes and `hasSsrSession`.
+     */
+    ssrToken: ComputedRef<string | undefined>;
+    /**
+     * Shared auth state for useConvexAuth.
+     */
+    auth: ConvexAuthContext;
+    /**
+     * Create a fresh HttpClient for one-shot fetches (SSR / Nitro / refresh).
+     * Prefer a new client per call — HttpClient is stateful.
+     */
+    createHttpClient: (options?: {
+        token?: string;
+    }) => ConvexHttpClient;
+}
+export declare const convexNuxtKey: InjectionKey<ConvexNuxtContext>;
+export declare function createAuthContext(): ConvexAuthContext;
+/**
+ * Resolve Convex context from Nuxt `$convex` provide and/or Vue inject.
+ *
+ * Prefer `$convex` so async plugins can still read context after `await`
+ * (Vue `inject()` only works synchronously inside setup).
+ */
+export declare function tryUseConvexContext(): ConvexNuxtContext | null;
+export declare function useConvexContext(): ConvexNuxtContext;

package/dist/runtime/utils/context.js

@@ -0,0 +1,41 @@
+import { inject, ref } from "vue";
+import { useNuxtApp } from "nuxt/app";
+export const convexNuxtKey = Symbol("convex-nuxt");
+export function createAuthContext() {
+  return {
+    configured: false,
+    fetchToken: null,
+    providerLoading: ref(false),
+    providerAuthenticated: ref(false),
+    isConvexAuthenticated: ref(null),
+    isRefreshingRaw: ref(false),
+    // Default: no auth wired → not loading, not authenticated.
+    isLoading: ref(false),
+    isAuthenticated: ref(false),
+    isRefreshing: ref(false)
+  };
+}
+export function tryUseConvexContext() {
+  try {
+    const app = useNuxtApp();
+    const fromNuxt = app.$convex;
+    if (fromNuxt) {
+      return fromNuxt;
+    }
+  } catch {
+  }
+  try {
+    return inject(convexNuxtKey, null);
+  } catch {
+    return null;
+  }
+}
+export function useConvexContext() {
+  const ctx = tryUseConvexContext();
+  if (!ctx) {
+    throw new Error(
+      "[convex-nuxt] Convex plugin did not start \u2014 set convex.url or NUXT_PUBLIC_CONVEX_URL (the module no-ops when the URL is empty)."
+    );
+  }
+  return ctx;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Resolve the JWT for a Nitro `fetch*` call.
+ * Explicit `token` wins; otherwise use the cookie value from the event.
+ */
+export declare function resolveFetchToken(options: {
+    token?: string;
+    cookieName?: string;
+    cookieValue?: string | null;
+}): string | undefined;

package/dist/runtime/utils/fetchToken.js

@@ -0,0 +1,6 @@
+export function resolveFetchToken(options) {
+  if (options.token !== void 0) {
+    return options.token || void 0;
+  }
+  return options.cookieValue || void 0;
+}

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

@@ -0,0 +1,10 @@
+import { ConvexHttpClient } from 'convex/browser';
+export interface CreateHttpClientOptions {
+    token?: string;
+    skipConvexDeploymentUrlCheck?: boolean;
+}
+/**
+ * Construct a fresh ConvexHttpClient for a single request.
+ * Matches the convex/nextjs pattern: new client, optional auth, no-store fetch.
+ */
+export declare function createHttpClient(url: string, options?: CreateHttpClientOptions): ConvexHttpClient;

package/dist/runtime/utils/http.js

@@ -0,0 +1,13 @@
+import { ConvexHttpClient } from "convex/browser";
+export function createHttpClient(url, options = {}) {
+  const client = new ConvexHttpClient(url, {
+    skipConvexDeploymentUrlCheck: options.skipConvexDeploymentUrlCheck,
+    ...options.token ? { auth: options.token } : {}
+  });
+  if (options.token) {
+    client.setAuth(options.token);
+  }
+  ;
+  client.setFetchOptions({ cache: "no-store" });
+  return client;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Validate an OAuth redirect from Convex `auth:signIn`.
+ * Only http(s) absolute URLs are allowed (blocks javascript:/data: etc.).
+ */
+export declare function parseOAuthRedirect(redirect: string): URL;

package/dist/runtime/utils/oauthRedirect.js

@@ -0,0 +1,12 @@
+export function parseOAuthRedirect(redirect) {
+  let url;
+  try {
+    url = new URL(redirect);
+  } catch {
+    throw new Error("Invalid OAuth redirect URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("OAuth redirect must be http(s)");
+  }
+  return url;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Resolve SSR payload vs live subscription — Nuxt equivalent of
+ * Next.js `usePreloadedQuery`: `live === undefined ? payload : live`.
+ */
+export declare function resolveQueryOverlay<T>(input: {
+    skipped: boolean;
+    liveReady: boolean;
+    liveData: T | undefined;
+    liveError: Error | null;
+    payload: T | null | undefined;
+    payloadError: Error | null | undefined;
+    payloadPending: boolean;
+}): {
+    data: T | null | undefined;
+    error: Error | null;
+    pending: boolean;
+    status: 'pending' | 'success' | 'error';
+};

package/dist/runtime/utils/overlay.js

@@ -0,0 +1,48 @@
+export function resolveQueryOverlay(input) {
+  if (input.skipped) {
+    return {
+      data: input.payload,
+      error: null,
+      pending: false,
+      status: "success"
+    };
+  }
+  if (input.liveReady) {
+    if (input.liveError) {
+      return {
+        data: input.liveData,
+        error: input.liveError,
+        pending: false,
+        status: "error"
+      };
+    }
+    return {
+      data: input.liveData,
+      error: null,
+      pending: false,
+      status: "success"
+    };
+  }
+  if (input.payloadError) {
+    return {
+      data: input.payload,
+      error: input.payloadError,
+      pending: false,
+      status: "error"
+    };
+  }
+  if (input.payloadPending) {
+    return {
+      data: input.payload,
+      error: null,
+      pending: true,
+      status: "pending"
+    };
+  }
+  return {
+    data: input.payload,
+    error: null,
+    pending: false,
+    status: "success"
+  };
+}

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

@@ -0,0 +1,37 @@
+import type { OptimisticLocalStore } from 'convex/browser';
+import type { Value } from 'convex/values';
+import type { PaginatedQueryArgs, PaginatedQueryItem, PaginatedQueryReference } from '../composables/useConvexPaginatedQuery.js';
+/**
+ * Apply an optimistic update to every loaded page of a paginated query
+ * (React `optimisticallyUpdateValueInPaginatedQuery` parity).
+ */
+export declare function optimisticallyUpdateValueInPaginatedQuery<Query extends PaginatedQueryReference>(localStore: OptimisticLocalStore, query: Query, args: PaginatedQueryArgs<Query>, updateValue: (currentValue: PaginatedQueryItem<Query>) => PaginatedQueryItem<Query>): void;
+/**
+ * Insert an item at the top of a paginated list's first loaded page.
+ */
+export declare function insertAtTop<Query extends PaginatedQueryReference>(options: {
+    paginatedQuery: Query;
+    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
+    localQueryStore: OptimisticLocalStore;
+    item: PaginatedQueryItem<Query>;
+}): void;
+/**
+ * Insert an item at the bottom of a paginated list only if the last page is loaded.
+ */
+export declare function insertAtBottomIfLoaded<Query extends PaginatedQueryReference>(options: {
+    paginatedQuery: Query;
+    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
+    localQueryStore: OptimisticLocalStore;
+    item: PaginatedQueryItem<Query>;
+}): void;
+/**
+ * Insert an item at a sort-key position within loaded paginated pages.
+ */
+export declare function insertAtPosition<Query extends PaginatedQueryReference>(options: {
+    paginatedQuery: Query;
+    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
+    sortOrder: 'asc' | 'desc';
+    sortKeyFromItem: (element: PaginatedQueryItem<Query>) => Value | Value[];
+    localQueryStore: OptimisticLocalStore;
+    item: PaginatedQueryItem<Query>;
+}): void;

package/dist/runtime/utils/paginatedOptimistic.js

@@ -0,0 +1,178 @@
+import { compareValues, convexToJson } from "convex/values";
+export function optimisticallyUpdateValueInPaginatedQuery(localStore, query, args, updateValue) {
+  const expectedArgs = JSON.stringify(convexToJson(args));
+  for (const queryResult of localStore.getAllQueries(query)) {
+    if (queryResult.value === void 0) {
+      continue;
+    }
+    const { paginationOpts: _, ...innerArgs } = queryResult.args;
+    if (JSON.stringify(convexToJson(innerArgs)) !== expectedArgs) {
+      continue;
+    }
+    const value = queryResult.value;
+    if (typeof value === "object" && value !== null && Array.isArray(value.page)) {
+      localStore.setQuery(query, queryResult.args, {
+        ...value,
+        page: value.page.map(
+          updateValue
+        )
+      });
+    }
+  }
+}
+export function insertAtTop(options) {
+  const { paginatedQuery, argsToMatch, localQueryStore, item } = options;
+  const queries = localQueryStore.getAllQueries(paginatedQuery);
+  const matching = queries.filter((q) => {
+    if (argsToMatch === void 0) {
+      return true;
+    }
+    return Object.keys(argsToMatch).every(
+      // @ts-expect-error both are plain objects
+      (key) => compareValues(argsToMatch[key], q.args[key]) === 0
+    );
+  });
+  const firstPage = matching.find(
+    (q) => q.args.paginationOpts.cursor === null
+  );
+  if (firstPage === void 0 || firstPage.value === void 0) {
+    return;
+  }
+  localQueryStore.setQuery(paginatedQuery, firstPage.args, {
+    ...firstPage.value,
+    page: [item, ...firstPage.value.page]
+  });
+}
+export function insertAtBottomIfLoaded(options) {
+  const { paginatedQuery, localQueryStore, item, argsToMatch } = options;
+  const queries = localQueryStore.getAllQueries(paginatedQuery);
+  const matching = queries.filter((q) => {
+    if (argsToMatch === void 0) {
+      return true;
+    }
+    return Object.keys(argsToMatch).every(
+      // @ts-expect-error both are plain objects
+      (key) => compareValues(argsToMatch[key], q.args[key]) === 0
+    );
+  });
+  const lastPage = matching.find(
+    (q) => q.value !== void 0 && q.value.isDone
+  );
+  if (lastPage === void 0 || lastPage.value === void 0) {
+    return;
+  }
+  localQueryStore.setQuery(paginatedQuery, lastPage.args, {
+    ...lastPage.value,
+    page: [...lastPage.value.page, item]
+  });
+}
+export function insertAtPosition(options) {
+  const {
+    paginatedQuery,
+    sortOrder,
+    sortKeyFromItem,
+    localQueryStore,
+    item,
+    argsToMatch
+  } = options;
+  const queries = localQueryStore.getAllQueries(paginatedQuery);
+  const queryGroups = {};
+  for (const query of queries) {
+    if (argsToMatch !== void 0 && !Object.keys(argsToMatch).every(
+      // @ts-expect-error both are plain objects
+      (key2) => argsToMatch[key2] === query.args[key2]
+    )) {
+      continue;
+    }
+    const key = JSON.stringify(
+      Object.fromEntries(
+        Object.entries(query.args).map(([k, v]) => [
+          k,
+          k === "paginationOpts" ? v.id : v
+        ])
+      )
+    );
+    queryGroups[key] ??= [];
+    queryGroups[key].push(query);
+  }
+  for (const pageQueries of Object.values(queryGroups)) {
+    insertAtPositionInPages({
+      pageQueries,
+      paginatedQuery,
+      sortOrder,
+      sortKeyFromItem,
+      localQueryStore,
+      item
+    });
+  }
+}
+function insertAtPositionInPages(options) {
+  const {
+    pageQueries,
+    sortOrder,
+    sortKeyFromItem,
+    localQueryStore,
+    item,
+    paginatedQuery
+  } = options;
+  const insertedKey = sortKeyFromItem(item);
+  const loadedPages = pageQueries.filter(
+    (q) => q.value !== void 0 && q.value.page.length > 0
+  );
+  const sortedPages = loadedPages.sort((a, b) => {
+    const aKey = sortKeyFromItem(a.value.page[0]);
+    const bKey = sortKeyFromItem(b.value.page[0]);
+    return sortOrder === "asc" ? compareValues(aKey, bKey) : compareValues(bKey, aKey);
+  });
+  const firstLoadedPage = sortedPages[0];
+  if (firstLoadedPage === void 0) {
+    return;
+  }
+  const firstPageKey = sortKeyFromItem(firstLoadedPage.value.page[0]);
+  const isBeforeFirstPage = sortOrder === "asc" ? compareValues(insertedKey, firstPageKey) <= 0 : compareValues(insertedKey, firstPageKey) >= 0;
+  if (isBeforeFirstPage) {
+    if (firstLoadedPage.args.paginationOpts.cursor === null) {
+      localQueryStore.setQuery(paginatedQuery, firstLoadedPage.args, {
+        ...firstLoadedPage.value,
+        page: [item, ...firstLoadedPage.value.page]
+      });
+    }
+    return;
+  }
+  const lastLoadedPage = sortedPages[sortedPages.length - 1];
+  if (lastLoadedPage === void 0) {
+    return;
+  }
+  const lastPageKey = sortKeyFromItem(
+    lastLoadedPage.value.page[lastLoadedPage.value.page.length - 1]
+  );
+  const isAfterLastPage = sortOrder === "asc" ? compareValues(insertedKey, lastPageKey) >= 0 : compareValues(insertedKey, lastPageKey) <= 0;
+  if (isAfterLastPage) {
+    if (lastLoadedPage.value.isDone) {
+      localQueryStore.setQuery(paginatedQuery, lastLoadedPage.args, {
+        ...lastLoadedPage.value,
+        page: [...lastLoadedPage.value.page, item]
+      });
+    }
+    return;
+  }
+  const successorPageIndex = sortedPages.findIndex(
+    (p) => sortOrder === "asc" ? compareValues(sortKeyFromItem(p.value.page[0]), insertedKey) > 0 : compareValues(sortKeyFromItem(p.value.page[0]), insertedKey) < 0
+  );
+  const pageToUpdate = successorPageIndex === -1 ? sortedPages[sortedPages.length - 1] : sortedPages[successorPageIndex - 1];
+  if (pageToUpdate === void 0) {
+    return;
+  }
+  const indexWithinPage = pageToUpdate.value.page.findIndex(
+    (element) => sortOrder === "asc" ? compareValues(sortKeyFromItem(element), insertedKey) >= 0 : compareValues(sortKeyFromItem(element), insertedKey) <= 0
+  );
+  const newPage = indexWithinPage === -1 ? [...pageToUpdate.value.page, item] : [
+    ...pageToUpdate.value.page.slice(0, indexWithinPage),
+    item,
+    ...pageToUpdate.value.page.slice(indexWithinPage)
+  ];
+  localQueryStore.setQuery(paginatedQuery, pageToUpdate.args, {
+    ...pageToUpdate.value,
+    page: newPage
+  });
+}

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

@@ -0,0 +1,8 @@
+import type { FunctionReference } from 'convex/server';
+/**
+ * Stable Nuxt payload / useAsyncData key for a Convex query.
+ *
+ * `'skip'` means "don't fetch" — it must not change the key, otherwise
+ * auth-gated queries lose the SSR payload on the client.
+ */
+export declare function convexQueryKey(query: FunctionReference<'query'>, args: unknown, explicitKey?: string): string;

package/dist/runtime/utils/queryKey.js

@@ -0,0 +1,11 @@
+import { getFunctionName } from "convex/server";
+import { convexToJson } from "convex/values";
+export function convexQueryKey(query, args, explicitKey) {
+  if (explicitKey) {
+    return explicitKey;
+  }
+  const name = getFunctionName(query);
+  const keyArgs = args === "skip" ? {} : args ?? {};
+  const argsJson = convexToJson(keyArgs);
+  return `convex:${name}:${JSON.stringify(argsJson)}`;
+}

package/dist/types.d.mts

@@ -0,0 +1,29 @@
+import type { ModulePublicRuntimeConfig } from './module.mjs'
+
+declare module '@nuxt/schema' {
+  interface PublicRuntimeConfig extends ModulePublicRuntimeConfig {}
+}
+
+export { type AuthTokens, type SignInResult, type UseAuthReturn } from '../dist/runtime/composables/useAuth.js'
+
+export { type ConvexQueryArgs, type UseConvexQueryOptions, type UseConvexQueryReturn } from '../dist/runtime/composables/useConvexQuery.js'
+
+export { type AuthTokenFetcher, type UseConvexAuthReturn, type UseConvexAuthSetupOptions } from '../dist/runtime/composables/useConvexAuth.js'
+
+export { type UseConvexMutationOptions } from '../dist/runtime/composables/useConvexMutation.js'
+
+export { type PaginatedQueryReference, type PaginationStatus, type UseConvexPaginatedQueryOptions, type UseConvexPaginatedQueryReturn } from '../dist/runtime/composables/useConvexPaginatedQuery.js'
+
+export { type ConvexQueriesRequest, type ConvexQueriesResult } from '../dist/runtime/composables/useConvexQueries.js'
+
+export { type ConvexFetchOptions } from '../dist/runtime/server/fetch.js'
+
+export { type ConvexAuthContext, type ConvexNuxtContext } from '../dist/runtime/utils/context.js'
+
+export { type ConnectionState } from '../dist/runtime/composables/useConvexConnectionState.js'
+
+export { type ConvexGate } from '../dist/runtime/composables/useConvexGate.js'
+
+export { default } from './module.mjs'
+
+export { type ModuleAuthOptions, type ModuleOptions, type ModulePublicRuntimeConfig } from './module.mjs'

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "use-convex",
+  "version": "0.0.2",
+  "description": "First-class Convex integration for Nuxt",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jrmybtlr/convex-nuxt.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./runtime/*": "./dist/runtime/*"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "nuxt-module-build build",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "dev": "nuxi dev playground --dotenv .env.local",
+    "dev:backend": "cd playground && convex dev",
+    "build:playground": "nuxi build playground",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "E2E_CONVEX=1 vitest run playground/e2e test/e2e",
+    "release": "semantic-release"
+  },
+  "peerDependencies": {
+    "convex": "^1.21.0",
+    "nuxt": "^4.0.0",
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.0.0",
+    "defu": "^6.1.4",
+    "h3": "^1.15.0"
+  },
+  "devDependencies": {
+    "@auth/core": "0.41.1",
+    "@convex-dev/auth": "^0.0.95",
+    "@nuxt/module-builder": "^1.0.0",
+    "@nuxt/schema": "^4.0.0",
+    "@nuxt/test-utils": "^3.23.0",
+    "@types/node": "^26.5.0",
+    "convex": "^1.45.0",
+    "convex-helpers": "^0.1.124",
+    "convex-test": "^0.0.56",
+    "happy-dom": "^20.14.0",
+    "nitropack": "^2.13.0",
+    "nuxt": "^4.5.2",
+    "semantic-release": "^25.0.9",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0",
+    "vue": "^3.5.0",
+    "vue-tsc": "^3.0.0"
+  },
+  "packageManager": "pnpm@10.0.0"
+}