@nuxtjs/better-auth 0.2.1 → 0.2.3

package/dist/module.d.mts

@@ -2,11 +2,15 @@ import * as _nuxt_schema from '@nuxt/schema';
 import { Nuxt } from '@nuxt/schema';
 import { BetterAuthModuleOptions } from '../dist/runtime/config.js';
 export { BetterAuthModuleOptions, defineClientAuth, defineServerAuth } from '../dist/runtime/config.js';
-import { BetterAuthOptions } from 'better-auth';
+import { BetterAuthPlugin } from 'better-auth';
 export { AppSession, Auth, AuthActionError, AuthMeta, AuthMode, AuthRouteRules, AuthSession, AuthSocialProviderId, AuthUser, InferSession, InferUser, RequireSessionOptions, ServerAuthContext, UserMatch } from '../dist/runtime/types.js';
 
 type DbDialect = 'sqlite' | 'postgresql' | 'mysql';
 
+interface BetterAuthPluginSources {
+    server?: string[];
+    client?: string[];
+}
 interface BetterAuthDatabaseProviderBuildContext {
     hubDialect: DbDialect;
     usePlural: boolean;
@@ -28,12 +32,17 @@ interface BetterAuthDatabaseProviderDefinition {
 }
 declare module '@nuxt/schema' {
     interface NuxtHooks {
+        /** Register absolute plugin module paths during module setup. Sources are additive and are not deduplicated. */
+        'better-auth:plugins:extend': (sources: BetterAuthPluginSources) => void | Promise<void>;
         /**
-         * Extend better-auth config with additional plugins or options.
-         * Called after user's auth.config.ts is loaded.
-         * @param config - Partial config to merge into the auth options
+         * Add plugin schemas to generated Better Auth database tables.
+         * This build-time hook does not install plugins in the runtime auth instance.
+         * @param config - Plugins to include during schema generation
+         * @param config.plugins - Better Auth plugins whose schemas should be generated
          */
-        'better-auth:config:extend': (config: Partial<BetterAuthOptions>) => void | Promise<void>;
+        'better-auth:config:extend': (config: {
+            plugins?: BetterAuthPlugin[];
+        }) => void | Promise<void>;
         /**
          * Register or override Better Auth database providers.
          * Providers are auto-selected via `isEnabled` + `priority`.

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/better-auth",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "configKey": "auth",
   "compatibility": {
     "nuxt": ">=4.0.0"

package/dist/module.mjs

@@ -2,7 +2,7 @@ import { existsSync, statSync, writeFileSync, readFileSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { getLayerDirectories, updateTemplates, addServerImportsDir, addServerImports, addServerScanDir, addServerHandler, addImportsDir, addPlugin, addComponentsDir, extendPages, addTemplate, hasNuxtModule, addTypeTemplate, defineNuxtModule, createResolver } from '@nuxt/kit';
 import { consola as consola$1 } from 'consola';
-import { isAbsolute, join, relative, dirname } from 'pathe';
+import { isAbsolute, resolve, join, relative, dirname } from 'pathe';
 import { defu } from 'defu';
 import { toRouteMatcher, createRouter } from 'radix3';
 import { generateDrizzleSchema as generateDrizzleSchema$1 } from 'auth/api';
@@ -10,10 +10,10 @@ import { randomBytes } from 'node:crypto';
 import { isCI, isTest } from 'std-env';
 export { defineClientAuth, defineServerAuth } from '../dist/runtime/config.js';
 
-const version = "0.2.1";
+const version = "0.2.3";
 
 const CONFIG_EXTENSIONS = [".ts", ".js"];
-const CONFIG_EXTENSION_RE = /\.(?:ts|js)$/;
+const CONFIG_EXTENSION_RE$1 = /\.(?:ts|js)$/;
 const DEFAULT_CONFIG_FILES = {
   server: "server/auth.config",
   client: "app/auth.config"
@@ -22,8 +22,12 @@ const OPTION_KEY_BY_KIND = {
   server: "serverConfig",
   client: "clientConfig"
 };
+const PLUGIN_OPTION_KEY_BY_KIND = {
+  server: "serverPluginSources",
+  client: "clientPluginSources"
+};
 function stripConfigExtension(path) {
-  return path.replace(CONFIG_EXTENSION_RE, "");
+  return path.replace(CONFIG_EXTENSION_RE$1, "");
 }
 function defaultConfigExists(path) {
   return CONFIG_EXTENSIONS.some((ext) => existsSync(`${path}${ext}`));
@@ -125,6 +129,18 @@ function resolveAuthConfigDescriptors(nuxt, files = {}, dependencies = {}) {
     client: resolveAuthConfigDescriptor(nuxt, "client", files.client, dependencies)
   };
 }
+function resolveAuthPluginSources(nuxt) {
+  const resolved = { server: [], client: [] };
+  for (const { directory, layer } of getLayerDirectoriesWithConfigs(nuxt)) {
+    for (const kind of ["server", "client"]) {
+      const sources = layer?.config?.auth?.[PLUGIN_OPTION_KEY_BY_KIND[kind]];
+      if (!Array.isArray(sources))
+        continue;
+      resolved[kind].push(...sources.map((source) => isAbsolute(source) ? source : resolve(directory.root, source)));
+    }
+  }
+  return resolved;
+}
 
 function resolveNitroCompatibilityImports(nuxtVersion) {
   const major = Number.parseInt(nuxtVersion, 10);
@@ -311,6 +327,8 @@ function loadLocalEnv(rootDir) {
     return;
   process.loadEnvFile(envPath);
 }
+const NO_DEFAULT_EXPORT_MESSAGE = "[@nuxtjs/better-auth] auth.config.ts does not export default. Expected: export default defineServerAuth(...)";
+const SCHEMA_NOT_REGENERATED_MESSAGE = "The schema was not regenerated and any existing generated schema file was left unchanged.";
 async function loadUserAuthConfig(configPath, throwOnError = false, alias, runtimeConfig = {}, rootDir) {
   const { createJiti } = await import('jiti');
   const { defineServerAuth: runtimeDefineServerAuth } = await import('../dist/runtime/config.js');
@@ -331,17 +349,18 @@ async function loadUserAuthConfig(configPath, throwOnError = false, alias, runti
     if (typeof configFn === "function") {
       return configFn({ runtimeConfig, db: null });
     }
-    consola$1.warn("[@nuxtjs/better-auth] auth.config.ts does not export default. Expected: export default defineServerAuth(...)");
     if (throwOnError) {
+      consola$1.warn(NO_DEFAULT_EXPORT_MESSAGE);
       throw new Error("auth.config.ts must export default defineServerAuth(...)");
     }
-    return {};
+    consola$1.error(`${NO_DEFAULT_EXPORT_MESSAGE}. ${SCHEMA_NOT_REGENERATED_MESSAGE}`);
+    return null;
   } catch (error) {
     if (throwOnError) {
       throw new Error(`Failed to load auth config: ${error instanceof Error ? error.message : error}`);
     }
-    consola$1.error("[@nuxtjs/better-auth] Failed to load auth config for schema generation. Schema may be incomplete:", error);
-    return {};
+    consola$1.error(`[@nuxtjs/better-auth] Failed to load auth config for schema generation. ${SCHEMA_NOT_REGENERATED_MESSAGE}`, error);
+    return null;
   } finally {
     const sharedDefineServerAuth = schemaGlobals.__nuxtBetterAuthDefineServerAuth;
     if (sharedDefineServerAuth) {
@@ -372,6 +391,7 @@ function getHubCasing(hub) {
 }
 
 const NODE_MODULES_SEGMENT_RE = /[\\/]/;
+const CONFIG_EXTENSION_RE = /\.[cm]?[jt]s$/;
 function resolveSchemaSecondaryStorageInjection(hubSecondaryStorage, userHasSecondaryStorage, isProduction) {
   if (hubSecondaryStorage === true)
     return { inject: false };
@@ -401,11 +421,13 @@ function resolveHubSchemaPath(buildDir, rootDir, dialect, exists = existsSync) {
 }
 async function loadAuthOptions(context) {
   const isProduction = !context.nuxt.options.dev;
-  const configFile = `${context.serverConfigPath}.ts`;
+  const configFile = CONFIG_EXTENSION_RE.test(context.serverConfigPath) ? context.serverConfigPath : `${context.serverConfigPath}.ts`;
   const alias = Object.fromEntries(
     Object.entries(context.nuxt.options.alias).filter(([, value]) => typeof value === "string").map(([key, value]) => [key, value])
   );
   const userConfig = await loadUserAuthConfig(configFile, isProduction, alias, context.nuxt.options.runtimeConfig, context.nuxt.options.rootDir);
+  if (!userConfig)
+    return null;
   const extendedConfig = {};
   await context.nuxt.callHook("better-auth:config:extend", extendedConfig);
   const plugins = [...userConfig.plugins || [], ...extendedConfig.plugins || []];
@@ -419,8 +441,17 @@ async function setupBetterAuthSchema(nuxt, serverConfigPath, options, consola, h
     return;
   }
   const context = { nuxt, serverConfigPath };
+  const nuxtWithHubHooks = nuxt;
+  nuxtWithHubHooks.hook("hub:db:schema:extend", ({ paths, dialect: hookDialect }) => {
+    const schemaPath = resolveHubSchemaPath(nuxt.options.buildDir, nuxt.options.rootDir, hookDialect);
+    if (schemaPath)
+      paths.unshift(schemaPath);
+  });
   try {
-    const { userConfig, plugins } = await loadAuthOptions(context);
+    const authConfig = await loadAuthOptions(context);
+    if (!authConfig)
+      return;
+    const { userConfig, plugins } = authConfig;
     const userHasSecondaryStorage = userConfig.secondaryStorage != null;
     const secondaryStorageResolution = resolveSchemaSecondaryStorageInjection(hubSecondaryStorage, userHasSecondaryStorage, !nuxt.options.dev);
     if (secondaryStorageResolution.error)
@@ -458,12 +489,6 @@ async function setupBetterAuthSchema(nuxt, serverConfigPath, options, consola, h
     addTemplate({ filename: `better-auth/schema.${dialect}.ts`, getContents: () => schemaCode, write: true });
     addTemplate({ filename: `better-auth/schema.${dialect}.mjs`, getContents: () => schemaCode, write: true });
     consola.info(`Generated ${dialect} schema (.ts + .mjs)`);
-    const nuxtWithHubHooks = nuxt;
-    nuxtWithHubHooks.hook("hub:db:schema:extend", ({ paths, dialect: hookDialect }) => {
-      const schemaPath = resolveHubSchemaPath(nuxt.options.buildDir, nuxt.options.rootDir, hookDialect);
-      if (schemaPath)
-        paths.unshift(schemaPath);
-    });
   } catch (error) {
     const isProduction = !nuxt.options.dev;
     if (isProduction)
@@ -563,21 +588,24 @@ function resolveDatabaseProvider(input) {
 }
 
 function resolveSecondaryStorage(input) {
-  const { options, clientOnly, hasNuxtHub, hub } = input;
+  const { options, clientOnly, consola } = input;
   const opt = options.hubSecondaryStorage ?? false;
-  const useHubKV = opt === true;
-  const secondaryStorageEnabled = opt === true || opt === "custom";
+  if (opt === true) {
+    if (clientOnly)
+      consola.warn("[nuxt-better-auth] hubSecondaryStorage: true is ignored in clientOnly mode because this module does not run the auth server.");
+    else
+      consola.warn('[nuxt-better-auth] hubSecondaryStorage: true cannot use NuxtHub KV with Better Auth 1.7 because NuxtHub KV lacks atomic getAndDelete and increment operations. The module will ignore this option and continue without injecting secondary storage. Without a custom secondary store, sessions use the configured database when one exists and rate limiting defaults to process-local memory. Configure rateLimit.storage as "database" or provide rateLimit.customStorage for shared limits. Set auth.hubSecondaryStorage to false to silence this warning, or use "custom" with an atomic secondaryStorage in defineServerAuth(). Track NuxtHub support: https://github.com/nuxt-hub/core/pull/927');
+    return { hubSecondaryStorage: false, secondaryStorageEnabled: false };
+  }
+  const secondaryStorageEnabled = opt === "custom";
   if (secondaryStorageEnabled && clientOnly) {
     throw new Error("[nuxt-better-auth] hubSecondaryStorage is not available in clientOnly mode. Either disable clientOnly or remove auth.hubSecondaryStorage.");
   }
-  if (useHubKV && (!hasNuxtHub || !hub?.kv)) {
-    throw new Error("[nuxt-better-auth] hubSecondaryStorage: true requires @nuxthub/core with hub.kv: true. Either add hub.kv: true to your nuxt.config or remove auth.hubSecondaryStorage.");
-  }
-  return { useHubKV, secondaryStorageEnabled };
+  return { hubSecondaryStorage: opt, secondaryStorageEnabled };
 }
 function setupRuntimeConfig(input) {
   const { nuxt, options, clientOnly, databaseProvider, consola } = input;
-  const { useHubKV, secondaryStorageEnabled } = resolveSecondaryStorage(input);
+  const { hubSecondaryStorage, secondaryStorageEnabled } = resolveSecondaryStorage(input);
   nuxt.options.runtimeConfig.public = nuxt.options.runtimeConfig.public || {};
   const configuredSiteUrl = nuxt.options.runtimeConfig.public.siteUrl;
   nuxt.options.runtimeConfig.public.siteUrl = configuredSiteUrl || process.env.NUXT_PUBLIC_SITE_URL || "";
@@ -599,27 +627,44 @@ function setupRuntimeConfig(input) {
     if (!siteUrl)
       consola.warn("clientOnly mode: set runtimeConfig.public.siteUrl (or NUXT_PUBLIC_SITE_URL) to your frontend URL");
     consola.info("clientOnly mode enabled - server utilities (serverAuth, getRequestSession, getUserSession, requireUserSession) are not available");
-    return { useHubKV, secondaryStorageEnabled };
+    return { secondaryStorageEnabled };
   }
   const currentSecret = nuxt.options.runtimeConfig.betterAuthSecret;
   nuxt.options.runtimeConfig.betterAuthSecret = currentSecret || process.env.NUXT_BETTER_AUTH_SECRET || process.env.BETTER_AUTH_SECRET || "";
-  nuxt.options.runtimeConfig.auth = defu(nuxt.options.runtimeConfig.auth, {
-    hubSecondaryStorage: options.hubSecondaryStorage ?? false
+  const authRuntimeConfig = defu(nuxt.options.runtimeConfig.auth, {
+    hubSecondaryStorage
   });
-  return { useHubKV, secondaryStorageEnabled };
+  authRuntimeConfig.hubSecondaryStorage = hubSecondaryStorage;
+  nuxt.options.runtimeConfig.auth = authRuntimeConfig;
+  return { secondaryStorageEnabled };
 }
 
-function buildSecondaryStorageCode(useHubKV) {
-  if (!useHubKV)
-    return "export function createSecondaryStorage() { return undefined }";
-  return `import { kv } from '@nuxthub/kv'
-export function createSecondaryStorage() {
+function buildImports(sources) {
   return {
-    get: async (key) => kv.get(\`_auth:\${key}\`),
-    set: async (key, value, ttl) => kv.set(\`_auth:\${key}\`, value, { ttl }),
-    delete: async (key) => kv.del(\`_auth:\${key}\`),
-  }
-}`;
+    imports: sources.map((source, index) => `import plugin${index} from ${JSON.stringify(source)}`).join("\n"),
+    names: sources.map((_, index) => `plugin${index}`).join(", ")
+  };
+}
+function buildExtendedServerAuthCode(configPath, sources) {
+  const plugins = buildImports(sources);
+  return `import createAppAuth from ${JSON.stringify(configPath)}
+import { extendServerAuth } from '@nuxtjs/better-auth/config'
+${plugins.imports}
+
+export default extendServerAuth(createAppAuth, [${plugins.names}])
+`;
+}
+function buildExtendedClientAuthCode(configPath, sources) {
+  const plugins = buildImports(sources);
+  return `import createAppAuthClient from ${JSON.stringify(configPath)}
+import { extendClientAuth } from '@nuxtjs/better-auth/config'
+${plugins.imports}
+
+export default extendClientAuth(createAppAuthClient, [${plugins.names}])
+`;
+}
+function buildSecondaryStorageCode() {
+  return "export function createSecondaryStorage() { return undefined }";
 }
 function buildDatabaseCode(input) {
   if (input.provider === "nuxthub") {
@@ -813,6 +858,9 @@ async function resolveAuthModuleSetup(input, dependencies = {}) {
     configExists: dependencies.configExists
   });
   assertConfigPresence(configs, clientOnly);
+  const pluginSources = resolveAuthPluginSources(nuxt);
+  pluginSources.server.push(...input.registeredPluginSources?.server || []);
+  pluginSources.client.push(...input.registeredPluginSources?.client || []);
   const aliases = {
     "#auth/server": clientOnly ? void 0 : configs.server.path,
     "#auth/client": configs.client.path
@@ -850,13 +898,8 @@ async function resolveAuthModuleSetup(input, dependencies = {}) {
     options,
     clientOnly,
     databaseProvider: providerId,
-    hasNuxtHub,
-    hub,
     consola
   });
-  if (runtime.useHubKV && !nuxt.options.alias["hub:kv"]) {
-    throw new Error("[nuxt-better-auth] hub:kv not found. Ensure @nuxthub/core is loaded before this module and hub.kv is enabled.");
-  }
   const hasHubDb = providerId === "nuxthub";
   if (hasHubDb && !nuxt.options.alias["hub:db"]) {
     throw new Error("[nuxt-better-auth] hub:db not found. Ensure @nuxthub/core is loaded before this module and hub.db is configured.");
@@ -865,6 +908,7 @@ async function resolveAuthModuleSetup(input, dependencies = {}) {
     clientOnly,
     configs,
     aliases,
+    pluginSources,
     hub: {
       hasNuxtHub,
       options: hub,
@@ -912,12 +956,7 @@ function registerServerTypeTemplates(input) {
     filename: "types/auth-secondary-storage.d.ts",
     getContents: () => `
 declare module '#auth/secondary-storage' {
-  interface SecondaryStorage {
-    get: (key: string) => Promise<string | null>
-    set: (key: string, value: unknown, ttl?: number) => Promise<void>
-    delete: (key: string) => Promise<void>
-  }
-  export function createSecondaryStorage(): SecondaryStorage | undefined
+  export function createSecondaryStorage(): undefined
 }
 `
   }, { nitro: true });
@@ -1371,94 +1410,122 @@ const module$1 = defineNuxtModule({
       process.env.NUXT_BETTER_AUTH_SECRET = generatedSecret;
     await createDefaultAuthConfigFiles(nuxt);
   },
-  async setup(options, nuxt) {
-    const resolver = createResolver(import.meta.url);
-    const nitroImports = resolveNitroCompatibilityImports(nuxt._version);
-    nuxt.options.alias["#better-auth/nitro-compat"] = resolver.resolve(`./runtime/server/internal/${nitroImports.runtime}`);
-    const setup = await resolveAuthModuleSetup({
-      nuxt,
-      options,
-      runtimeTypesAugmentPath: resolver.resolve("./runtime/types/augment"),
-      consola
-    });
-    if (setup.aliases["#auth/server"])
-      nuxt.options.alias["#auth/server"] = setup.aliases["#auth/server"];
-    nuxt.options.alias["#auth/client"] = setup.aliases["#auth/client"];
-    if (!setup.clientOnly) {
-      const secondaryStorageTemplate = addTemplate({
-        filename: "better-auth/secondary-storage.mjs",
-        getContents: () => buildSecondaryStorageCode(setup.runtime.useHubKV),
-        write: true
-      });
-      nuxt.options.alias["#auth/secondary-storage"] = secondaryStorageTemplate.dst;
-      const databaseTemplate = addTemplate({
-        filename: "better-auth/database.mjs",
-        getContents: () => setup.database.providerDefinition.buildDatabaseCode(setup.database.buildContext),
-        write: true
+  setup(options, nuxt) {
+    nuxt.hook("modules:done", async () => {
+      const resolver = createResolver(import.meta.url);
+      const nitroImports = resolveNitroCompatibilityImports(nuxt._version);
+      nuxt.options.alias["#better-auth/nitro-compat"] = resolver.resolve(`./runtime/server/internal/${nitroImports.runtime}`);
+      const registeredPluginSources = {};
+      await nuxt.callHook("better-auth:plugins:extend", registeredPluginSources);
+      for (const source of [...registeredPluginSources.server || [], ...registeredPluginSources.client || []]) {
+        if (!isAbsolute(source))
+          throw new Error(`[nuxt-better-auth] Modules must register absolute plugin source paths. Received: ${source}`);
+      }
+      const setup = await resolveAuthModuleSetup({
+        nuxt,
+        options,
+        runtimeTypesAugmentPath: resolver.resolve("./runtime/types/augment"),
+        consola,
+        registeredPluginSources
       });
-      nuxt.options.alias["#auth/database"] = databaseTemplate.dst;
-      const schemaTemplate = addTemplate({
-        filename: "better-auth/schema.mjs",
-        getContents: () => buildSchemaExportCode(setup.database.hasHubDb, setup.database.buildContext?.hubDialect ?? "sqlite"),
+      let serverConfigPath = setup.aliases["#auth/server"];
+      let clientConfigPath = setup.aliases["#auth/client"];
+      if (serverConfigPath && setup.pluginSources.server.length) {
+        const serverConfigCode = buildExtendedServerAuthCode(setup.configs.server.path, setup.pluginSources.server);
+        serverConfigPath = addTemplate({
+          filename: "better-auth/server.config.ts",
+          getContents: () => serverConfigCode,
+          write: true
+        }).dst;
+        await mkdir(dirname(serverConfigPath), { recursive: true });
+        await writeFile(serverConfigPath, serverConfigCode);
+      }
+      if (setup.pluginSources.client.length) {
+        clientConfigPath = addTemplate({
+          filename: "better-auth/client.config.ts",
+          getContents: () => buildExtendedClientAuthCode(setup.configs.client.path, setup.pluginSources.client),
+          write: true
+        }).dst;
+      }
+      if (serverConfigPath)
+        nuxt.options.alias["#auth/server"] = serverConfigPath;
+      nuxt.options.alias["#auth/client"] = clientConfigPath;
+      if (!setup.clientOnly) {
+        const secondaryStorageTemplate = addTemplate({
+          filename: "better-auth/secondary-storage.mjs",
+          getContents: () => buildSecondaryStorageCode(),
+          write: true
+        });
+        nuxt.options.alias["#auth/secondary-storage"] = secondaryStorageTemplate.dst;
+        const databaseTemplate = addTemplate({
+          filename: "better-auth/database.mjs",
+          getContents: () => setup.database.providerDefinition.buildDatabaseCode(setup.database.buildContext),
+          write: true
+        });
+        nuxt.options.alias["#auth/database"] = databaseTemplate.dst;
+        const schemaTemplate = addTemplate({
+          filename: "better-auth/schema.mjs",
+          getContents: () => buildSchemaExportCode(setup.database.hasHubDb, setup.database.buildContext?.hubDialect ?? "sqlite"),
+          write: true
+        });
+        nuxt.options.alias["#auth/schema"] = schemaTemplate.dst;
+        if (setup.schemaGeneration)
+          await ensureSchemaBootstrap(schemaTemplate.dst, setup.database.buildContext?.hubDialect ?? "sqlite");
+      }
+      if (setup.prepareTypes) {
+        registerPrepareTypesHook({
+          nuxt,
+          serverDir: setup.prepareTypes.serverDir,
+          hasHubDb: setup.prepareTypes.hasHubDb
+        });
+      }
+      if (setup.database.providerDefinition) {
+        const setupCtx = {
+          nuxt,
+          options,
+          clientOnly: setup.clientOnly
+        };
+        await setup.database.providerDefinition.setup?.(setupCtx);
+      }
+      const authRouteRulesTemplate = addTemplate({
+        filename: "better-auth/route-rules.mjs",
+        getContents: () => buildAuthRouteRulesCode(collectAuthRouteRules(nuxt)),
         write: true
       });
-      nuxt.options.alias["#auth/schema"] = schemaTemplate.dst;
-      if (setup.schemaGeneration)
-        await ensureSchemaBootstrap(schemaTemplate.dst, setup.database.buildContext?.hubDialect ?? "sqlite");
-    }
-    if (setup.prepareTypes) {
-      registerPrepareTypesHook({
-        nuxt,
-        serverDir: setup.prepareTypes.serverDir,
-        hasHubDb: setup.prepareTypes.hasHubDb
-      });
-    }
-    if (setup.database.providerDefinition) {
-      const setupCtx = {
-        nuxt,
-        options,
-        clientOnly: setup.clientOnly
-      };
-      await setup.database.providerDefinition.setup?.(setupCtx);
-    }
-    const authRouteRulesTemplate = addTemplate({
-      filename: "better-auth/route-rules.mjs",
-      getContents: () => buildAuthRouteRulesCode(collectAuthRouteRules(nuxt)),
-      write: true
-    });
-    nuxt.options.alias["#auth/route-rules"] = authRouteRulesTemplate.dst;
-    if (setup.serverTypes) {
-      registerServerTypeTemplates({
-        serverConfigPath: setup.serverTypes.serverConfigPath,
-        hasHubDb: setup.serverTypes.hasHubDb,
+      nuxt.options.alias["#auth/route-rules"] = authRouteRulesTemplate.dst;
+      if (setup.serverTypes) {
+        registerServerTypeTemplates({
+          serverConfigPath,
+          hasHubDb: setup.serverTypes.hasHubDb,
+          runtimeTypesPath: resolver.resolve("./runtime/types"),
+          sharedServerConfigSafe: [setup.configs.server.path, ...setup.pluginSources.server].every(isServerConfigSharedTypeSafe),
+          h3TypesPath: nitroImports.h3,
+          nitroTypesPath: nitroImports.types
+        });
+      }
+      if (setup.schemaGeneration) {
+        if (setup.schemaGeneration.externalizeNuxtHubDatabase)
+          registerNuxtHubDatabaseExternalHook(nuxt);
+        await setupBetterAuthSchema(
+          nuxt,
+          serverConfigPath,
+          options,
+          consola,
+          setup.schemaGeneration.hubSecondaryStorage
+        );
+      }
+      registerSharedTypeTemplates({
+        runtimeTypesAugmentPath: setup.sharedTypes.runtimeTypesAugmentPath,
         runtimeTypesPath: resolver.resolve("./runtime/types"),
-        sharedServerConfigSafe: isServerConfigSharedTypeSafe(setup.serverTypes.serverConfigPath),
-        h3TypesPath: nitroImports.h3,
-        nitroTypesPath: nitroImports.types
+        clientConfigPath,
+        h3TypesPath: nitroImports.h3
       });
-    }
-    if (setup.schemaGeneration) {
-      if (setup.schemaGeneration.externalizeNuxtHubDatabase)
-        registerNuxtHubDatabaseExternalHook(nuxt);
-      await setupBetterAuthSchema(
-        nuxt,
-        setup.schemaGeneration.serverConfigPath,
-        options,
-        consola,
-        setup.schemaGeneration.hubSecondaryStorage
-      );
-    }
-    registerSharedTypeTemplates({
-      runtimeTypesAugmentPath: setup.sharedTypes.runtimeTypesAugmentPath,
-      runtimeTypesPath: resolver.resolve("./runtime/types"),
-      clientConfigPath: setup.sharedTypes.clientConfigPath,
-      h3TypesPath: nitroImports.h3
+      registerTemplateHmrHook(nuxt);
+      registerServerRuntime({ clientOnly: setup.clientOnly, resolve: resolver.resolve });
+      registerAuthMiddlewareHook(nuxt, resolver.resolve);
+      await registerDevtools({ nuxt, clientOnly: setup.clientOnly, hasHubDb: setup.database.hasHubDb, resolve: resolver.resolve });
+      registerRouteRulesMetaHook(nuxt);
     });
-    registerTemplateHmrHook(nuxt);
-    registerServerRuntime({ clientOnly: setup.clientOnly, resolve: resolver.resolve });
-    registerAuthMiddlewareHook(nuxt, resolver.resolve);
-    await registerDevtools({ nuxt, clientOnly: setup.clientOnly, hasHubDb: setup.database.hasHubDb, resolve: resolver.resolve });
-    registerRouteRulesMetaHook(nuxt);
   }
 });
 

package/dist/runtime/app/composables/useUserSession.js

@@ -87,8 +87,21 @@ export function useUserSession() {
       throw error;
     }
   }
+  function queueHydrationReconciliation() {
+    if (hydrationReconcileQueued.value)
+      return;
+    hydrationReconcileQueued.value = true;
+    nuxtApp.hook("app:mounted", async () => {
+      await fetchSession({ force: true });
+      hydrationReconcileQueued.value = false;
+    });
+  }
   if (runtimeFlags.client && rawClient) {
     const clientSession = rawClient.useSession();
+    const initialClientSession = clientSession.value;
+    const shouldReconcileInitialHydration = nuxtApp.isHydrating && nuxtApp.payload.serverRendered && Boolean(session.value && user.value) && !initialClientSession?.data?.session && !initialClientSession?.data?.user && !initialClientSession?.isPending && !initialClientSession?.isRefetching;
+    if (shouldReconcileInitialHydration)
+      queueHydrationReconciliation();
     watch(
       () => clientSession.value,
       (newSession) => {
@@ -101,21 +114,14 @@ export function useUserSession() {
         } else if (!newSession?.isPending && !newSession?.isRefetching) {
           const isHydrationEmptySnapshot = nuxtApp.isHydrating && nuxtApp.payload.serverRendered && Boolean(session.value && user.value) && !newSession?.data?.session && !newSession?.data?.user;
           if (isHydrationEmptySnapshot) {
-            if (!hydrationReconcileQueued.value) {
-              hydrationReconcileQueued.value = true;
-              nuxtApp.hook("app:mounted", async () => {
-                await fetchSession({ force: true });
-                hydrationReconcileQueued.value = false;
-              });
-            }
+            queueHydrationReconciliation();
             return;
           }
           clearSession();
         }
         if (!authReady.value && !newSession?.isPending && !newSession?.isRefetching)
           authReady.value = true;
-      },
-      { immediate: true }
+      }
     );
   }
   function waitForSession() {

package/dist/runtime/config.d.ts

@@ -1,5 +1,5 @@
 import type { BetterAuthOptions, BetterAuthPlugin } from 'better-auth';
-import type { BetterAuthClientOptions } from 'better-auth/client';
+import type { BetterAuthClientOptions, BetterAuthClientPlugin } from 'better-auth/client';
 import type { ServerAuthContext as BaseServerAuthContext } from './types/augment.js';
 import { createAuthClient } from 'better-auth/vue';
 export interface ServerAuthContextExtension {
@@ -17,6 +17,23 @@ export type ClientAuthConfig = Omit<BetterAuthClientOptions, 'baseURL'> & {
 };
 export type ServerAuthConfigFn = (ctx: ServerAuthContext) => ServerAuthConfig;
 export type ClientAuthConfigFn = (ctx: ClientAuthContext) => ClientAuthConfig;
+type ServerPlugins<T> = T extends {
+    plugins: infer P extends readonly BetterAuthPlugin[];
+} ? P : [];
+type ClientPlugins<T> = T extends {
+    plugins: infer P extends BetterAuthClientPlugin[];
+} ? P : [];
+type ExtendedServerAuthConfig<T, P extends readonly BetterAuthPlugin[]> = Omit<T, 'plugins'> & {
+    plugins: [...ServerPlugins<T>, ...P];
+};
+type ExtendedClientAuthConfig<T, P extends BetterAuthClientPlugin[]> = Omit<T, 'plugins'> & {
+    plugins: [...ClientPlugins<T>, ...P];
+};
+export type ClientAuthFactory<T extends ClientAuthConfig> = ((baseURL: string) => ReturnType<typeof createAuthClient<T>>) & {
+    resolveOptions: (baseURL: string) => T & {
+        baseURL: string;
+    };
+};
 export type ModuleDatabaseProviderId = 'none' | 'nuxthub' | (string & {});
 export type EffectiveDatabaseProviderId = 'user' | ModuleDatabaseProviderId;
 export interface BetterAuthModuleOptions {
@@ -26,6 +43,10 @@ export interface BetterAuthModuleOptions {
     serverConfig?: string;
     /** Client config path. Relative paths resolve from the layer that declares them. Default: 'app/auth.config' */
     clientConfig?: string;
+    /** Server plugin modules. Relative paths resolve from the declaring layer. Sources are additive and are not deduplicated. */
+    serverPluginSources?: string[];
+    /** Client plugin modules. Relative paths resolve from the declaring layer. Sources are additive and are not deduplicated. */
+    clientPluginSources?: string[];
     redirects?: {
         /** Where to redirect unauthenticated users. Default: '/login' */
         login?: string;
@@ -50,9 +71,9 @@ export interface BetterAuthModuleOptions {
      */
     redirectQueryKey?: string;
     /**
-     * Enable secondary storage for sessions.
-     * - `true`: Use NuxtHub KV (requires hub.kv: true)
-     * - `'custom'`: User provides own secondaryStorage in defineServerAuth()
+     * Configure secondary storage for sessions.
+     * - `true`: Temporarily falls back to database-backed sessions with a setup warning
+     * - `'custom'`: User provides an atomic secondaryStorage in defineServerAuth()
      * - `false` (default): No secondary storage from module
      */
     hubSecondaryStorage?: boolean | 'custom';
@@ -84,4 +105,7 @@ export interface AuthPrivateRuntimeConfig {
 }
 export declare function defineServerAuth<const R>(config: (ctx: ServerAuthContext) => R & ServerAuthConfig): (ctx: ServerAuthContext) => R;
 export declare function defineServerAuth<const R>(config: R & ServerAuthConfig): (ctx: ServerAuthContext) => R;
-export declare function defineClientAuth<T extends ClientAuthConfig>(config: T | ((ctx: ClientAuthContext) => T)): (baseURL: string) => ReturnType<typeof createAuthClient<T>>;
+export declare function extendServerAuth<const R extends ServerAuthConfig, const P extends readonly BetterAuthPlugin[]>(createConfig: (ctx: ServerAuthContext) => R, plugins: P): (ctx: ServerAuthContext) => ExtendedServerAuthConfig<R, P>;
+export declare function defineClientAuth<T extends ClientAuthConfig>(config: T | ((ctx: ClientAuthContext) => T)): ClientAuthFactory<T>;
+export declare function extendClientAuth<T extends ClientAuthConfig, const P extends BetterAuthClientPlugin[]>(createClient: ClientAuthFactory<T>, plugins: P): ClientAuthFactory<ExtendedClientAuthConfig<T, P>>;
+export {};

package/dist/runtime/config.js

@@ -2,12 +2,30 @@ import { createAuthClient } from "better-auth/vue";
 export function defineServerAuth(config) {
   return typeof config === "function" ? config : () => config;
 }
+export function extendServerAuth(createConfig, plugins) {
+  return (ctx) => {
+    const config = createConfig(ctx);
+    const basePlugins = config.plugins || [];
+    return { ...config, plugins: [...basePlugins, ...plugins] };
+  };
+}
+function createClientAuthFactory(resolveOptions) {
+  const factory = ((baseURL) => createAuthClient(resolveOptions(baseURL)));
+  factory.resolveOptions = resolveOptions;
+  return factory;
+}
 export function defineClientAuth(config) {
-  return (baseURL) => {
+  return createClientAuthFactory((baseURL) => {
     const ctx = { siteUrl: baseURL };
     const resolved = typeof config === "function" ? config(ctx) : config;
     const { baseURL: configuredBaseURL, ...resolvedOptions } = resolved;
-    const clientOptions = { ...resolvedOptions, baseURL: configuredBaseURL ?? baseURL };
-    return createAuthClient(clientOptions);
-  };
+    return { ...resolvedOptions, baseURL: configuredBaseURL ?? baseURL };
+  });
+}
+export function extendClientAuth(createClient, plugins) {
+  return createClientAuthFactory((baseURL) => {
+    const config = createClient.resolveOptions(baseURL);
+    const basePlugins = config.plugins || [];
+    return { ...config, plugins: [...basePlugins, ...plugins] };
+  });
 }

package/dist/runtime/server/api/_better-auth/config.get.js

@@ -25,7 +25,7 @@ export default defineEventHandler(async (event) => {
           },
           preserveRedirect: publicAuth?.preserveRedirect ?? true,
           redirectQueryKey: publicAuth?.redirectQueryKey ?? "redirect",
-          hubSecondaryStorage: privateAuth?.hubSecondaryStorage ?? false,
+          hubSecondaryStorage: privateAuth?.hubSecondaryStorage === true ? false : privateAuth?.hubSecondaryStorage ?? false,
           useDatabase: publicAuth?.useDatabase ?? false,
           databaseProvider: publicAuth?.databaseProvider ?? "none"
         },

package/dist/runtime/server/utils/auth.d.ts

@@ -4,6 +4,7 @@ import { betterAuth } from 'better-auth';
 import createServerAuth from '#auth/server';
 type AuthOptions = ReturnType<typeof createServerAuth>;
 type UserAuthConfig = AuthOptions & {
+    rateLimit?: BetterAuthOptions['rateLimit'];
     secrets?: BetterAuthOptions['secrets'];
     trustedOrigins?: BetterAuthOptions['trustedOrigins'];
     secondaryStorage?: BetterAuthOptions['secondaryStorage'];

package/dist/runtime/server/utils/auth.js

@@ -1,7 +1,6 @@
 import { betterAuth, env } from "better-auth";
 import { withoutProtocol } from "ufo";
 import { createDatabase, db } from "#auth/database";
-import { createSecondaryStorage } from "#auth/secondary-storage";
 import createServerAuth from "#auth/server";
 import { getRequestHost, getRequestProtocol, useRuntimeConfig } from "../internal/nitro-compat.js";
 import { resolveCustomSecondaryStorageRequirement } from "./custom-secondary-storage.js";
@@ -9,6 +8,8 @@ const _authCache = /* @__PURE__ */ new Map();
 const requestAuthKey = Symbol.for("nuxt-better-auth.requestAuth");
 let _baseURLInferenceLogged = false;
 let _customSecondaryStorageMisconfigWarned = false;
+let _unsupportedHubSecondaryStorageWarned = false;
+let _secondaryStorageRateLimitFallbackWarned = false;
 const fallbackRequestAuthContext = /* @__PURE__ */ new WeakMap();
 function getRequestAuthContext(event) {
   const eventWithContext = event;
@@ -214,6 +215,10 @@ export function serverAuth(event) {
   const database = createDatabase(event);
   const trustedOrigins = withDevTrustedOrigins(userConfig.trustedOrigins);
   const hubSecondaryStorage = runtimeConfig.auth?.hubSecondaryStorage;
+  if (hubSecondaryStorage === true && !_unsupportedHubSecondaryStorageWarned) {
+    _unsupportedHubSecondaryStorageWarned = true;
+    console.warn("[nuxt-better-auth] Runtime hubSecondaryStorage: true is unsupported with Better Auth 1.7 and will be ignored. The module will preserve secondaryStorage from defineServerAuth(). Remove NUXT_AUTH_HUB_SECONDARY_STORAGE or set it to false.");
+  }
   const customSecondaryStorage = resolveCustomSecondaryStorageRequirement(hubSecondaryStorage, userConfig.secondaryStorage != null, Boolean(import.meta.dev));
   if (customSecondaryStorage?.shouldThrow)
     throw new Error(customSecondaryStorage.message);
@@ -221,6 +226,12 @@ export function serverAuth(event) {
     _customSecondaryStorageMisconfigWarned = true;
     console.warn(customSecondaryStorage.message);
   }
+  const useMemoryRateLimit = userConfig.rateLimit?.storage === "secondary-storage" && !userConfig.rateLimit.customStorage && !userConfig.secondaryStorage;
+  if (useMemoryRateLimit && !_secondaryStorageRateLimitFallbackWarned) {
+    _secondaryStorageRateLimitFallbackWarned = true;
+    console.warn('[nuxt-better-auth] rateLimit.storage: "secondary-storage" requires secondaryStorage. Falling back to process-local memory. Set rateLimit.storage to "database" or provide rateLimit.customStorage for shared limits.');
+  }
+  const rateLimit = useMemoryRateLimit ? { ...userConfig.rateLimit, storage: "memory" } : userConfig.rateLimit;
   if (!database) {
     const cached = _authCache.get(cacheKey);
     if (cached) {
@@ -231,8 +242,8 @@ export function serverAuth(event) {
   }
   const authOptions = {
     ...userConfig,
+    ...rateLimit ? { rateLimit } : {},
     ...database ? { database } : {},
-    ...hubSecondaryStorage === true ? { secondaryStorage: createSecondaryStorage() } : {},
     secret: betterAuthSecret,
     baseURL: siteUrl,
     trustedOrigins

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtjs/better-auth",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Nuxt module for Better Auth integration with NuxtHub, route protection, session management, and role-based access",
   "author": "onmax",
   "license": "MIT",