nuxt-convex-module 0.11.0 → 0.12.1

package/dist/module.d.mts

@@ -1,6 +1,6 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
-/** The `convex.autoImports` option: every name, only the `Convex`-marked ones, or none. */
+/** The `convex.autoImports` option: every name, every name prefixed with `Convex`, or none. */
 type AutoImports = boolean | 'prefixed';
 
 /**
@@ -22,6 +22,12 @@ interface BetterAuthModuleOptions {
      * @example './app/convex-auth-client'
      */
     authClient?: string;
+    /**
+     * Route the same-origin proxy to Better Auth is mounted at. Defaults to
+     * `/api/auth`, Better Auth's own default `basePath`; moving it needs an
+     * `authClient` created with the same `basePath`.
+     */
+    authRoute?: string;
     /**
      * Restrict cross-domain one-time-token (`?ott=`) sign-in completion to one
      * app route, e.g. `'/auth/callback'`. Only meaningful when your auth client
@@ -95,14 +101,13 @@ interface ModuleOptions {
      * Which names are auto-imported. `true` registers every composable, component
      * and Nitro helper under its upstream name (`useQuery`, `<Authenticated>`,
      * `fetchQuery`) and, where one exists, its prefixed twin (`useConvexQuery`).
-     * `'prefixed'` registers only names carrying `Convex` (`useConvexQuery`,
-     * `<ConvexImage>`, `provideConvexAuth`, `convexAuth`, …) so a bare name never
-     * collides with another module's; the rest stay importable from the subpath
-     * exports. `false` auto-imports nothing.
+     * `'prefixed'` registers every one of them with `Convex` in its name, as the
+     * Nuxt module author guide asks (`useConvexQuery`, `<ConvexAuthenticated>`,
+     * `fetchConvexQuery`, `useConvexBetterAuth`, …), so a bare name never
+     * collides with another module's; the upstream names stay importable from
+     * the subpath exports. `false` auto-imports nothing.
      */
     autoImports?: AutoImports;
