nuxt-convex-module 0.9.1 → 0.11.0

package/dist/module.d.mts

@@ -1,5 +1,8 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
+/** The `convex.autoImports` option: every name, only the `Convex`-marked ones, or none. */
+type AutoImports = boolean | 'prefixed';
+
 /**
  * Configuration for the opt-in Better Auth integration.
  *
@@ -31,7 +34,7 @@ interface BetterAuthModuleOptions {
      */
     crossDomainCallbackRoute?: string;
     /**
-     * Route the `auth` middleware sends unauthenticated visitors to (and never
+     * Route the `convex-auth` middleware sends unauthenticated visitors to (and never
      * redirects away from, to avoid a self-redirect loop). The original
      * destination is appended as a `?redirect=` query so the login page can
      * return the visitor after sign-in. Defaults to `/login`.
@@ -88,6 +91,16 @@ interface ModuleOptions {
      * `nuxt.config`) turns this off too.
      */
     security?: boolean;
+    /**
+     * 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.
+     */
+    autoImports?: AutoImports;
     /** Route the Better Auth same-origin proxy is mounted at. Defaults to `/api/auth`. */
     authRoute?: string;
     /**
@@ -99,12 +112,12 @@ 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;
 }

package/dist/module.json

@@ -5,7 +5,7 @@
   "compatibility": {
     "nuxt": ">=4.1.0"
   },
-  "version": "0.9.1",
+  "version": "0.11.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 { 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 };
@@ -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,16 @@ function resolveDeploymentUrls(options, env) {
     siteUrl: stripTrailingSlashes(options.siteUrl || env.NUXT_PUBLIC_CONVEX_SITE_URL || env.CONVEX_SITE_URL || "")
   };
 }
+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";
@@ -175,9 +192,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,6 +224,9 @@ function setupDevScript(rootDir) {
   return { changed: true, from: dev, to };
 }
 
+function isAutoImported(name, mode) {
+  return mode === true || mode === "prefixed" && /convex/i.test(name);
+}
 const vue = (file) => `runtime/vue/${file}`;
 const composable = (file) => vue(`composables/${file}`);
 const asyncQuery = "runtime/nuxt/composables/use-async-query";
@@ -331,6 +351,7 @@ const module$1 = defineNuxtModule({
     }
   },
   defaults: {
+    autoImports: true,
     authRoute: "/api/auth",
     devtools: true,
     devScript: true
@@ -345,6 +366,8 @@ 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 diagnostics = validateModuleOptions({
       url,
@@ -362,9 +385,10 @@ const module$1 = defineNuxtModule({
     registerConvexAliases(nuxt);
     registerConvexApiPlugin(resolver, nuxt);
     registerConvexTypeFallback(nuxt);
-    registerVueComposables(resolver);
-    registerAuthComponents(resolver);
-    const integrations = registerIntegrations(resolver, nuxt, options);
+    const autoImports = options.autoImports ?? true;
+    registerVueComposables(resolver, autoImports);
+    registerAuthComponents(resolver, autoImports);
+    const integrations = registerIntegrations(resolver, nuxt, options, autoImports);
     watchConvexCodegen(nuxt);
     if (nuxt.options.dev && options.devtools !== false && isDevtoolsUiEnabled(nuxt)) {
       const { setupDevtools } = await import('./chunks/index.mjs');
@@ -384,15 +408,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) {
+function registerIntegrations(resolver, nuxt, options, autoImports) {
   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.`);
@@ -403,21 +434,21 @@ function registerIntegrations(resolver, nuxt, options) {
   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");
+    registerBetterAuth(resolver, options.authRoute || "/api/auth", autoImports);
   } else {
     registerBaseConvexClient(resolver);
   }
   const clerk = resolve("clerk", "@clerk/vue");
   if (clerk) {
-    registerClerk(resolver);
+    registerClerk(resolver, autoImports);
   }
   const auth0 = resolve("auth0", "@auth0/auth0-vue");
   if (auth0) {
-    registerAuth0(resolver);
+    registerAuth0(resolver, autoImports);
   }
   const polar = resolve("polar", "@convex-dev/polar");
   if (polar) {
-    registerPolarComponents(resolver);
+    registerPolarComponents(resolver, autoImports);
   }
   const security = report("security", "nuxt-security", resolveSecurityState(nuxt, options.security));
   if (security) {
@@ -443,12 +474,13 @@ function registerSecurity(resolver) {
   addServerPlugin(resolver.resolve("./runtime/nuxt/security"));
 }
 function applyRuntimeConfig(nuxt, options) {
-  const resolved = resolveDeploymentUrls(options, process.env);
+  const resolved = resolveDeploymentUrls(options, deploymentEnv(nuxt.options.rootDir, process.env, nuxt.options.dev));
   const url = nuxt.options._prepare ? "" : resolved.url;
   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 || "";
@@ -492,6 +524,7 @@ function registerConvexApiPlugin(resolver, nuxt) {
         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";
       }
@@ -518,19 +551,22 @@ function registerConvexTypeFallback(nuxt) {
     getContents: () => convexTypeFallbackContents(hasGeneratedApi(nuxt.options.rootDir, functionsDir), functionsDir)
   }, { nuxt: true, nitro: true });
 }
-function registerVueComposables(resolver) {
-  registerIntegrationImports(resolver, "core");
+function registerVueComposables(resolver, autoImports) {
+  registerIntegrationImports(resolver, "core", autoImports);
 }
-function registerAuthComponents(resolver) {
-  registerComponents(resolver, "core");
+function registerAuthComponents(resolver, autoImports) {
+  registerComponents(resolver, "core", autoImports);
 }
-function registerIntegrationImports(resolver, integration) {
-  const resolve = (entry) => ({ ...entry, from: resolver.resolve(`./${entry.from}`) });
-  if (APP_IMPORTS[integration].length > 0) addImports(APP_IMPORTS[integration].map(resolve));
-  if (SERVER_IMPORTS[integration].length > 0) addServerImports(SERVER_IMPORTS[integration].map(resolve));
+function registerIntegrationImports(resolver, integration, autoImports) {
+  const kept = (entries) => entries.filter((entry) => isAutoImported(entry.name, autoImports)).map((entry) => ({ ...entry, 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) {
+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 });
   }
 }
@@ -538,11 +574,11 @@ const AUTH_PROXY_SECURITY_RULES = {
   xssValidator: false,
   allowedMethodsRestricter: { methods: ["GET", "HEAD", "POST", "OPTIONS"] }
 };
-function registerBetterAuth(resolver, authRoute) {
+function registerBetterAuth(resolver, authRoute, autoImports) {
   addPlugin(resolver.resolve("./runtime/better-auth/vue/plugin.client"));
   addPlugin(resolver.resolve("./runtime/better-auth/vue/plugin.server"));
-  registerIntegrationImports(resolver, "betterAuth");
-  registerComponents(resolver, "betterAuth");
+  registerIntegrationImports(resolver, "betterAuth", autoImports);
+  registerComponents(resolver, "betterAuth", autoImports);
   addServerHandler({
     route: `${authRoute}/**`,
     handler: resolver.resolve("./runtime/better-auth/nuxt/proxy")
@@ -553,7 +589,7 @@ function registerBetterAuth(resolver, authRoute) {
     security: AUTH_PROXY_SECURITY_RULES
   });
   addRouteMiddleware({
-    name: "auth",
+    name: "convex-auth",
     path: resolver.resolve("./runtime/better-auth/nuxt/middleware"),
     global: false
   });
@@ -561,16 +597,16 @@ function registerBetterAuth(resolver, authRoute) {
 function registerBaseConvexClient(resolver) {
   addPlugin(resolver.resolve("./runtime/vue/plugin"));
 }
-function registerClerk(resolver) {
-  registerIntegrationImports(resolver, "clerk");
-  registerComponents(resolver, "clerk");
+function registerClerk(resolver, autoImports) {
+  registerIntegrationImports(resolver, "clerk", autoImports);
+  registerComponents(resolver, "clerk", autoImports);
 }
-function registerAuth0(resolver) {
-  registerIntegrationImports(resolver, "auth0");
-  registerComponents(resolver, "auth0");
+function registerAuth0(resolver, autoImports) {
+  registerIntegrationImports(resolver, "auth0", autoImports);
+  registerComponents(resolver, "auth0", autoImports);
 }
-function registerPolarComponents(resolver) {
-  registerComponents(resolver, "polar");
+function registerPolarComponents(resolver, autoImports) {
+  registerComponents(resolver, "polar", autoImports);
 }
 
 export { module$1 as default };

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

@@ -8,7 +8,7 @@
  * Usage in page:
  * ```vue
  * <script setup>
- * definePageMeta({ middleware: 'auth' })
+ * definePageMeta({ middleware: 'convex-auth' })
  * </script>
  * ```
  */

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/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/vue/auth-boundary.js

@@ -2,7 +2,7 @@ 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({
+const UserSubscription = /* @__PURE__ */ defineComponent({
   name: "UserSubscription",
   props: {
     getAuthUserFn: { type: Object, required: true }
@@ -15,7 +15,7 @@ const UserSubscription = defineComponent({
     };
   }
 });
-export const AuthBoundary = defineComponent({
+export const AuthBoundary = /* @__PURE__ */ defineComponent({
   name: "AuthBoundary",
   props: {
     /**