nuxt-convex-module 0.10.0 → 0.12.0

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
@@ -112,21 +117,16 @@ interface ModuleOptions {
     /**
      * Run Convex beside Nuxt with one command. On the first `nuxt dev` (or
      * `nuxt prepare`) in an app whose `dev` script is still the plain
-     * `nuxt dev`, the module rewrites it to `convex dev --start 'nuxt dev'`:
-     * the Convex CLI starts the dev deployment, starts Nuxt next to it, and
-     * hands it `CONVEX_URL` / `CONVEX_SITE_URL` in the environment — no `.env`
-     * needed for local development. A `dev` script you have already changed,
-     * or one that runs `convex dev` somewhere, is left alone. Set `false` to
-     * never touch `package.json`.
+     * `nuxt dev`, the module rewrites it to `convex dev --start "nuxt dev"`:
+     * the Convex CLI starts the dev deployment, writes its URL to `.env.local`
+     * and starts Nuxt next to it, and the module reads that file in
+     * development — no `.env` needed for local development. A `dev` script you
+     * have already changed, or one that runs `convex dev` somewhere, is left
+     * alone. Set `false` to never touch `package.json`.
      */
     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.10.0",
+  "version": "0.12.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,7 +1,9 @@
-import { useLogger, updateTemplates, defineNuxtModule, createResolver, addPlugin, hasNuxtModule, addServerPlugin, addPluginTemplate, addTypeTemplate, addImports, addServerImports, addComponent, addServerHandler, extendRouteRules, addRouteMiddleware } from '@nuxt/kit';
-import { join, isAbsolute } from 'node:path';
+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';
-import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { parseEnv } from 'node:util';
 
 function resolveIntegrationState(explicit, installed, declared = installed) {
   if (explicit === false) return { enabled: false, missingPackage: false };
@@ -50,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)) {
@@ -93,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;
@@ -110,11 +112,16 @@ function formatStartupSummary(url, functionsDir, integrations) {
   return `Convex ${url || "(no URL)"} \xB7 functions: ${functionsDir}/ \xB7 integrations: ${enabled.join(", ") || "none"}`;
 }
 function isPackageInstalled(id, rootDir) {
-  for (const base of [join(rootDir, "package.json"), import.meta.url]) {
-    const lookupPaths = createRequire(base).resolve.paths(id) ?? [];
-    if (lookupPaths.some((dir) => existsSync(join(dir, id, "package.json")))) return true;
+  return [rootDir, dirname(fileURLToPath(import.meta.url))].some(
+    (base) => nodeModulesPaths(base).some((dir) => existsSync(join(dir, id, "package.json")))
+  );
+}
+function nodeModulesPaths(dir) {
+  const paths = [];
+  for (let current = dir; ; current = dirname(current)) {
+    if (basename(current) !== "node_modules") paths.push(join(current, "node_modules"));
+    if (dirname(current) === current) return paths;
   }
-  return false;
 }
 function resolveDeploymentUrls(options, env) {
   return {
@@ -122,6 +129,29 @@ 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;
+  try {
+    local = parseEnv(readFileSync(join(rootDir, ".env.local"), "utf8"));
+  } catch {
+    return env;
+  }
+  return { ...local, ...env };
+}
 
 const logger$1 = useLogger("nuxt-convex-module");
 const DEFAULT_FUNCTIONS_DIR = "convex";
@@ -164,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");
@@ -175,9 +205,9 @@ function watchConvexCodegen(nuxt) {
   });
 }
 
-const PLAIN_NUXT_DEV = /^(?:npx )?(?:nuxt|nuxi) dev(?: [^&|;]*)?$/;
+const PLAIN_NUXT_DEV = /^(?:npx )?(?:nuxt|nuxi) dev(?: [^&|;"']*)?$/;
 function combinedDevScript(nuxtCommand) {
-  return `convex dev --start '${nuxtCommand}'`;
+  return `convex dev --start "${nuxtCommand}"`;
 }
 function setupDevScript(rootDir) {
   const path = join(rootDir, "package.json");
@@ -207,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}`);
@@ -236,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
@@ -327,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
   },
@@ -349,27 +380,28 @@ const module$1 = defineNuxtModule({
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
     nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
+    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');
@@ -389,15 +421,22 @@ const module$1 = defineNuxtModule({
       const result = setupDevScript(nuxt.options.rootDir);
       if (result.changed) {
         logger.info(`Set \`scripts.dev\` to \`${result.to}\` \u2014 one command now runs Convex beside Nuxt, no .env needed locally. Set \`convex.devScript: false\` to keep your own script.`);
+        hintAgent();
       }
     }
   }
 });