-    /** Route the Better Auth same-origin proxy is mounted at. Defaults to `/api/auth`. */
-    authRoute?: string;
     /**
      * Convex panel in Nuxt DevTools (dev only): connection state, live query
      * subscriptions, auth state, and client logs. Enabled by default whenever
@@ -122,11 +127,6 @@ interface ModuleOptions {
     devScript?: boolean;
 }
 declare module '@nuxt/schema' {
-    interface RuntimeConfig {
-        convex: {
-            siteUrl: string;
-        };
-    }
     interface PublicRuntimeConfig {
         convex: {
             url: string;

package/dist/module.json

@@ -3,9 +3,9 @@
   "configKey": "convex",
   "docs": "https://nuxt-convex-module.dev",
   "compatibility": {
-    "nuxt": ">=4.1.0"
+    "nuxt": ">=4.6.0"
   },
-  "version": "0.11.0",
+  "version": "0.12.1",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { useLogger, updateTemplates, defineNuxtModule, createResolver, addPlugin, hasNuxtModule, addServerPlugin, addPluginTemplate, addTypeTemplate, addImports, addServerImports, addComponent, addServerHandler, extendRouteRules, addRouteMiddleware } from '@nuxt/kit';
+import { useLogger, updateTemplates, defineNuxtModule, createResolver, addPlugin, hasNuxtModule, addNitroPlugin, addTypeTemplate, addImports, addServerImports, addComponent, addServerHandler, extendRouteRules, addRouteMiddleware } from '@nuxt/kit';
 import { dirname, join, isAbsolute, basename } from 'node:path';
 import { detectAgent } from 'std-env';
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
@@ -52,11 +52,11 @@ function validateModuleOptions(input) {
       `\`convex.siteUrl\` ("${input.siteUrl}") does not look like a valid http(s) URL.`
     );
   }
-  const authRoute = normalizeRoutePath(input.authRoute, "convex.authRoute", warnings);
+  const authRoute = normalizeRoutePath(input.authRoute, "convex.betterAuth.authRoute", warnings);
   const loginPath = normalizeRoutePath(input.loginPath ?? "/login", "convex.betterAuth.loginPath", warnings);
   if (authRoute !== "/api/auth" && !input.authClient) {
     errors.push(
-      `\`convex.authRoute\` is "${authRoute}" but the bundled Better Auth client still calls /api/auth, so every auth request would 404. Keep the default route, or set \`convex.betterAuth.authClient\` to a client created with \`basePath: "${authRoute}"\`.`
+      `\`convex.betterAuth.authRoute\` is "${authRoute}" but the bundled Better Auth client still calls /api/auth, so every auth request would 404. Keep the default route, or set \`convex.betterAuth.authClient\` to a client created with \`basePath: "${authRoute}"\`.`
     );
   }
   if (input.authClient && !authClientModuleExists(input.authClient, input.rootDir)) {
@@ -95,7 +95,7 @@ function integrationWarnings(flags, isInstalled) {
   }
   if (flags.polar && !isInstalled("@polar-sh/checkout")) {
     warnings.push(
-      "`@convex-dev/polar` is installed but its peer `@polar-sh/checkout` is not \u2014 `<CheckoutLink>` imports it and the build fails the moment the component is used. Run `npm install @polar-sh/checkout`."
+      "`@convex-dev/polar` is installed but its peer `@polar-sh/checkout` is not \u2014 `<CheckoutLink>` imports it and the build fails the moment the component is used. Run `npm install @polar-sh/checkout@~0.4.0`."
     );
   }
   return warnings;
@@ -129,6 +129,19 @@ function resolveDeploymentUrls(options, env) {
     siteUrl: stripTrailingSlashes(options.siteUrl || env.NUXT_PUBLIC_CONVEX_SITE_URL || env.CONVEX_SITE_URL || "")
   };
 }
+function deploymentWarnings(options, env) {
+  const warnings = [];
+  const cliUrl = stripTrailingSlashes(env.CONVEX_URL || "");
+  const source = options.url ? "`convex.url`" : env.NUXT_PUBLIC_CONVEX_URL ? "NUXT_PUBLIC_CONVEX_URL" : "";
+  const { url } = resolveDeploymentUrls(options, env);
+  if (cliUrl && source && url !== cliUrl) {
+    const stale = [["`convex.url`", options.url], ["NUXT_PUBLIC_CONVEX_URL", env.NUXT_PUBLIC_CONVEX_URL]].filter(([, value]) => value && stripTrailingSlashes(value) !== cliUrl).map(([name]) => name);
+    warnings.push(
+      `The app calls ${url} (from ${source}), but \`npx convex dev\` pushes your functions to ${cliUrl} (CONVEX_URL). New or changed functions will fail with "Could not find public function". Remove ${stale.join(" and ")} to follow \`convex dev\`, or point ${source} at ${cliUrl}.`
+    );
+  }
+  return warnings;
+}
 function deploymentEnv(rootDir, env, dev) {
   if (!dev) return env;
   let local;
@@ -181,7 +194,7 @@ function getConvexAliases(rootDir) {
   };
 }
 
-const CODEGEN_GUARDED_TEMPLATES = ["nuxt-convex-module-provide-api.mjs", "types/nuxt-convex-module-api-fallback.d.ts"];
+const CODEGEN_GUARDED_TEMPLATES = ["types/nuxt-convex-module-api-fallback.d.ts"];
 function watchConvexCodegen(nuxt) {
   if (!nuxt.options.dev) return;
   const generatedDir = join(nuxt.options.rootDir, resolveFunctionsDir(nuxt.options.rootDir), "_generated");
@@ -224,8 +237,14 @@ function setupDevScript(rootDir) {
   return { changed: true, from: dev, to };
 }
 
-function isAutoImported(name, mode) {
-  return mode === true || mode === "prefixed" && /convex/i.test(name);
+function prefixedName(name) {
+  if (/convex/i.test(name)) return name;
+  return /^[A-Z]/.test(name) ? `Convex${name}` : name.replace(/[A-Z]/, (letter) => `Convex${letter}`);
+}
+function autoImportedAs(name, mode, registered) {
+  if (mode !== "prefixed") return mode ? name : void 0;
+  const prefixed = prefixedName(name);
+  return prefixed !== name && registered.includes(prefixed) ? void 0 : prefixed;
 }
 const vue = (file) => `runtime/vue/${file}`;
 const composable = (file) => vue(`composables/${file}`);
@@ -253,9 +272,6 @@ const APP_IMPORTS = {
     { name: "useConvexStorageUrl", from: composable("use-storage-url") },
     { name: "useConvexAuth", from: vue("auth/index") },
     { name: "provideConvexAuth", from: vue("auth/index") },
-    { name: "provideConvexApi", from: vue("provide") },
-    { name: "useConvexApi", from: vue("provide") },
-    { name: "useConvexNamespace", from: vue("provide") },
     { name: "usePreloadedQuery", from: vue("hydration") },
     // Nuxt-only (imports `#app`), hence under runtime/nuxt/ — see PARITY.md.
     // Its types too, so `import type { AsyncQueryReturn } from '#imports'` works
@@ -344,15 +360,13 @@ const module$1 = defineNuxtModule({
     configKey: "convex",
     // Surfaced by Nuxt DevTools and the nuxt/modules registry.
     docs: "https://nuxt-convex-module.dev",
-    // `moduleDependencies` (below) is a Nuxt >= 4.1 feature — fail fast with a
-    // clear kit error on older Nuxt instead of silently skipping nuxt-security.
+    // The server code is written against `nuxt/server`, which ships in 4.6.
     compatibility: {
-      nuxt: ">=4.1.0"
+      nuxt: ">=4.6.0"
     }
   },
   defaults: {
     autoImports: true,
-    authRoute: "/api/auth",
     devtools: true,
     devScript: true
   },
@@ -369,26 +383,25 @@ const module$1 = defineNuxtModule({
     nuxt.options.vite.resolve ??= {};
     nuxt.options.vite.resolve.dedupe = [...nuxt.options.vite.resolve.dedupe ?? [], "convex"];
     const { url, siteUrl } = applyRuntimeConfig(nuxt, options);
+    const betterAuthOptions = readBetterAuthOptions(options);
     const diagnostics = validateModuleOptions({
       url,
       siteUrl,
-      authRoute: options.authRoute || "/api/auth",
+      authRoute: betterAuthOptions.authRoute || "/api/auth",
       loginPath: nuxt.options.runtimeConfig.public.convex.loginPath,
-      authClient: typeof options.betterAuth === "object" ? options.betterAuth.authClient : void 0,
+      authClient: betterAuthOptions.authClient,
       rootDir: nuxt.options.rootDir
     });
     for (const message of diagnostics.errors) logger.error(message);
     for (const message of diagnostics.warnings) logger.warn(message);
-    options.authRoute = diagnostics.authRoute;
     nuxt.options.runtimeConfig.public.convex.loginPath = diagnostics.loginPath;
     registerAuthClientAlias(resolver, nuxt, options);
     registerConvexAliases(nuxt);
-    registerConvexApiPlugin(resolver, nuxt);
     registerConvexTypeFallback(nuxt);
     const autoImports = options.autoImports ?? true;
     registerVueComposables(resolver, autoImports);
     registerAuthComponents(resolver, autoImports);
-    const integrations = registerIntegrations(resolver, nuxt, options, autoImports);
+    const integrations = registerIntegrations(resolver, nuxt, options, autoImports, diagnostics.authRoute);
     watchConvexCodegen(nuxt);
     if (nuxt.options.dev && options.devtools !== false && isDevtoolsUiEnabled(nuxt)) {
       const { setupDevtools } = await import('./chunks/index.mjs');
@@ -423,7 +436,7 @@ function isDevtoolsUiEnabled(nuxt) {
   const devtools = nuxt.options.devtools;
   return typeof devtools === "boolean" ? devtools : devtools?.enabled !== false;
 }
-function registerIntegrations(resolver, nuxt, options, autoImports) {
+function registerIntegrations(resolver, nuxt, options, autoImports, authRoute) {
   const report = (key, pkg, state) => {
     if (state.missingPackage) {
       logger.error(`\`convex.${key}\` is enabled but \`${pkg}\` is not installed. Run \`npm install ${pkg}\` or remove the option.`);
@@ -434,7 +447,7 @@ function registerIntegrations(resolver, nuxt, options, autoImports) {
   const resolve = (key, pkg) => report(key, pkg, resolveIntegrationState(options[key], isPackageInstalled(pkg, rootDir), isDeclaredDependency(pkg, rootDir)));
   const betterAuth = resolve("betterAuth", "@convex-dev/better-auth");
   if (betterAuth) {
-    registerBetterAuth(resolver, options.authRoute || "/api/auth", autoImports);
+    registerBetterAuth(resolver, authRoute, autoImports);
   } else {
     registerBaseConvexClient(resolver);
   }
@@ -471,11 +484,20 @@ function resolveSecurityState(nuxt, explicit) {
   return resolveIntegrationState(explicit, installed, declared);
 }
 function registerSecurity(resolver) {
-  addServerPlugin(resolver.resolve("./runtime/nuxt/security"));
+  const plugin = resolver.resolve("./runtime/nuxt/security");
+  addNitroPlugin({ nitro2: plugin, nitro3: plugin });
+}
+function readBetterAuthOptions(options) {
+  if ("authRoute" in options) logger.error("`convex.authRoute` moved to `convex.betterAuth.authRoute`.");
+  return typeof options.betterAuth === "object" ? options.betterAuth : {};
 }
 function applyRuntimeConfig(nuxt, options) {
-  const resolved = resolveDeploymentUrls(options, deploymentEnv(nuxt.options.rootDir, process.env, nuxt.options.dev));
+  const env = deploymentEnv(nuxt.options.rootDir, process.env, nuxt.options.dev);
+  const resolved = resolveDeploymentUrls(options, env);
   const url = nuxt.options._prepare ? "" : resolved.url;
+  if (nuxt.options.dev && url) {
+    for (const message of deploymentWarnings(options, env)) logger.warn(message);
+  }
   if (!url && !nuxt.options._prepare) {
     logger.warn(
       "No Convex deployment URL configured. Set NUXT_PUBLIC_CONVEX_URL or `convex.url` in nuxt.config, or run `npx convex dev`: it writes CONVEX_URL to .env.local, which the module reads in development."
@@ -493,7 +515,6 @@ function applyRuntimeConfig(nuxt, options) {
     crossDomainCallbackRoute,
     loginPath
   };
-  runtimeConfig.convex = { ...runtimeConfig.convex, siteUrl };
   return { url, siteUrl };
 }
 function registerConvexAliases(nuxt) {
@@ -513,42 +534,24 @@ function registerAuthClientAlias(resolver, nuxt, options) {
   nuxt.options.alias["#convex/auth-client"] = target;
   nuxt.options.nitro.alias["#convex/auth-client"] = target;
 }
-function registerConvexApiPlugin(resolver, nuxt) {
+function registerConvexTypeFallback(nuxt) {
   const functionsDir = resolveFunctionsDir(nuxt.options.rootDir);
-  const provideModule = resolver.resolve("./runtime/vue/provide");
   let notifiedMissing = false;
-  addPluginTemplate({
-    filename: "nuxt-convex-module-provide-api.mjs",
+  addTypeTemplate({
+    filename: "types/nuxt-convex-module-api-fallback.d.ts",
     getContents: () => {
-      if (!hasGeneratedApi(nuxt.options.rootDir, functionsDir)) {
-        if (nuxt.options.dev && !nuxt.options._prepare && !notifiedMissing) {
-          notifiedMissing = true;
-          logger.info(`Convex codegen not found in \`${functionsDir}/_generated\` \u2014 run \`npx convex dev\`. Convex features no-op until it exists.`);
-          hintAgent();
-        }
-        return "import { defineNuxtPlugin } from '#app'\nexport default defineNuxtPlugin(() => {})\n";
+      const generated = hasGeneratedApi(nuxt.options.rootDir, functionsDir);
+      if (!generated && nuxt.options.dev && !nuxt.options._prepare && !notifiedMissing) {
+        notifiedMissing = true;
+        logger.info(`Convex codegen not found in \`${functionsDir}/_generated\` \u2014 run \`npx convex dev\`. \`#convex/api\` is typed \`any\` until it exists.`);
+        hintAgent();
       }
-      if (notifiedMissing) {
+      if (generated && notifiedMissing) {
         notifiedMissing = false;
-        logger.success("Convex codegen detected \u2014 generated `api` wired app-wide.");
+        logger.success("Convex codegen detected \u2014 `#convex/api` is typed from it.");
       }
-      return [
-        "import { defineNuxtPlugin } from '#app'",
-        "import { api } from '#convex/api'",
-        `import { provideConvexApi } from ${JSON.stringify(provideModule)}`,
-        "export default defineNuxtPlugin((nuxtApp) => {",
-        "  provideConvexApi(api, nuxtApp.vueApp)",
-        "})",
-        ""
-      ].join("\n");
+      return convexTypeFallbackContents(generated, functionsDir);
     }
-  });
-}
-function registerConvexTypeFallback(nuxt) {
-  const functionsDir = resolveFunctionsDir(nuxt.options.rootDir);
-  addTypeTemplate({
-    filename: "types/nuxt-convex-module-api-fallback.d.ts",
-    getContents: () => convexTypeFallbackContents(hasGeneratedApi(nuxt.options.rootDir, functionsDir), functionsDir)
   }, { nuxt: true, nitro: true });
 }
 function registerVueComposables(resolver, autoImports) {
@@ -558,16 +561,20 @@ function registerAuthComponents(resolver, autoImports) {
   registerComponents(resolver, "core", autoImports);
 }
 function registerIntegrationImports(resolver, integration, autoImports) {
-  const kept = (entries) => entries.filter((entry) => isAutoImported(entry.name, autoImports)).map((entry) => ({ ...entry, from: resolver.resolve(`./${entry.from}`) }));
+  const kept = (entries) => entries.flatMap((entry) => {
+    const as = autoImportedAs(entry.name, autoImports, entries.map((e) => e.name));
+    return as ? [{ ...entry, as, from: resolver.resolve(`./${entry.from}`) }] : [];
+  });
   const app = kept(APP_IMPORTS[integration]);
   const server = kept(SERVER_IMPORTS[integration]);
   if (app.length > 0) addImports(app);
   if (server.length > 0) addServerImports(server);
 }
 function registerComponents(resolver, integration, autoImports) {
-  for (const { name, from } of APP_COMPONENTS[integration]) {
-    if (!isAutoImported(name, autoImports)) continue;
-    addComponent({ name, filePath: resolver.resolve(`./${from}`), export: name });
+  const entries = APP_COMPONENTS[integration];
+  for (const { name, from } of entries) {
+    const as = autoImportedAs(name, autoImports, entries.map((e) => e.name));
+    if (as) addComponent({ name: as, filePath: resolver.resolve(`./${from}`), export: name });
   }
 }
 const AUTH_PROXY_SECURITY_RULES = {
@@ -581,7 +588,7 @@ function registerBetterAuth(resolver, authRoute, autoImports) {
   registerComponents(resolver, "betterAuth", autoImports);
   addServerHandler({
     route: `${authRoute}/**`,
-    handler: resolver.resolve("./runtime/better-auth/nuxt/proxy")
+    handler: { nuxt: resolver.resolve("./runtime/better-auth/nuxt/proxy") }
   });
   extendRouteRules(`${authRoute}/**`, {
     cache: false,

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

@@ -1,22 +1,22 @@
 /**
- * Proxy all `${convex.authRoute}/**` requests (default `/api/auth/**`) to the
+ * Proxy all `${convex.betterAuth.authRoute}/**` requests (default `/api/auth/**`) to the
  * Convex site URL. This keeps auth cookies on the same origin (no CORS issues).
  *
- * The site URL is `convexAuth`'s to resolve: the private `runtimeConfig.convex.siteUrl`,
- * then the public one, then the environment — so a container built without it and
- * started with `NUXT_PUBLIC_CONVEX_SITE_URL` works. Reading only the private key here
- * used to fail every auth request in exactly that deployment.
+ * The site URL is `convexAuth`'s to resolve: `runtimeConfig.public.convex.siteUrl`,
+ * then the environment — so a container built without it and started with
+ * `NUXT_PUBLIC_CONVEX_SITE_URL` works.
  *
  * The method list matches the nuxt-security route rule the module registers on this
  * route; enforcing it here too keeps the proxy closed to `PUT`/`DELETE` probes when
  * nuxt-security is not installed.
  *
- * The path check: h3 routes the request's raw path, and the handler forwards the
- * URL-normalised one. `/api/auth/../../x` (or its `%2e%2e` spelling) matches this
- * route and normalises to `/x`, which the proxy would send to the site origin —
- * any HTTP action on the deployment, reached through the app's origin with the
- * app's cookies attached. Next.js normalises before routing, so upstream's
- * handler never sees such a path; Nitro does not, so it is refused here.
+ * The path check: Nitro 2 routes the request's raw path, and the handler forwards
+ * the URL-normalised one. `/api/auth/../../x` (or its `%2e%2e` spelling) matches
+ * this route and normalises to `/x`, which the proxy would send to the site
+ * origin — any HTTP action on the deployment, reached through the app's origin
+ * with the app's cookies attached. Next.js normalises before routing, so
+ * upstream's handler never sees such a path; Nitro 2 does not, so a dot segment
+ * in the part of the path this route matched is refused here.
  */
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Response>>;
+declare const _default: import("nuxt/server").EventHandler<Promise<Response>>;
 export default _default;

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

