refactor(core): finalize no-convex db dx

README.md

@@ -22,6 +22,11 @@
 
 **[nuxt-better-auth.onmax.me](https://nuxt-better-auth.onmax.me/)**
 
+## Alpha Migration Notes
+
+- `auth.database.*` module options are removed. This now fails fast during module setup.
+- Configure Better Auth's `database` directly in `server/auth.config.ts`, or use a module that registers `better-auth:database:providers`.
+
 ## License
 
 MIT

docs/app/composables/useSidebarConfig.ts

@@ -60,7 +60,6 @@ export function useSidebarConfig() {
         { title: 'NuxtHub', href: '/integrations/nuxthub', icon: 'i-simple-icons-nuxtdotjs' },
         { title: 'DevTools', href: '/integrations/devtools', icon: 'i-solar-tuning-square-bold' },
         { title: 'i18n', href: '/integrations/i18n', icon: 'i-lucide-languages' },
-        { title: 'Convex', href: '/integrations/convex', icon: 'i-custom-convex' },
       ],
     },
     {

docs/content/1.getting-started/2.configuration.md

@@ -60,22 +60,6 @@ export default defineNuxtConfig({
     **Requirement**: Requires [NuxtHub Integration](/integrations/nuxthub) with `hub: { kv: true }`.
   ::
 
-  ::field{name="database.provider" type="'none' | 'nuxthub' | 'convex'"}
-    Default: auto (`'nuxthub'` when `hub.db` is configured, otherwise `'none'`)
-
-    Select the database backend used by Better Auth.
-    - `'none'`: No DB adapter
-    - `'nuxthub'`: Use `@nuxthub/core` database
-    - `'convex'`: Use Convex HTTP adapter (requires `nuxt-convex`)
-  ::
-
-  ::field{name="database.convexUrl" type="string"}
-    Default: auto-detected
-
-    Optional Convex URL override when `database.provider = 'convex'`.
-    Priority: `auth.database.convexUrl` → `convex.url` → `runtimeConfig.public.convex.url` → `CONVEX_URL` → `NUXT_PUBLIC_CONVEX_URL`
-  ::
-
   ::field{name="schema.usePlural" type="boolean"}
     Default: `false`
 
@@ -89,6 +73,45 @@ export default defineNuxtConfig({
   ::
 ::
 
+## Removed Module Database Options
+
+`auth.database.*` options were removed and now fail fast at module setup.
+
+Removed keys:
+- `auth.database.provider`
+- `auth.database.convexUrl`
+
+::warning
+This is a hard removal in the current alpha. The module throws an error when any `auth.database.*` option is configured.
+::
+
+Before (removed):
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  auth: {
+    database: {
+      provider: 'nuxthub',
+      convexUrl: 'https://example.convex.cloud',
+    },
+  },
+})
+```
+
+After (supported):
+
+```ts [server/auth.config.ts]
+import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { db, schema } from '@nuxthub/db'
+
+export default defineServerAuth({
+  database: drizzleAdapter(db, { provider: 'sqlite', schema }),
+})
+```
+
+Or register a provider module via `better-auth:database:providers`.
+
 ## Server Configuration
 
 Define your authentication logic in `server/auth.config.ts`, including plugins, providers, and settings.
@@ -127,16 +150,34 @@ import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
 export default defineServerAuth((ctx) => ({
   emailAndPassword: { enabled: true },
 
-  // Access the database connection via ctx.db when using NuxtHub
-  // Example: pass ctx.db to your own plugin/helper.
-  // Do not set `database` here - the module injects it from `auth.database.provider`.
+  // Access the auto-injected NuxtHub database connection when available
+  // (undefined when no module DB provider is active).
   appName: ctx.runtimeConfig.public.siteUrl ? 'Better Auth App' : 'Better Auth',
 
   // Access runtime config if needed
   // someValue: ctx.runtimeConfig.customKey
 }))
 ```
 
+### Configure Better Auth Database Manually
+
+When you need a custom adapter (or want full control), set Better Auth's native `database` option in `server/auth.config.ts`.
+
+```ts [server/auth.config.ts]
+import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { db, schema } from '@nuxthub/db'
+
+export default defineServerAuth({
+  database: drizzleAdapter(db, { provider: 'sqlite', schema }),
+  emailAndPassword: { enabled: true },
+})
+```
+
+::note
+If `database` is set in `defineServerAuth`, it takes precedence over module auto-detected providers.
+::
+
 ## Base URL Configuration
 
 The module resolves `siteUrl` using this priority:
@@ -200,6 +241,22 @@ export default defineNuxtModule({
 })
 ```
 
+Register a database provider from another Nuxt module:
+
+```ts
+export default defineNuxtModule({
+  setup(_options, nuxt) {
+    nuxt.hook('better-auth:database:providers', (providers) => {
+      providers.myProvider = {
+        priority: 200,
+        isEnabled: () => true,
+        buildDatabaseCode: () => 'export function createDatabase() { return undefined }\nexport const db = undefined',
+      }
+    })
+  },
+})
+```
+
 Access sessions from server handlers:
 
 ```ts

docs/content/5.api/1.composables.md

@@ -117,12 +117,16 @@ await fetchSession({
 
 #### `updateUser`
 
-Optimistically updates the local user object.
+Updates the user on the server and optimistically patches local state. Local state reverts if the server call fails.
 
 ```ts
-updateUser({ name: 'New Name' })
+await updateUser({ name: 'New Name' })
 ```
 
+::note
+During SSR, `updateUser` only patches local state since no client is available.
+::
+
 ::tip
 **Reactivity**: `user` and `session` are global states using `useState`. Changes in one component are instantly reflected everywhere.
 ::

package.json

@@ -26,10 +26,6 @@
     "./config": {
       "types": "./dist/runtime/config.d.ts",
       "import": "./dist/runtime/config.js"
-    },
-    "./adapters/convex": {
-      "types": "./dist/runtime/adapters/convex.d.ts",
-      "import": "./dist/runtime/adapters/convex.js"
     }
   },
   "main": "./dist/module.mjs",
@@ -40,9 +36,6 @@
       ],
       "config": [
         "./dist/runtime/config.d.ts"
-      ],
-      "adapters/convex": [
-        "./dist/runtime/adapters/convex.d.ts"
       ]
     }
   },
@@ -67,15 +60,11 @@
   },
   "peerDependencies": {
     "@nuxthub/core": ">=0.10.5",
-    "better-auth": ">=1.0.0",
-    "convex": ">=1.25.0"
+    "better-auth": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "@nuxthub/core": {
       "optional": true
-    },
-    "convex": {
-      "optional": true
     }
   },
   "dependencies": {