better-convex-nuxt 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Matthias Amon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# Better Convex Nuxt
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Full-featured [Convex](https://convex.dev) integration for [Nuxt](https://nuxt.com) with SSR, real-time subscriptions, authentication, and permissions.
+
+- [Documentation](https://better-convex-nuxt.vercel.app)
+- [Online Playground](https://stackblitz.com/github/lupinum-dev/better-convex-nuxt?file=playground%2Fapp.vue)
+
+## Features
+
+- **Real-time Queries** - Fetch data with SSR, then upgrade to WebSocket subscriptions
+- **Optimistic Updates** - Instant UI feedback with automatic rollback on failure
+- **Authentication** - Better Auth integration with email/password, OAuth, and magic links
+- **Permissions** - Role-based access control with ownership rules
+- **SSR Support** - Server-side rendering with hydration
+- **Type Safety** - Full TypeScript inference from your Convex schema
+
+## Quick Setup
+
+Install the module:
+
+```bash
+npx nuxi module add better-convex-nuxt
+```
+
+Add your Convex URL to `.env`:
+
+```bash
+CONVEX_URL=https://your-project.convex.cloud
+```
+
+That's it! Start using Convex in your Nuxt app.
+
+## Usage
+
+### Queries
+
+```vue
+<script setup lang="ts">
+import { api } from '~/convex/_generated/api'
+
+// Real-time subscription with SSR support
+const { data: tasks, status } = await useConvexQuery(
+  api.tasks.list,
+  { status: 'active' }
+)
+</script>
+
+<template>
+  <ul v-if="status === 'success'">
+    <li v-for="task in tasks" :key="task._id">
+      {{ task.text }}
+    </li>
+  </ul>
+</template>
+```
+
+### Mutations
+
+```vue
+<script setup lang="ts">
+import { api } from '~/convex/_generated/api'
+
+const { mutate, pending } = useConvexMutation(api.tasks.create, {
+  optimisticUpdate: (localStore, args) => {
+    updateQuery({
+      query: api.tasks.list,
+      args: {},
+      localQueryStore: localStore,
+      updater: (current) => current
+        ? [{ _id: 'temp', text: args.text, completed: false }, ...current]
+        : []
+    })
+  }
+})
+
+await mutate({ text: 'Ship my app' })
+</script>
+```
+
+### Authentication
+
+```vue
+<script setup lang="ts">
+const { isAuthenticated, user } = useConvexAuth()
+const authClient = useAuthClient()
+
+async function handleLogin() {
+  await authClient.signIn.social({ provider: 'github' })
+}
+</script>
+
+<template>
+  <div v-if="isAuthenticated">
+    Welcome, {{ user?.name }}!
+  </div>
+  <button v-else @click="handleLogin">
+    Sign in with GitHub
+  </button>
+</template>
+```
+
+## Composables
+
+| Composable                 | Description                                          |
+| -------------------------- | ---------------------------------------------------- |
+| `useConvexQuery`           | Execute queries with SSR and real-time subscriptions |
+| `useLazyConvexQuery`       | Non-blocking queries that load in background         |
+| `useConvexMutation`        | Execute mutations with optimistic updates            |
+| `useConvexAction`          | Execute Convex actions                               |
+| `useConvexPaginatedQuery`  | Paginated queries with `loadMore()`                  |
+| `useConvexAuth`            | Authentication state (user, token, isAuthenticated)  |
+| `useConvexConnectionState` | WebSocket connection status                          |
+| `useConvexCached`          | Read cached query data                               |
+| `useConvex`                | Access raw ConvexClient instance                     |
+
+## Components
+
+| Component                 | Description                                 |
+| ------------------------- | ------------------------------------------- |
+| `<ConvexAuthenticated>`   | Renders content only when authenticated     |
+| `<ConvexUnauthenticated>` | Renders content only when not authenticated |
+| `<ConvexAuthLoading>`     | Renders content during auth state loading   |
+
+## Documentation
+
+Visit [better-convex-nuxt.vercel.app](https://better-convex-nuxt.vercel.app) for full documentation including:
+
+- [Installation & Setup](https://better-convex-nuxt.vercel.app/getting-started/installation)
+- [SSR Patterns](https://better-convex-nuxt.vercel.app/patterns/ssr-patterns)
+- [Optimistic Updates](https://better-convex-nuxt.vercel.app/patterns/optimistic-updates)
+- [Permissions](https://better-convex-nuxt.vercel.app/patterns/permissions)
+- [Server Utilities](https://better-convex-nuxt.vercel.app/server/server-utilities)
+
+## Contributing
+
+```bash
+# Install dependencies
+pnpm install
+
+# Generate type stubs
+pnpm dev:prepare
+
+# Develop with the playground
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Lint
+pnpm lint
+```
+
+## License
+
+[MIT](./LICENSE)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/better-convex-nuxt/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/better-convex-nuxt
+[npm-downloads-src]: https://img.shields.io/npm/dm/better-convex-nuxt.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/better-convex-nuxt
+[license-src]: https://img.shields.io/npm/l/better-convex-nuxt.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/better-convex-nuxt
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,24 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface BetterAuthOptions {
+    /** @deprecated Use siteUrl instead */
+    url?: string;
+}
+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. */
+    siteUrl?: string;
+    /** @deprecated Use siteUrl instead */
+    auth?: BetterAuthOptions;
+    /**
+     * Enable permission composables (createPermissions factory).
+     * When true, auto-imports createPermissions for building usePermissions.
+     * @default false
+     */
+    permissions?: boolean;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { BetterAuthOptions, ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "better-convex-nuxt",
+  "configKey": "convex",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "0.1.5",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,148 @@
+import { defineNuxtModule, createResolver, addPlugin, addServerHandler, addTemplate, addImports, addServerImports, addComponentsDir } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "better-convex-nuxt",
+    configKey: "convex",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    url: process.env.CONVEX_URL,
+    siteUrl: process.env.CONVEX_SITE_URL,
+    permissions: false
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const derivedSiteUrl = options.siteUrl || options.auth?.url || (options.url?.replace(".convex.cloud", ".convex.site") ?? "");
+    const convexConfig = defu(
+      nuxt.options.runtimeConfig.public.convex,
+      {
+        url: options.url || "",
+        siteUrl: derivedSiteUrl,
+        // Keep auth.url for backwards compatibility
+        auth: {
+          url: options.auth?.url || derivedSiteUrl
+        }
+      }
+    );
+    nuxt.options.runtimeConfig.public.convex = convexConfig;
+    addPlugin({
+      src: resolver.resolve("./runtime/plugin.server"),
+      mode: "server"
+    });
+    addPlugin(resolver.resolve("./runtime/plugin.client"));
+    addServerHandler({
+      route: "/api/auth/**",
+      handler: resolver.resolve("./runtime/server/api/auth/[...]")
+    });
+    addTemplate({
+      filename: "types/better-convex-nuxt.d.ts",
+      getContents: () => `
+import type { ConvexClient } from 'convex/browser'
+import type { createAuthClient } from 'better-auth/vue'
+
+type AuthClient = ReturnType<typeof createAuthClient>
+
+declare module '#app' {
+  interface NuxtApp {
+    $convex: ConvexClient
+    $auth?: AuthClient
+  }
+}
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $convex: ConvexClient
+    $auth?: AuthClient
+  }
+}
+
+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: "useConvexCached", from: resolver.resolve("./runtime/composables/useConvexCached") },
+      { name: "useConvexData", from: resolver.resolve("./runtime/composables/useConvexData") },
+      {
+        name: "useLazyConvexQuery",
+        from: resolver.resolve("./runtime/composables/useLazyConvexQuery")
+      },
+      {
+        name: "useConvexPaginatedQuery",
+        from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
+      },
+      {
+        name: "useConvexConnectionState",
+        from: resolver.resolve("./runtime/composables/useConvexConnectionState")
+      },
+      // Optimistic update helpers for regular queries
+      { name: "updateQuery", from: resolver.resolve("./runtime/composables/useConvexMutation") },
+      { name: "setQueryData", from: resolver.resolve("./runtime/composables/useConvexMutation") },
+      {
+        name: "updateAllQueries",
+        from: resolver.resolve("./runtime/composables/useConvexMutation")
+      },
+      {
+        name: "deleteFromQuery",
+        from: resolver.resolve("./runtime/composables/useConvexMutation")
+      },
+      // Optimistic update helpers for paginated queries (already available from useConvexPaginatedQuery)
+      {
+        name: "insertAtTop",
+        from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
+      },
+      {
+        name: "insertAtPosition",
+        from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
+      },
+      {
+        name: "insertAtBottomIfLoaded",
+        from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
+      },
+      {
+        name: "optimisticallyUpdateValueInPaginatedQuery",
+        from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
+      },
+      {
+        name: "deleteFromPaginatedQuery",
+        from: resolver.resolve("./runtime/composables/useConvexPaginatedQuery")
+      }
+    ]);
+    if (options.permissions) {
+      addImports([
+        {
+          name: "createPermissions",
+          from: resolver.resolve("./runtime/composables/usePermissions")
+        }
+      ]);
+    }
+    addServerImports([
+      { name: "fetchQuery", from: resolver.resolve("./runtime/server/utils/convex") },
+      { name: "fetchMutation", from: resolver.resolve("./runtime/server/utils/convex") },
+      { name: "fetchAction", from: resolver.resolve("./runtime/server/utils/convex") }
+    ]);
+    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")
+      });
+    });
+  }
+});
+
+export { module$1 as default };

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

@@ -0,0 +1,13 @@
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/ConvexAuthLoading.vue

@@ -0,0 +1,8 @@
+<script setup>
+import { useConvexAuth } from "../composables/useConvexAuth";
+const { isPending } = useConvexAuth();
+</script>
+
+<template>
+  <slot v-if="isPending" />
+</template>

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

@@ -0,0 +1,13 @@
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,13 @@
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/ConvexAuthenticated.vue

@@ -0,0 +1,8 @@
+<script setup>
+import { useConvexAuth } from "../composables/useConvexAuth";
+const { isAuthenticated, isPending } = useConvexAuth();
+</script>
+
+<template>
+  <slot v-if="isAuthenticated && !isPending" />
+</template>

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

@@ -0,0 +1,13 @@
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,13 @@
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/ConvexUnauthenticated.vue

@@ -0,0 +1,8 @@
+<script setup>
+import { useConvexAuth } from "../composables/useConvexAuth";
+const { isAuthenticated, isPending } = useConvexAuth();
+</script>
+
+<template>
+  <slot v-if="!isAuthenticated && !isPending" />
+</template>

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

@@ -0,0 +1,13 @@
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,11 @@
+export { useConvexAuth } from './useConvexAuth.js';
+export { useConvex } from './useConvex.js';
+export { useConvexConnectionState, type ConnectionState, type UseConvexConnectionStateOptions, } from './useConvexConnectionState.js';
+export { useConvexMutation, type MutationStatus, type UseConvexMutationReturn, type UseConvexMutationOptions, updateQuery, setQueryData, updateAllQueries, deleteFromQuery, type UpdateQueryOptions, type SetQueryDataOptions, type UpdateAllQueriesOptions, type DeleteFromQueryOptions, } from './useConvexMutation.js';
+export type { OptimisticLocalStore } from 'convex/browser';
+export { useConvexAction, type ActionStatus, type UseConvexActionReturn, type UseConvexActionOptions, } from './useConvexAction.js';
+export { useAuthClient } from './useAuthClient.js';
+export { useConvexQuery, type QueryStatus, type UseConvexQueryReturn, type UseConvexQueryData, type UseConvexQueryOptions, } from './useConvexQuery.js';
+export { useConvexCached } from './useConvexCached.js';
+export { useConvexPaginatedQuery, type PaginationStatus, type UseConvexPaginatedQueryOptions, type UseConvexPaginatedQueryReturn, type PaginatedQueryReference, type PaginatedQueryArgs, type PaginatedQueryItem, insertAtTop, insertAtPosition, insertAtBottomIfLoaded, optimisticallyUpdateValueInPaginatedQuery, deleteFromPaginatedQuery, type InsertAtTopOptions, type InsertAtPositionOptions, type InsertAtBottomIfLoadedOptions, type UpdateInPaginatedQueryOptions, type DeleteFromPaginatedQueryOptions, } from './useConvexPaginatedQuery.js';
+export { createPermissions, type PermissionContext, type Resource, type CheckPermissionFn, type CreatePermissionsOptions, type UsePermissionsReturn, type UsePermissionGuardOptions, } from './usePermissions.js';

package/dist/runtime/composables/index.js

@@ -0,0 +1,31 @@
+export { useConvexAuth } from "./useConvexAuth.js";
+export { useConvex } from "./useConvex.js";
+export {
+  useConvexConnectionState
+} from "./useConvexConnectionState.js";
+export {
+  useConvexMutation,
+  updateQuery,
+  setQueryData,
+  updateAllQueries,
+  deleteFromQuery
+} from "./useConvexMutation.js";
+export {
+  useConvexAction
+} from "./useConvexAction.js";
+export { useAuthClient } from "./useAuthClient.js";
+export {
+  useConvexQuery
+} from "./useConvexQuery.js";
+export { useConvexCached } from "./useConvexCached.js";
+export {
+  useConvexPaginatedQuery,
+  insertAtTop,
+  insertAtPosition,
+  insertAtBottomIfLoaded,
+  optimisticallyUpdateValueInPaginatedQuery,
+  deleteFromPaginatedQuery
+} from "./useConvexPaginatedQuery.js";
+export {
+  createPermissions
+} from "./usePermissions.js";

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

@@ -0,0 +1,36 @@
+import type { createAuthClient } from 'better-auth/vue';
+type AuthClient = ReturnType<typeof createAuthClient>;
+/**
+ * Composable for accessing the Better Auth client instance.
+ *
+ * Returns the auth client that is:
+ * - Configured with the auth server URL
+ * - Integrated with Convex for token synchronization
+ * - Ready for sign-in, sign-out, and session management
+ *
+ * SSR-safe: Can be called during component setup. Returns null during SSR,
+ * but this is safe because auth operations (sign in, sign out) should only
+ * be triggered by user interactions which only happen on the client.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * // Safe to call at setup time - returns null on SSR, client on browser
+ * const authClient = useAuthClient()
+ *
+ * // Auth operations are event handlers - only run on client
+ * async function login(email: string, password: string) {
+ *   const { data, error } = await authClient!.signIn.email({
+ *     email,
+ *     password
+ *   })
+ * }
+ *
+ * async function logout() {
+ *   await authClient?.signOut()
+ * }
+ * </script>
+ * ```
+ */
+export declare function useAuthClient(): AuthClient | null;
+export {};

package/dist/runtime/composables/useAuthClient.js

@@ -0,0 +1,6 @@
+import { useNuxtApp } from "#imports";
+export function useAuthClient() {
+  const nuxtApp = useNuxtApp();
+  const auth = nuxtApp.$auth;
+  return auth ?? null;
+}

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

@@ -0,0 +1,28 @@
+import type { ConvexClient } from 'convex/browser';
+/**
+ * Composable for accessing the Convex client instance.
+ *
+ * Returns the singleton ConvexClient that is:
+ * - Configured with auth token from SSR
+ * - Ready to use for queries, mutations, and actions
+ *
+ * Note: Returns null during SSR as ConvexClient only works on the client.
+ * Use this composable in client-only code or check for null.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { api } from '~/convex/_generated/api'
+ *
+ * const convex = useConvex()
+ *
+ * // For client-only usage
+ * onMounted(async () => {
+ *   if (convex) {
+ *     const result = await convex.query(api.tasks.list)
+ *   }
+ * })
+ * </script>
+ * ```
+ */
+export declare function useConvex(): ConvexClient | null;

package/dist/runtime/composables/useConvex.js

@@ -0,0 +1,6 @@
+import { useNuxtApp } from "#imports";
+export function useConvex() {
+  const nuxtApp = useNuxtApp();
+  const convex = nuxtApp.$convex;
+  return convex ?? null;
+}