nuxt-convex-module 0.0.0

package/dist/module.json

@@ -0,0 +1,13 @@
+{
+  "name": "nuxt-convex-module",
+  "configKey": "convex",
+  "docs": "https://github.com/qruto/nuxt-convex-module#readme",
+  "compatibility": {
+    "nuxt": ">=4.1.0"
+  },
+  "version": "0.0.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/runtime/auth0/vue/index.d.ts

@@ -0,0 +1,58 @@
+import { type PropType } from 'vue';
+import { type ConvexAuthState, type IConvexVueClient } from '../../vue/auth/index.js';
+/**
+ * Options for {@link provideConvexAuthFromAuth0} / `<ConvexProviderWithAuth0>`.
+ */
+export interface ConvexProviderWithAuth0Options {
+    /** Convex client to authenticate. Defaults to the provided {@link useConvex} client. */
+    client?: IConvexVueClient;
+}
+/**
+ * The composable form of {@link ConvexProviderWithAuth0} — provides a
+ * {@link ConvexVueClient} authenticated with Auth0.
+ *
+ * It must be called in an app wrapped by a configured Auth0 plugin from
+ * `@auth0/auth0-vue`.
+ *
+ * See [Convex Auth0](https://docs.convex.dev/auth/auth0) on how to set up
+ * Convex with Auth0.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { provideConvexAuthFromAuth0 } from 'nuxt-convex-module/auth0/client'
+ * provideConvexAuthFromAuth0()
+ * </script>
+ * ```
+ *
+ * @public
+ */
+export declare function provideConvexAuthFromAuth0(options?: ConvexProviderWithAuth0Options): ConvexAuthState;
+/**
+ * A wrapper Vue component which provides a {@link ConvexVueClient}
+ * authenticated with Auth0 — the component form of
+ * {@link provideConvexAuthFromAuth0}. Renders its default slot once Convex
+ * auth is wired.
+ *
+ * It must be wrapped by a configured Auth0 plugin from `@auth0/auth0-vue`.
+ *
+ * See [Convex Auth0](https://docs.convex.dev/auth/auth0) on how to set up
+ * Convex with Auth0.
+ *
+ * @public
+ */
+export declare const ConvexProviderWithAuth0: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    client: {
+        type: PropType<IConvexVueClient>;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    client: {
+        type: PropType<IConvexVueClient>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    client: IConvexVueClient;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/runtime/auth0/vue/index.js

@@ -0,0 +1,33 @@
+import { useAuth0 } from "@auth0/auth0-vue";
+import { defineComponent } from "vue";
+import { provideConvexAuth } from "../../vue/auth/index.js";
+import { useConvexOrThrow } from "../../vue/client.js";
+export function provideConvexAuthFromAuth0(options = {}) {
+  const client = options.client ?? useConvexOrThrow("provideConvexAuthFromAuth0");
+  return provideConvexAuth({ client, useAuth: useAuthFromAuth0 });
+}
+export const ConvexProviderWithAuth0 = defineComponent({
+  name: "ConvexProviderWithAuth0",
+  props: {
+    client: { type: Object, default: void 0 }
+  },
+  setup(props, { slots }) {
+    provideConvexAuthFromAuth0({ client: props.client });
+    return () => slots.default?.();
+  }
+});
+function useAuthFromAuth0() {
+  const { isLoading, isAuthenticated, getAccessTokenSilently } = useAuth0();
+  const fetchAccessToken = async ({ forceRefreshToken }) => {
+    try {
+      const response = await getAccessTokenSilently({
+        detailedResponse: true,
+        cacheMode: forceRefreshToken ? "off" : "on"
+      });
+      return response.id_token;
+    } catch {
+      return null;
+    }
+  };
+  return { isLoading, isAuthenticated, fetchAccessToken };
+}

package/dist/runtime/better-auth/nuxt/middleware.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Auth route middleware — protects pages from unauthenticated access.
+ *
+ * Usage in page:
+ * ```vue
+ * <script setup>
+ * definePageMeta({ middleware: 'auth' })
+ * </script>
+ * ```
+ */
+/** Exported for unit tests — `import.meta.server` is compile-time. @internal */
+export declare function serverGuard(path: string): Promise<string | false | void | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric | import("vue-router").NavigationFailure>;
+declare const _default: import("nuxt/app").RouteMiddleware;
+export default _default;

package/dist/runtime/better-auth/nuxt/middleware.js

@@ -0,0 +1,39 @@
+import { defineNuxtRouteMiddleware, navigateTo, useNuxtApp, useRequestEvent } from "#app";
+import { watch } from "vue";
+import { useAuth } from "../vue/use-auth.js";
+import { convexAuth } from "./server.js";
+export async function serverGuard(path) {
+  const event = useRequestEvent();
+  if (!event) return;
+  const nuxtApp = useNuxtApp();
+  const authed = await convexAuth(event).isAuthenticated();
+  if (!authed && path !== "/login") {
+    return nuxtApp.runWithContext(() => navigateTo("/login"));
+  }
+}
+function waitForSession(isPending) {
+  return new Promise((resolve) => {
+    const stop = watch(
+      isPending,
+      (pending) => {
+        if (!pending) {
+          stop();
+          resolve();
+        }
+      },
+      { immediate: true }
+    );
+  });
+}
+export default defineNuxtRouteMiddleware(async (to) => {
+  if (import.meta.server) {
+    return serverGuard(to.path);
+  }
+  const { session } = useAuth();
+  if (session.value.isPending) {
+    await waitForSession(() => session.value.isPending);
+  }
+  if (!session.value.data && to.path !== "/login") {
+    return navigateTo("/login");
+  }
+});

package/dist/runtime/better-auth/nuxt/proxy.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Proxy all /api/auth/* requests to the Convex site URL.
+ * This keeps auth cookies on the same origin (no CORS issues).
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Response>>;
+export default _default;

package/dist/runtime/better-auth/nuxt/proxy.js

@@ -0,0 +1,11 @@
+import { defineEventHandler } from "h3";
+import { useRuntimeConfig } from "#imports";
+import { convexAuth } from "./server.js";
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig();
+  const siteUrl = config.convex.siteUrl;
+  if (!siteUrl) {
+    throw new Error("[nuxt-convex-module] NUXT_PUBLIC_CONVEX_SITE_URL is not configured. Auth proxy cannot forward requests.");
+  }
+  return convexAuth(event, { convexSiteUrl: siteUrl }).handler();
+});

package/dist/runtime/better-auth/nuxt/server.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Server-side Better Auth + Convex integration for Nuxt.
+ *
+ * Provides {@link convexAuth} for Nuxt server handlers.
+ *
+ * It accepts the H3
+ * {@link H3Event} that is available in every Nuxt server route, API handler
+ * and server middleware.
+ *
+ * @module better-auth/server
+ */
+import type { H3Event } from 'h3';
+import type { GetTokenOptions } from '@convex-dev/better-auth/utils';
+import type { FunctionReference, FunctionReturnType } from 'convex/server';
+import type { Preloaded } from '../../vue/hydration.js';
+type OptionalArgs<FuncRef extends FunctionReference<any, any>> = FuncRef['_args'] extends Record<string, never> ? [args?: Record<string, never>] : [args: FuncRef['_args']];
+/**
+ * Options for {@link convexAuth}.
+ *
+ * Extends {@link GetTokenOptions} from `@convex-dev/better-auth/utils` with
+ * an optional override for the Convex site URL.
+ *
+ * @public
+ */
+export type ConvexAuthOptions = GetTokenOptions & {
+    /**
+     * Accepted for drop-in compatibility with upstream `convexBetterAuthNextJs`
+     * option objects and ignored — upstream requires but never reads it either;
+     * the deployment URL comes from runtime config.
+     */
+    convexUrl?: string;
+    /**
+     * Override the Convex site URL. Defaults to `NUXT_PUBLIC_CONVEX_SITE_URL`.
+     */
+    convexSiteUrl?: string;
+};
+/**
+ * Per-request Better Auth + Convex helper returned by {@link convexAuth}.
+ *
+ * @public
+ */
+export interface ConvexAuthService {
+    /** Convex JWT for the current user, or `undefined` when not authenticated. */
+    getToken: () => Promise<string | undefined>;
+    /** Proxy a Better Auth route to the configured Convex site URL. */
+    handler: () => Promise<Response>;
+    /** `true` when the current request has a valid Convex auth token. */
+    isAuthenticated: () => Promise<boolean>;
+    /** Preload a Convex query with the current user's auth token. */
+    preloadAuthQuery: <Query extends FunctionReference<'query'>>(query: Query, ...args: OptionalArgs<Query>) => Promise<Preloaded<Query>>;
+    /** Execute a Convex query with the current user's auth token. */
+    fetchAuthQuery: <Query extends FunctionReference<'query'>>(query: Query, ...args: OptionalArgs<Query>) => Promise<FunctionReturnType<Query>>;
+    /** Execute a Convex mutation with the current user's auth token. */
+    fetchAuthMutation: <Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, ...args: OptionalArgs<Mutation>) => Promise<FunctionReturnType<Mutation>>;
+    /** Execute a Convex action with the current user's auth token. */
+    fetchAuthAction: <Action extends FunctionReference<'action'>>(action: Action, ...args: OptionalArgs<Action>) => Promise<FunctionReturnType<Action>>;
+}
+/**
+ * Create a per-request Better Auth + Convex helper for Nuxt server code.
+ *
+ * Adapts the Better Auth + Convex server helper pattern to H3 events.
+ *
+ * Call once at the top of a server route / event handler and destructure the
+ * helpers you need. The auth token is fetched at most once per request — the
+ * cache lives on `event.context`, so every `convexAuth(event)` instance for
+ * the same request (server plugin, middleware, your route) shares one Better
+ * Auth round-trip. Mirrors upstream's `React.cache`-wrapped `getToken`.
+ *
+ * @example
+ * ```ts
+ * // server/api/profile.get.ts
+ * export default defineEventHandler(async (event) => {
+ *   const { fetchAuthQuery, isAuthenticated } = convexAuth(event)
+ *   if (!await isAuthenticated()) {
+ *     throw createError({ statusCode: 401 })
+ *   }
+ *   return fetchAuthQuery(api.users.current)
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // pages/profile.vue — preloading data for SSR
+ * const { data } = await useAsyncData(async () => {
+ *   const event = useRequestEvent()!
+ *   return convexAuth(event).preloadAuthQuery(api.users.current)
+ * })
+ * ```
+ *
+ * @param event - The H3 event from a Nuxt server route or middleware.
+ * @param opts  - Optional {@link ConvexAuthOptions}.
+ *
+ * @public
+ */
+export declare function convexAuth(event: H3Event, opts?: ConvexAuthOptions): ConvexAuthService;
+/**
+ * Upstream-named alias of {@link convexAuth} — the mechanical rename target
+ * for `@convex-dev/better-auth/nextjs`'s `convexBetterAuthNextJs` (framework
+ * suffix `NextJs` → `Nuxt`). Unlike upstream's module-level factory (which
+ * reads request state ambiently via `next/headers`), Nitro has no ambient
+ * per-request context, so the H3 `event` is passed explicitly.
+ *
+ * @public
+ */
+export declare const convexBetterAuthNuxt: typeof convexAuth;
+export {};

package/dist/runtime/better-auth/nuxt/server.js

@@ -0,0 +1,123 @@
+import { getRequestHeaders, toWebRequest } from "h3";
+import { getToken } from "@convex-dev/better-auth/utils";
+import { getConvexRuntimeConfig } from "../../nuxt/config.js";
+import { fetchAction, fetchMutation, fetchQuery, preloadQuery } from "../../nuxt/index.js";
+const parseConvexSiteUrl = (url) => {
+  if (!url) {
+    throw new Error(
+      "NUXT_PUBLIC_CONVEX_SITE_URL is not set.\nThis is automatically set in the Convex deployment, but must be set in the Nuxt environment.\nFor local development, this can be set in the .env file, or via the `convex.siteUrl` option in nuxt.config."
+    );
+  }
+  if (url.endsWith(".convex.cloud")) {
+    throw new Error(
+      `NUXT_PUBLIC_CONVEX_SITE_URL should be set to your Convex Site URL, which ends in .convex.site.
+Currently set to ${url}.`
+    );
+  }
+  return url;
+};
+const handler = async (request, siteUrl) => {
+  const requestUrl = new URL(request.url);
+  const nextUrl = `${siteUrl}${requestUrl.pathname}${requestUrl.search}`;
+  const headers = new Headers(request.headers);
+  headers.delete("transfer-encoding");
+  headers.delete("content-length");
+  headers.delete("connection");
+  headers.set("accept-encoding", "application/json");
+  headers.set("host", new URL(siteUrl).host);
+  headers.set("x-forwarded-host", requestUrl.host);
+  headers.set("x-forwarded-proto", requestUrl.protocol.replace(/:$/, ""));
+  headers.set("x-better-auth-forwarded-host", requestUrl.host);
+  headers.set("x-better-auth-forwarded-proto", requestUrl.protocol.replace(/:$/, ""));
+  const init = {
+    headers,
+    method: request.method,
+    redirect: "manual"
+  };
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    const body = await request.arrayBuffer();
+    if (body.byteLength > 0) {
+      init.body = body;
+    }
+  }
+  const response = await fetch(nextUrl, init);
+  const responseHeaders = new Headers(response.headers);
+  responseHeaders.delete("content-encoding");
+  responseHeaders.delete("content-length");
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: responseHeaders
+  });
+};
+const nuxtHandler = (event, siteUrl) => () => handler(toWebRequest(event), siteUrl);
+const getArgsAndOptions = (args, token) => {
+  return [args[0], { token }];
+};
+export function convexAuth(event, opts) {
+  const siteUrl = parseConvexSiteUrl(
+    opts?.convexSiteUrl ?? getConvexRuntimeConfig().siteUrl ?? process.env.NUXT_PUBLIC_CONVEX_SITE_URL
+  );
+  const cacheKey = `__nuxtConvexToken:${siteUrl}|${opts?.basePath ?? ""}`;
+  const tokenCache = event.context;
+  const cachedGetToken = ({ forceRefresh } = {}) => {
+    const cached = tokenCache[cacheKey];
+    if (cached && !forceRefresh) return cached;
+    const headers = getRequestHeaders(event);
+    const mutableHeaders = new Headers(headers);
+    mutableHeaders.delete("content-length");
+    mutableHeaders.delete("transfer-encoding");
+    mutableHeaders.set("accept-encoding", "identity");
+    const promise = getToken(siteUrl, mutableHeaders, { ...opts, forceRefresh });
+    tokenCache[cacheKey] = promise;
+    return promise;
+  };
+  const callWithToken = async (fn) => {
+    const token = await cachedGetToken();
+    try {
+      return await fn(token?.token);
+    } catch (error) {
+      if (!opts?.jwtCache?.enabled || token.isFresh || !opts.jwtCache.isAuthError(error)) {
+        throw error;
+      }
+      const newToken = await cachedGetToken({ forceRefresh: true });
+      return await fn(newToken.token);
+    }
+  };
+  return {
+    getToken: async () => {
+      const token = await cachedGetToken();
+      return token.token;
+    },
+    handler: nuxtHandler(event, siteUrl),
+    isAuthenticated: async () => {
+      const token = await cachedGetToken();
+      return !!token.token;
+    },
+    preloadAuthQuery: async (query, ...args) => {
+      return callWithToken((token) => {
+        const argsAndOptions = getArgsAndOptions(args, token);
+        return preloadQuery(query, ...argsAndOptions);
+      });
+    },
+    fetchAuthQuery: async (query, ...args) => {
+      return callWithToken((token) => {
+        const argsAndOptions = getArgsAndOptions(args, token);
+        return fetchQuery(query, ...argsAndOptions);
+      });
+    },
+    fetchAuthMutation: async (mutation, ...args) => {
+      return callWithToken((token) => {
+        const argsAndOptions = getArgsAndOptions(args, token);
+        return fetchMutation(mutation, ...argsAndOptions);
+      });
+    },
+    fetchAuthAction: async (action, ...args) => {
+      return callWithToken((token) => {
+        const argsAndOptions = getArgsAndOptions(args, token);
+        return fetchAction(action, ...argsAndOptions);
+      });
+    }
+  };
+}
+export const convexBetterAuthNuxt = convexAuth;