@@ -1,11 +1,13 @@
-import { assertMethod, createError, defineEventHandler, toWebRequest } from "h3";
+import { createError, defineEventHandler, getRouterParam } from "nuxt/server";
 import { convexAuth } from "./server.js";
+const METHODS = ["GET", "HEAD", "POST", "OPTIONS"];
 export default defineEventHandler(async (event) => {
-  assertMethod(event, ["GET", "HEAD", "POST", "OPTIONS"]);
-  const routed = event.path.split("?")[0];
-  const forwarded = new URL(toWebRequest(event).url).pathname;
-  if (forwarded !== routed) {
-    throw createError({ statusCode: 400, statusMessage: "Bad Request" });
+  if (!METHODS.includes(event.req.method)) {
+    throw createError({ status: 405, statusText: "Method Not Allowed" });
+  }
+  const matched = getRouterParam(event, "_", { decode: true }) ?? "";
+  if (matched.split(/[/\\]/).some((segment) => segment === "." || segment === "..")) {
+    throw createError({ status: 400, statusText: "Bad Request" });
   }
   return convexAuth(event).handler();
 });

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

@@ -1,16 +1,28 @@
 /**
  * Server-side Better Auth + Convex integration for Nuxt.
  *
- * Provides {@link convexAuth} for Nuxt server handlers: it takes the H3
- * `H3Event` every Nuxt server route, API handler and server middleware
- * receives, and returns a request-scoped, authenticated Convex client.
+ * Provides {@link convexAuth} for Nuxt server handlers: it takes the event
+ * every Nuxt server route, API handler and server middleware receives, and
+ * returns a request-scoped, authenticated Convex client.
  *
  * @module better-auth/server
  */
-import type { H3Event } from 'h3';
+import type { RequestEvent } from 'nuxt/schema';
 import type { GetTokenOptions } from '@convex-dev/better-auth/utils';
 import type { FunctionReference, FunctionReturnType } from 'convex/server';
 import type { Preloaded } from '../../vue/hydration.js';
+/**
+ * The server event {@link convexAuth} reads: the one `defineEventHandler` from
+ * `nuxt/server` passes, whose `req` is a web `Request`, or the h3 event a
+ * Nuxt 4 route defined with the auto-imported `defineEventHandler`, and
+ * `useRequestEvent()` during SSR, still pass, which carries `headers`.
+ *
+ * @public
+ */
+export type ConvexAuthEvent = Pick<RequestEvent, 'req' | 'context'> | {
+    headers: Headers;
+    context: Record<string, unknown>;
+};
 type OptionalArgs<FuncRef extends FunctionReference<any, any>> = FuncRef['_args'] extends Record<string, never> ? [args?: Record<string, never>] : [args: FuncRef['_args']];
 /**
  * Options for {@link convexAuth}.
@@ -28,8 +40,8 @@ export type ConvexAuthOptions = GetTokenOptions & {
      */
     convexUrl?: string;
     /**
-     * Override the Convex site URL. Defaults to `runtimeConfig.convex.siteUrl`,
-     * then `runtimeConfig.public.convex.siteUrl`, then the
+     * Override the Convex site URL. Defaults to
+     * `runtimeConfig.public.convex.siteUrl`, then the
      * `NUXT_PUBLIC_CONVEX_SITE_URL` process variable.
      */
     convexSiteUrl?: string;
@@ -58,7 +70,7 @@ export interface ConvexAuthService {
 /**
  * Create a per-request Better Auth + Convex helper for Nuxt server code.
  *
- * Adapts the Better Auth + Convex server helper pattern to H3 events.
+ * Adapts the Better Auth + Convex server helper pattern to Nuxt server 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
@@ -87,18 +99,18 @@ export interface ConvexAuthService {
  * })
  * ```
  *
- * @param event - The H3 event from a Nuxt server route or middleware.
+ * @param event - The event from a Nuxt server route or middleware, or `useRequestEvent()` during SSR. See {@link ConvexAuthEvent}.
  * @param opts  - Optional {@link ConvexAuthOptions}.
  *
  * @public
  */
-export declare function convexAuth(event: H3Event, opts?: ConvexAuthOptions): ConvexAuthService;
+export declare function convexAuth(event: ConvexAuthEvent, 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.
+ * per-request context, so the `event` is passed explicitly.
  *
  * @public
  */

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

@@ -1,4 +1,3 @@
-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";
@@ -65,7 +64,16 @@ const handler = async (request, siteUrl) => {
     headers: responseHeaders
   });
 };
-const nuxtHandler = (event, siteUrl) => () => handler(toWebRequest(event), siteUrl);
+const requestOf = (event) => "req" in event && event.req instanceof Request ? event.req : void 0;
+const nuxtHandler = (event, siteUrl) => () => {
+  const request = requestOf(event);
+  if (!request) {
+    throw new Error(
+      "[nuxt-convex-module] convexAuth(event).handler() needs the event `defineEventHandler` from `nuxt/server` passes, whose `req` is a web Request."
+    );
+  }
+  return handler(request, siteUrl);
+};
 const getArgsAndOptions = (args, token) => {
   return [args[0], { token }];
 };
@@ -78,8 +86,7 @@ export function convexAuth(event, opts) {
   const cachedGetToken = ({ forceRefresh } = {}) => {
     const cached = tokenCache[cacheKey];
     if (cached && !forceRefresh) return cached;
-    const headers = getRequestHeaders(event);
-    const mutableHeaders = new Headers(headers);
+    const mutableHeaders = new Headers(requestOf(event)?.headers ?? event.headers);
     mutableHeaders.delete("content-length");
     mutableHeaders.delete("transfer-encoding");
     mutableHeaders.set("accept-encoding", "identity");

package/dist/runtime/better-auth/vue/plugin.server.js

@@ -1,16 +1,15 @@
 import { computed } from "vue";
-import { setResponseHeader } from "h3";
-import { defineNuxtPlugin, useRuntimeConfig, useState, useRequestEvent } from "#app";
+import { defineNuxtPlugin, useRuntimeConfig, useState, useRequestEvent, useResponseHeader } from "#app";
 import { ConvexVueClient, ConvexClientKey } from "../../vue/client.js";
 import { CONVEX_INITIAL_TOKEN_KEY } from "../../nuxt/config.js";
 import { convexAuth } from "../nuxt/server.js";
 import { ConvexAuthStateKey } from "../../vue/auth/index.js";
-export async function prefetchAuthToken(event, initialToken) {
+export async function prefetchAuthToken(event, initialToken, cacheControl) {
   try {
     const token = await convexAuth(event).getToken();
     initialToken.value = token ?? null;
     if (token && event) {
-      setResponseHeader(event, "Cache-Control", "private, no-store");
+      cacheControl.value = "private, no-store";
     }
   } catch (error) {
     console.warn("[nuxt-convex-module] Failed to prefetch auth token for SSR:", error);
@@ -33,7 +32,7 @@ export default defineNuxtPlugin({
     nuxtApp.vueApp.provide(ConvexAuthStateKey, ssrAuthState);
     const event = useRequestEvent();
     if (event && !import.meta.prerender) {
-      await prefetchAuthToken(event, initialToken);
+      await prefetchAuthToken(event, initialToken, useResponseHeader("Cache-Control"));
     }
   }
 });

package/dist/runtime/nuxt/app.d.ts

@@ -39,9 +39,6 @@
  * const messages: AsyncQueryReturn<Doc<'messages'>[]> = useAsyncQuery(api.messages.list, {})
  * ```
  *
- * Before 1.0 the composable was auto-imported but reachable from no subpath,
- * so neither the explicit form nor the types could be written at all.
- *
  * @module app
  */
 export { useAsyncQuery, useConvexAsyncQuery, type AsyncQueryData, type AsyncQueryOptions, type AsyncQueryReturn, type AsyncQueryStatus, } from './composables/use-async-query.js';

package/dist/runtime/nuxt/config.js

@@ -5,7 +5,7 @@ export function getConvexRuntimeConfig() {
     const config = useRuntimeConfig();
     return {
       url: config.public?.convex?.url,
-      siteUrl: config.convex?.siteUrl || config.public?.convex?.siteUrl
+      siteUrl: config.public?.convex?.siteUrl
     };
   } catch {
     return {};

package/dist/runtime/nuxt/security.d.ts

@@ -21,7 +21,8 @@ export interface SecurityNitroApp {
  * origins are appended to whatever the app configured, whatever the order of
  * `modules`. nuxt-security sorts its own Nitro plugins last, so this listener
  * is in place before the hook fires. The deployment URL comes from runtime
- * config, so it need not be known at build time.
+ * config, so it need not be known at build time. `nuxt/server` is its only
+ * server import, so the same file runs on Nitro 2 and Nitro 3.
  *
  * `connect-src` is tightened only in production: creating it in dev would
  * block the Vite HMR and devtools WebSockets, which run on ports `'self'`

package/dist/runtime/nuxt/security.js

@@ -1,10 +1,10 @@
-import { getConvexRuntimeConfig } from "./config.js";
+import { useRuntimeConfig } from "nuxt/server";
 import { applyConvexSecurityDefaults, convexConnectSrc, convexResourceSrc } from "./csp.js";
 export default function convexSecurityPlugin(nitroApp) {
   nitroApp.hooks.hook("nuxt-security:routeRules", (rules) => {
     const global = rules["/**"];
     if (!global) return;
-    const { url, siteUrl } = getConvexRuntimeConfig();
+    const { url, siteUrl } = useRuntimeConfig().public?.convex ?? {};
     applyConvexSecurityDefaults(
       global,
       import.meta.dev ? [] : convexConnectSrc(url, siteUrl),