+let agentHinted = false;
+function hintAgent() {
+  if (agentHinted || !detectAgent().name) return;
+  agentHinted = true;
+  logger.info("An AI agent is running Nuxt. `CONVEX_AGENT_MODE=anonymous npx convex dev --once` sets up a local Convex deployment with no prompts and no account, writes .env.local and the codegen, then exits. For the setup steps and this module's API: `npx skills add https://nuxt-convex-module.dev --skill nuxt-convex-module -y`.");
+}
 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.`);
@@ -408,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);
   }
@@ -445,15 +484,25 @@ 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, process.env);
+  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. Note: `npx convex dev` writes CONVEX_URL to .env.local, which Nuxt does not read without `nuxt dev --dotenv .env.local`."
+      "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."
     );
+    hintAgent();
   }
   const siteUrl = resolved.siteUrl;
   const crossDomainCallbackRoute = typeof options.betterAuth === "object" && options.betterAuth.crossDomainCallbackRoute || "";
@@ -466,7 +515,6 @@ function applyRuntimeConfig(nuxt, options) {
     crossDomainCallbackRoute,
     loginPath
   };
-  runtimeConfig.convex = { ...runtimeConfig.convex, siteUrl };
   return { url, siteUrl };
 }
 function registerConvexAliases(nuxt) {
@@ -486,41 +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.`);
-        }
-        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) {
@@ -530,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 = {
@@ -553,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/auth0/vue/index.js

@@ -6,7 +6,7 @@ export function provideConvexAuthFromAuth0(options = {}) {
   const client = options.client ?? useConvexOrThrow("provideConvexAuthFromAuth0");
   return provideConvexAuth({ client, useAuth: useAuthFromAuth0 });
 }
-export const ConvexProviderWithAuth0 = defineComponent({
+export const ConvexProviderWithAuth0 = /* @__PURE__ */ defineComponent({
   name: "ConvexProviderWithAuth0",
   props: {
     client: { type: Object, default: void 0 }

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

@@ -1,18 +1,7 @@
-import { defineNuxtRouteMiddleware, navigateTo, useNuxtApp, useRequestEvent, useRuntimeConfig } from "#app";
+import { defineNuxtRouteMiddleware, navigateTo, useRuntimeConfig } from "#app";
 import { watch } from "vue";
 import { useBetterAuth } from "../vue/use-better-auth.js";
-import { convexAuth } from "./server.js";
-function loginTarget(to, loginPath) {
-  return { path: loginPath, query: { redirect: to.fullPath } };
-}
-export async function serverGuard(to, loginPath) {
-  const nuxtApp = useNuxtApp();
-  const event = useRequestEvent();
-  const authed = event ? await convexAuth(event).isAuthenticated() : false;
-  if (!authed && to.path !== loginPath) {
-    return nuxtApp.runWithContext(() => navigateTo(loginTarget(to, loginPath)));
-  }
-}
+import { loginTarget, serverGuard } from "./server-guard.js";
 function waitForSession(isPending) {
   return new Promise((resolve) => {
     const stop = watch(

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-guard.d.ts

@@ -0,0 +1,12 @@
+interface GuardedRoute {
+    path: string;
+    fullPath: string;
+}
+/** Where a visitor who isn't signed in goes: the login page, with the page they asked for in `?redirect=`. */
+export declare function loginTarget(to: GuardedRoute, loginPath: string): {
+    path: string;
+    query: {
+        redirect: string;
+    };
+};
+export {};

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

@@ -0,0 +1,13 @@
+import { navigateTo, useNuxtApp, useRequestEvent } from "#app";
+import { convexAuth } from "./server.js";
+export function loginTarget(to, loginPath) {
+  return { path: loginPath, query: { redirect: to.fullPath } };
+}
+export async function serverGuard(to, loginPath) {
+  const nuxtApp = useNuxtApp();
+  const event = useRequestEvent();
+  const authed = event ? await convexAuth(event).isAuthenticated() : false;
+  if (!authed && to.path !== loginPath) {
+    return nuxtApp.runWithContext(() => navigateTo(loginTarget(to, loginPath)));
+  }
+}

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");