@onmax/nuxt-better-auth 0.0.2-alpha.12 → 0.0.2-alpha.14

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0"
   },
-  "version": "0.0.2-alpha.12",
+  "version": "0.0.2-alpha.14",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -5,7 +5,7 @@ import { consola as consola$1 } from 'consola';
 import { defu } from 'defu';
 import { join } from 'pathe';
 import { toRouteMatcher, createRouter } from 'radix3';
-import pluralize from 'pluralize';
+import { generateDrizzleSchema as generateDrizzleSchema$1 } from '@better-auth/cli/api';
 export { defineClientAuth, defineServerAuth } from '../dist/runtime/config.js';
 
 function setupDevTools(nuxt) {
@@ -23,160 +23,51 @@ function setupDevTools(nuxt) {
   });
 }
 
-function toSnakeCase(str) {
-  return str.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z\d])([A-Z])/g, "$1_$2").toLowerCase();
+function dialectToProvider(dialect) {
+  return dialect === "postgresql" ? "pg" : dialect;
 }
-function generateDrizzleSchema(tables, dialect, options) {
-  const typedTables = tables;
-  const imports = getImports(dialect, options);
-  const tableDefinitions = Object.entries(typedTables).map(([tableName, table]) => generateTable(tableName, table, dialect, typedTables, options)).join("\n\n");
-  return `${imports}
-
-${tableDefinitions}
-`;
-}
-function getImports(dialect, options) {
-  switch (dialect) {
-    case "sqlite":
-      return `import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'`;
-    case "postgresql":
-      return options?.useUuid ? `import { boolean, integer, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'` : `import { boolean, integer, pgTable, text, timestamp } from 'drizzle-orm/pg-core'`;
-    case "mysql":
-      return `import { boolean, int, mysqlTable, text, timestamp, varchar } from 'drizzle-orm/mysql-core'`;
-  }
-}
-function generateTable(tableName, table, dialect, allTables, options) {
-  const tableFunc = dialect === "sqlite" ? "sqliteTable" : dialect === "postgresql" ? "pgTable" : "mysqlTable";
-  const hasCustomModelName = table.modelName && table.modelName !== tableName;
-  let dbTableName = hasCustomModelName ? table.modelName : tableName;
-  if (options?.casing === "snake_case" && !hasCustomModelName)
-    dbTableName = toSnakeCase(dbTableName);
-  if (options?.usePlural && !hasCustomModelName)
-    dbTableName = pluralize(dbTableName);
-  const fields = Object.entries(table.fields).map(([fieldName, field]) => generateField(fieldName, field, dialect, allTables, options)).join(",\n    ");
-  const idField = generateIdField(dialect, options);
-  return `export const ${tableName} = ${tableFunc}('${dbTableName}', {
-    ${idField},
-    ${fields}
-  })`;
-}
-function generateIdField(dialect, options) {
-  switch (dialect) {
-    case "sqlite":
-      if (options?.useUuid)
-        consola$1.warn("[@onmax/nuxt-better-auth] useUuid ignored for SQLite (no native uuid type). Using text.");
-      return `id: text('id').primaryKey()`;
-    case "postgresql":
-      return options?.useUuid ? `id: uuid('id').defaultRandom().primaryKey()` : `id: text('id').primaryKey()`;
-    case "mysql":
-      return `id: varchar('id', { length: 36 }).primaryKey()`;
-  }
-}
-function generateField(fieldName, field, dialect, allTables, options) {
-  const dbFieldName = options?.casing === "snake_case" ? toSnakeCase(fieldName) : fieldName;
-  const isFkToId = options?.useUuid && field.references?.field === "id";
-  let fieldDef;
-  if (isFkToId && dialect === "postgresql")
-    fieldDef = `uuid('${dbFieldName}')`;
-  else if (isFkToId && dialect === "mysql")
-    fieldDef = `varchar('${dbFieldName}', { length: 36 })`;
-  else
-    fieldDef = getFieldType(field.type, dialect, dbFieldName);
-  if (field.required && field.defaultValue === void 0)
-    fieldDef += ".notNull()";
-  if (field.unique)
-    fieldDef += ".unique()";
-  if (field.defaultValue !== void 0) {
-    if (typeof field.defaultValue === "boolean")
-      fieldDef += `.default(${field.defaultValue})`;
-    else if (typeof field.defaultValue === "string")
-      fieldDef += `.default('${field.defaultValue}')`;
-    else if (typeof field.defaultValue === "function")
-      fieldDef += `.$defaultFn(${field.defaultValue})`;
-    else
-      fieldDef += `.default(${field.defaultValue})`;
-    if (field.required)
-      fieldDef += ".notNull()";
-  }
-  if (typeof field.onUpdate === "function" && field.type === "date")
-    fieldDef += `.$onUpdate(${field.onUpdate})`;
-  if (field.references) {
-    const refTable = field.references.model;
-    if (allTables[refTable])
-      fieldDef += `.references(() => ${refTable}.${field.references.field})`;
-  }
-  return `${fieldName}: ${fieldDef}`;
-}
-function getFieldType(type, dialect, fieldName) {
-  const normalizedType = Array.isArray(type) ? "string" : type;
-  switch (dialect) {
-    case "sqlite":
-      return getSqliteType(normalizedType, fieldName);
-    case "postgresql":
-      return getPostgresType(normalizedType, fieldName);
-    case "mysql":
-      return getMysqlType(normalizedType, fieldName);
-  }
-}
-function getSqliteType(type, fieldName) {
-  switch (type) {
-    case "string":
-      return `text('${fieldName}')`;
-    case "boolean":
-      return `integer('${fieldName}', { mode: 'boolean' })`;
-    case "date":
-      return `integer('${fieldName}', { mode: 'timestamp' })`;
-    case "number":
-      return `integer('${fieldName}')`;
-    default:
-      return `text('${fieldName}')`;
-  }
-}
-function getPostgresType(type, fieldName) {
-  switch (type) {
-    case "string":
-      return `text('${fieldName}')`;
-    case "boolean":
-      return `boolean('${fieldName}')`;
-    case "date":
-      return `timestamp('${fieldName}')`;
-    case "number":
-      return `integer('${fieldName}')`;
-    default:
-      return `text('${fieldName}')`;
-  }
-}
-function getMysqlType(type, fieldName) {
-  switch (type) {
-    case "string":
-      return `text('${fieldName}')`;
-    case "boolean":
-      return `boolean('${fieldName}')`;
-    case "date":
-      return `timestamp('${fieldName}')`;
-    case "number":
-      return `int('${fieldName}')`;
-    default:
-      return `text('${fieldName}')`;
+async function generateDrizzleSchema(authOptions, dialect, schemaOptions) {
+  const provider = dialectToProvider(dialect);
+  const options = {
+    ...authOptions,
+    advanced: {
+      ...authOptions.advanced,
+      database: {
+        ...authOptions.advanced?.database,
+        ...schemaOptions?.useUuid && { generateId: "uuid" }
+      }
+    }
+  };
+  const adapter = {
+    id: "drizzle",
+    options: {
+      provider,
+      camelCase: schemaOptions?.casing !== "snake_case",
+      adapterConfig: { usePlural: schemaOptions?.usePlural ?? false }
+    }
+  };
+  const result = await generateDrizzleSchema$1({ adapter, options });
+  if (!result.code) {
+    throw new Error(`Schema generation returned empty result for ${dialect}`);
   }
+  return result.code;
 }
 async function loadUserAuthConfig(configPath, throwOnError = false) {
   const { createJiti } = await import('jiti');
   const { defineServerAuth } = await import('../dist/runtime/config.js');
   const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false });
-  const key = "defineServerAuth";
-  const g = globalThis;
-  if (!g[key]) {
+  if (!globalThis.defineServerAuth) {
     defineServerAuth._count = 0;
-    g[key] = defineServerAuth;
+    globalThis.defineServerAuth = defineServerAuth;
   }
-  g[key]._count++;
+  globalThis.defineServerAuth._count++;
   try {
     const mod = await jiti.import(configPath);
     const configFn = typeof mod === "object" && mod !== null && "default" in mod ? mod.default : mod;
     if (typeof configFn === "function") {
       return configFn({ runtimeConfig: {}, db: null });
     }
+    consola$1.warn("[@onmax/nuxt-better-auth] auth.config.ts does not export a function. Expected: export default defineServerAuth(...)");
     if (throwOnError) {
       throw new Error("auth.config.ts must export default defineServerAuth(...)");
     }
@@ -188,9 +79,9 @@ async function loadUserAuthConfig(configPath, throwOnError = false) {
     consola$1.error("[@onmax/nuxt-better-auth] Failed to load auth config for schema generation. Schema may be incomplete:", error);
     return {};
   } finally {
-    g[key]._count--;
-    if (!g[key]._count) {
-      delete g[key];
+    globalThis.defineServerAuth._count--;
+    if (!globalThis.defineServerAuth._count) {
+      globalThis.defineServerAuth = void 0;
     }
   }
 }
@@ -257,14 +148,15 @@ const module$1 = defineNuxtModule({
       consola.info("clientOnly mode enabled - server utilities (serverAuth, getUserSession, requireUserSession) are not available");
     }
     if (!clientOnly) {
-      const betterAuthSecret = process.env.BETTER_AUTH_SECRET || process.env.NUXT_BETTER_AUTH_SECRET || nuxt.options.runtimeConfig.betterAuthSecret || "";
+      const currentSecret = nuxt.options.runtimeConfig.betterAuthSecret;
+      nuxt.options.runtimeConfig.betterAuthSecret = currentSecret || process.env.BETTER_AUTH_SECRET || "";
+      const betterAuthSecret = nuxt.options.runtimeConfig.betterAuthSecret;
       if (!nuxt.options.dev && !betterAuthSecret) {
         throw new Error("[nuxt-better-auth] BETTER_AUTH_SECRET is required in production. Set BETTER_AUTH_SECRET or NUXT_BETTER_AUTH_SECRET environment variable.");
       }
       if (betterAuthSecret && betterAuthSecret.length < 32) {
         throw new Error("[nuxt-better-auth] BETTER_AUTH_SECRET must be at least 32 characters for security");
       }
-      nuxt.options.runtimeConfig.betterAuthSecret = betterAuthSecret;
       nuxt.options.runtimeConfig.auth = defu(nuxt.options.runtimeConfig.auth, {
         secondaryStorage: secondaryStorageEnabled
       });
@@ -312,7 +204,7 @@ declare module '#auth/secondary-storage' {
   export function createSecondaryStorage(): SecondaryStorage | undefined
 }
 `
-      });
+      }, { nitro: true, node: true });
       addTypeTemplate({
         filename: "types/auth-database.d.ts",
         getContents: () => `
@@ -322,7 +214,7 @@ declare module '#auth/database' {
   export const db: unknown
 }
 `
-      });
+      }, { nitro: true, node: true });
       addTypeTemplate({
         filename: "types/nuxt-better-auth-infer.d.ts",
         getContents: () => `
@@ -354,7 +246,7 @@ declare module '@onmax/nuxt-better-auth/config' {
   export function defineServerAuth<T extends ServerAuthConfig>(config: (ctx: _AugmentedServerAuthContext) => T): (ctx: _AugmentedServerAuthContext) => T
 }
 `
-      });
+      }, { nuxt: true, nitro: true, node: true });
       addTypeTemplate({
         filename: "types/nuxt-better-auth-nitro.d.ts",
         getContents: () => `
@@ -465,27 +357,22 @@ async function setupBetterAuthSchema(nuxt, serverConfigPath, options) {
     const extendedConfig = {};
     await nuxt.callHook("better-auth:config:extend", extendedConfig);
     const plugins = [...userConfig.plugins || [], ...extendedConfig.plugins || []];
-    const { getAuthTables } = await import('better-auth/db');
-    const tables = getAuthTables({
+    const authOptions = {
+      ...userConfig,
       plugins,
-      secondaryStorage: options.secondaryStorage ? {
-        get: async (_key) => null,
-        set: async (_key, _value, _ttl) => {
-        },
-        delete: async (_key) => {
-        }
-      } : void 0
-    });
-    const useUuid = userConfig.advanced?.database?.generateId === "uuid";
+      secondaryStorage: options.secondaryStorage ? { get: async (_key) => null, set: async (_key, _value, _ttl) => {
+      }, delete: async (_key) => {
+      } } : void 0
+    };
     const hubCasing = getHubCasing(hub);
-    const schemaOptions = { ...options.schema, useUuid, casing: options.schema?.casing ?? hubCasing };
-    const schemaCode = generateDrizzleSchema(tables, dialect, schemaOptions);
+    const schemaOptions = { ...options.schema, useUuid: userConfig.advanced?.database?.generateId === "uuid", casing: options.schema?.casing ?? hubCasing };
+    const schemaCode = await generateDrizzleSchema(authOptions, dialect, schemaOptions);
     const schemaDir = join(nuxt.options.buildDir, "better-auth");
     const schemaPath = join(schemaDir, `schema.${dialect}.ts`);
     await mkdir(schemaDir, { recursive: true });
     await writeFile(schemaPath, schemaCode);
     addTemplate({ filename: `better-auth/schema.${dialect}.ts`, getContents: () => schemaCode, write: true });
-    consola.info(`Generated ${dialect} schema with ${Object.keys(tables).length} tables`);
+    consola.info(`Generated ${dialect} schema`);
   } catch (error) {
     if (isProduction) {
       throw error;

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

@@ -1,9 +1,9 @@
 import { defineEventHandler } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
 import { serverAuth } from "../../utils/auth.js";
-export default defineEventHandler(async () => {
+export default defineEventHandler(async (event) => {
   try {
-    const auth = serverAuth();
+    const auth = serverAuth(event);
     const options = auth.options;
     const runtimeConfig = useRuntimeConfig();
     const publicAuth = runtimeConfig.public?.auth;

package/dist/runtime/server/api/auth/[...all].js

@@ -1,6 +1,6 @@
 import { defineEventHandler, toWebRequest } from "h3";
 import { serverAuth } from "../../utils/auth.js";
 export default defineEventHandler(async (event) => {
-  const auth = serverAuth();
+  const auth = serverAuth(event);
   return auth.handler(toWebRequest(event));
 });

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

@@ -1,5 +1,7 @@
 import type { Auth } from 'better-auth';
+import type { H3Event } from 'h3';
 import createServerAuth from '#auth/server';
 type AuthInstance = Auth<ReturnType<typeof createServerAuth>>;
-export declare function serverAuth(): AuthInstance;
+/** Returns Better Auth instance. Pass event for accurate URL detection on first call. */
+export declare function serverAuth(event?: H3Event): AuthInstance;
 export {};

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

@@ -2,15 +2,72 @@ import { createDatabase, db } from "#auth/database";
 import { createSecondaryStorage } from "#auth/secondary-storage";
 import createServerAuth from "#auth/server";
 import { betterAuth } from "better-auth";
+import { getRequestHost, getRequestProtocol } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
+import { withoutProtocol } from "ufo";
 let _auth = null;
-export function serverAuth() {
+function validateURL(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    throw new Error(`Invalid siteUrl: "${url}". Must be a valid URL.`);
+  }
+}
+function getNitroOrigin(e) {
+  const cert = process.env.NITRO_SSL_CERT;
+  const key = process.env.NITRO_SSL_KEY;
+  let host = process.env.NITRO_HOST || process.env.HOST;
+  let port;
+  if (import.meta.dev)
+    port = process.env.NITRO_PORT || process.env.PORT || "3000";
+  let protocol = cert && key || !import.meta.dev ? "https" : "http";
+  try {
+    if ((import.meta.dev || import.meta.prerender) && process.env.__NUXT_DEV__) {
+      const origin = JSON.parse(process.env.__NUXT_DEV__).proxy.url;
+      host = withoutProtocol(origin);
+      protocol = origin.includes("https") ? "https" : "http";
+    } else if ((import.meta.dev || import.meta.prerender) && process.env.NUXT_VITE_NODE_OPTIONS) {
+      const origin = JSON.parse(process.env.NUXT_VITE_NODE_OPTIONS).baseURL.replace("/__nuxt_vite_node__", "");
+      host = withoutProtocol(origin);
+      protocol = origin.includes("https") ? "https" : "http";
+    } else if (e) {
+      host = getRequestHost(e, { xForwardedHost: true }) || host;
+      protocol = getRequestProtocol(e, { xForwardedProto: true }) || protocol;
+    }
+  } catch {
+  }
+  if (!host)
+    return void 0;
+  if (host.includes(":") && !host.startsWith("[")) {
+    const hostParts = host.split(":");
+    port = hostParts.pop();
+    host = hostParts.join(":");
+  }
+  const portSuffix = port ? `:${port}` : "";
+  return `${protocol}://${host}${portSuffix}`;
+}
+function getBaseURL(event) {
+  const config = useRuntimeConfig();
+  if (config.public.siteUrl && typeof config.public.siteUrl === "string")
+    return validateURL(config.public.siteUrl);
+  const nitroOrigin = getNitroOrigin(event);
+  if (nitroOrigin)
+    return validateURL(nitroOrigin);
+  if (process.env.VERCEL_URL)
+    return validateURL(`https://${process.env.VERCEL_URL}`);
+  if (process.env.CF_PAGES_URL)
+    return validateURL(`https://${process.env.CF_PAGES_URL}`);
+  if (process.env.URL)
+    return validateURL(process.env.URL.startsWith("http") ? process.env.URL : `https://${process.env.URL}`);
+  if (import.meta.dev)
+    return "http://localhost:3000";
+  throw new Error("siteUrl required. Set NUXT_PUBLIC_SITE_URL.");
+}
+export function serverAuth(event) {
   if (_auth)
     return _auth;
   const runtimeConfig = useRuntimeConfig();
-  const siteUrl = runtimeConfig.public.siteUrl;
-  if (!siteUrl)
-    throw new Error("siteUrl must be configured. Set NUXT_PUBLIC_SITE_URL or configure in nuxt.config.");
+  const siteUrl = getBaseURL(event);
   const database = createDatabase();
   const userConfig = createServerAuth({ runtimeConfig, db });
   _auth = betterAuth({

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

@@ -2,7 +2,7 @@ import { createError } from "h3";
 import { matchesUser } from "../../utils/match-user.js";
 import { serverAuth } from "./auth.js";
 export async function getUserSession(event) {
-  const auth = serverAuth();
+  const auth = serverAuth(event);
   const session = await auth.api.getSession({ headers: event.headers });
   return session;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onmax/nuxt-better-auth",
   "type": "module",
-  "version": "0.0.2-alpha.12",
+  "version": "0.0.2-alpha.14",
   "packageManager": "pnpm@10.15.1",
   "description": "Nuxt module for Better Auth integration with NuxtHub, route protection, session management, and role-based access",
   "author": "onmax",
@@ -10,6 +10,14 @@
     "type": "git",
     "url": "https://github.com/onmax/nuxt-better-auth"
   },
+  "agents": {
+    "skills": [
+      {
+        "name": "nuxt-better-auth",
+        "path": "./skills/nuxt-better-auth"
+      }
+    ]
+  },
   "exports": {
     ".": {
       "types": "./dist/types.d.mts",
@@ -32,7 +40,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "prepack": "nuxt-module-build build",
@@ -59,16 +68,15 @@
     }
   },
   "dependencies": {
+    "@better-auth/cli": "^1.5.0-beta.3",
     "@nuxt/kit": "^4.2.2",
     "defu": "^6.1.4",
     "jiti": "^2.4.2",
     "pathe": "^2.0.3",
-    "pluralize": "^8.0.0",
     "radix3": "^1.1.2"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^4.12.0",
-    "@better-auth/cli": "^1.4.6",
     "@libsql/client": "^0.15.15",
     "@nuxt/devtools": "^3.1.1",
     "@nuxt/devtools-kit": "^3.1.1",
@@ -78,8 +86,7 @@
     "@nuxthub/core": "^0.10.3",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "latest",
-    "@types/pluralize": "^0.0.33",
-    "better-auth": "^1.4.7",
+    "better-auth": "^1.5.0-beta.3",
     "better-sqlite3": "^11.9.1",
     "bumpp": "^10.3.2",
     "changelogen": "^0.6.2",
@@ -87,6 +94,7 @@
     "drizzle-kit": "^0.31.8",
     "drizzle-orm": "^0.38.4",
     "eslint": "^9.39.1",
+    "npm-agentskills": "https://pkg.pr.new/onmax/npm-agentskills@394499e",
     "nuxt": "^4.2.2",
     "tinyexec": "^1.0.2",
     "typescript": "~5.9.3",

package/skills/nuxt-better-auth/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: nuxt-better-auth
+description: Use when implementing auth in Nuxt apps with @onmax/nuxt-better-auth - provides useUserSession composable, server auth helpers, route protection, and Better Auth plugins integration.
+license: MIT
+---
+
+# Nuxt Better Auth
+
+Authentication module for Nuxt 4+ built on [Better Auth](https://www.better-auth.com/). Provides composables, server utilities, and route protection.
+
+> **Alpha Status**: This module is currently in alpha (v0.0.2-alpha.12) and not recommended for production use. APIs may change.
+
+## When to Use
+
+- Installing/configuring `@onmax/nuxt-better-auth`
+- Implementing login/signup/signout flows
+- Protecting routes (client and server)
+- Accessing user session in API routes
+- Integrating Better Auth plugins (admin, passkey, 2FA)
+- Setting up database with NuxtHub
+- Using clientOnly mode for external auth backends
+
+**For Nuxt patterns:** use `nuxt` skill
+**For NuxtHub database:** use `nuxthub` skill
+
+## Available Guidance
+
+| File                                                                 | Topics                                                                 |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **[references/installation.md](references/installation.md)**         | Module setup, env vars, config files                                   |
+| **[references/client-auth.md](references/client-auth.md)**           | useUserSession, signIn/signUp/signOut, BetterAuthState, safe redirects |
+| **[references/server-auth.md](references/server-auth.md)**           | serverAuth, getUserSession, requireUserSession                         |
+| **[references/route-protection.md](references/route-protection.md)** | routeRules, definePageMeta, middleware                                 |
+| **[references/plugins.md](references/plugins.md)**                   | Better Auth plugins (admin, passkey, 2FA)                              |
+| **[references/database.md](references/database.md)**                 | NuxtHub integration, Drizzle schema                                    |
+| **[references/client-only.md](references/client-only.md)**           | External auth backend, clientOnly mode, CORS                           |
+| **[references/types.md](references/types.md)**                       | AuthUser, AuthSession, type augmentation                               |
+
+## Usage Pattern
+
+**Load based on context:**
+
+- Installing module? → [references/installation.md](references/installation.md)
+- Login/signup forms? → [references/client-auth.md](references/client-auth.md)
+- API route protection? → [references/server-auth.md](references/server-auth.md)
+- Route rules/page meta? → [references/route-protection.md](references/route-protection.md)
+- Using plugins? → [references/plugins.md](references/plugins.md)
+- Database setup? → [references/database.md](references/database.md)
+- External auth backend? → [references/client-only.md](references/client-only.md)
+- TypeScript types? → [references/types.md](references/types.md)
+
+**DO NOT read all files at once.** Load based on context.
+
+## Key Concepts
+
+| Concept                | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `useUserSession()`     | Client composable - user, session, loggedIn, signIn/Out methods |
+| `requireUserSession()` | Server helper - throws 401/403 if not authenticated             |
+| `auth` route mode      | `'user'`, `'guest'`, `{ user: {...} }`, or `false`              |
+| `serverAuth()`         | Get Better Auth instance in server routes                       |
+
+## Quick Reference
+
+```ts
+// Client: useUserSession()
+const { user, loggedIn, signIn, signOut } = useUserSession()
+await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
+```
+
+```ts
+// Server: requireUserSession()
+const { user } = await requireUserSession(event, { user: { role: 'admin' } })
+```
+
+```ts
+// nuxt.config.ts: Route protection
+routeRules: {
+  '/admin/**': { auth: { user: { role: 'admin' } } },
+  '/login': { auth: 'guest' },
+  '/app/**': { auth: 'user' }
+}
+```
+
+## Resources
+
+- [Module Docs](https://github.com/onmax/nuxt-better-auth)
+- [Better Auth Docs](https://www.better-auth.com/)
+
+---
+
+_Token efficiency: Main skill ~300 tokens, each sub-file ~800-1200 tokens_