package/dist/runtime/better-auth/vue/auth-boundary.d.ts

@@ -0,0 +1,131 @@
+import { type PropType, type VNode } from 'vue';
+import type { FunctionReference } from 'convex/server';
+import type { EmptyObject } from 'convex-helpers';
+import type { AuthClient } from '#convex/auth-client';
+/**
+ * _Experimental_
+ *
+ * A wrapper Vue component which provides error handling for auth related errors.
+ * This is typically used to redirect the user to the login page when they are
+ * unauthenticated, and does so reactively based on the getAuthUserFn query.
+ *
+ * @example
+ * ```vue
+ * <!--
+ *   convex/auth.ts:
+ *   export const { getAuthUser } = authComponent.clientApi();
+ * -->
+ * <script setup lang="ts">
+ * import { AuthBoundary, authClient } from '#imports'
+ * import { api } from '#convex/api'
+ * import { isAuthError } from '~/utils/auth'
+ * </script>
+ *
+ * <template>
+ *   <AuthBoundary
+ *     :on-unauth="() => navigateTo('/sign-in')"
+ *     :auth-client="authClient"
+ *     :get-auth-user-fn="api.auth.getAuthUser"
+ *     :is-auth-error="isAuthError"
+ *   >
+ *     <slot />
+ *   </AuthBoundary>
+ * </template>
+ * ```
+ * @param props.onUnauth - Function to call when the user is
+ * unauthenticated. Typically a redirect to the login page.
+ * @param props.authClient - Better Auth authClient to use.
+ * @param props.renderFallback - Fallback component to render when the user is
+ * unauthenticated. Defaults to null. Generally not rendered as error handling
+ * is typically a redirect.
+ * @param props.getAuthUserFn - Reference to a Convex query that returns user.
+ * The component provides a query for this via `export const { getAuthUser } = authComponent.clientApi()`.
+ * @param props.isAuthError - Function to check if the error is auth related.
+ *
+ * @public
+ */
+export declare const AuthBoundary: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /**
+     * The function to call when the user is unauthenticated. Typically a redirect
+     * to the login page.
+     */
+    onUnauth: {
+        type: PropType<() => void | Promise<void>>;
+        required: true;
+    };
+    /**
+     * The Better Auth authClient to use.
+     */
+    authClient: {
+        type: PropType<AuthClient>;
+        required: true;
+    };
+    /**
+     * The fallback to render when the user is unauthenticated. Defaults to null.
+     * Generally not rendered as error handling is typically a redirect.
+     */
+    renderFallback: {
+        type: PropType<() => VNode | null>;
+        default: () => null;
+    };
+    /**
+     * The function to call to get the auth user.
+     */
+    getAuthUserFn: {
+        type: PropType<FunctionReference<"query", "public", EmptyObject>>;
+        required: true;
+    };
+    /**
+     * The function to call to check if the error is auth related.
+     */
+    isAuthError: {
+        type: PropType<(error: unknown) => boolean>;
+        required: true;
+    };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | (VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[] | undefined)[] | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /**
+     * The function to call when the user is unauthenticated. Typically a redirect
+     * to the login page.
+     */
+    onUnauth: {
+        type: PropType<() => void | Promise<void>>;
+        required: true;
+    };
+    /**
+     * The Better Auth authClient to use.
+     */
+    authClient: {
+        type: PropType<AuthClient>;
+        required: true;
+    };
+    /**
+     * The fallback to render when the user is unauthenticated. Defaults to null.
+     * Generally not rendered as error handling is typically a redirect.
+     */
+    renderFallback: {
+        type: PropType<() => VNode | null>;
+        default: () => null;
+    };
+    /**
+     * The function to call to get the auth user.
+     */
+    getAuthUserFn: {
+        type: PropType<FunctionReference<"query", "public", EmptyObject>>;
+        required: true;
+    };
+    /**
+     * The function to call to check if the error is auth related.
+     */
+    isAuthError: {
+        type: PropType<(error: unknown) => boolean>;
+        required: true;
+    };
+}>> & Readonly<{}>, {
+    renderFallback: () => VNode | null;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/runtime/better-auth/vue/auth-boundary.js

@@ -0,0 +1,78 @@
+import { defineComponent, h, onErrorCaptured, ref, watch } from "vue";
+import { useConvexAuth } from "../../vue/auth/index.js";
+import { Authenticated } from "../../vue/auth/helpers.js";
+import { useQuery } from "../../vue/composables/use-query.js";
+const UserSubscription = defineComponent({
+  name: "UserSubscription",
+  props: {
+    getAuthUserFn: { type: Object, required: true }
+  },
+  setup(props) {
+    const user = useQuery(props.getAuthUserFn);
+    return () => {
+      void user.value;
+      return null;
+    };
+  }
+});
+export const AuthBoundary = defineComponent({
+  name: "AuthBoundary",
+  props: {
+    /**
+     * The function to call when the user is unauthenticated. Typically a redirect
+     * to the login page.
+     */
+    onUnauth: { type: Function, required: true },
+    /**
+     * The Better Auth authClient to use.
+     */
+    authClient: { type: Object, required: true },
+    /**
+     * The fallback to render when the user is unauthenticated. Defaults to null.
+     * Generally not rendered as error handling is typically a redirect.
+     */
+    renderFallback: { type: Function, default: () => null },
+    /**
+     * The function to call to get the auth user.
+     */
+    getAuthUserFn: {
+      type: Object,
+      required: true
+    },
+    /**
+     * The function to call to check if the error is auth related.
+     */
+    isAuthError: { type: Function, required: true }
+  },
+  setup(props, { slots }) {
+    const { isAuthenticated, isLoading } = useConvexAuth();
+    const handleUnauth = async () => {
+      await props.authClient.getSession();
+      await props.onUnauth();
+    };
+    watch([isLoading, isAuthenticated], () => {
+      void (async () => {
+        if (!isLoading.value && !isAuthenticated.value) {
+          await handleUnauth();
+        }
+      })();
+    }, { immediate: true });
+    const error = ref();
+    onErrorCaptured((err) => {
+      error.value = err;
+      if (props.isAuthError(err)) {
+        void handleUnauth();
+        return false;
+      }
+    });
+    return () => {
+      if (error.value && props.isAuthError(error.value)) {
+        return props.renderFallback?.();
+      }
+      return [
+        h(Authenticated, () => h(UserSubscription, { getAuthUserFn: props.getAuthUserFn })),
+        slots.default?.()
+      ];
+    };
+  }
+});