init: nuxt better auth module

Author: onmax

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_size = 2
+indent_style = space
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - run: npm i -g --force corepack@latest && corepack enable
+
+      - name: Install dependencies
+        run: npx nypm@latest i
+
+      - name: Lint
+        run: npm run lint
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - run: npm i -g --force corepack@latest && corepack enable
+
+      - name: Install dependencies
+        run: npx nypm@latest i
+
+      - name: Playground prepare
+        run: npm run dev:prepare
+
+      - name: Test
+        run: npm run test

.gitignore

@@ -0,0 +1,56 @@
+# Dependencies
+node_modules
+
+# Logs
+*.log*
+
+# Temp directories
+.temp
+.tmp
+.cache
+
+# Yarn
+**/.yarn/cache
+**/.yarn/*state*
+
+# Generated dirs
+dist
+
+# Nuxt
+.nuxt
+.output
+.data
+.vercel_build_output
+.build-*
+.netlify
+
+# Env
+.env
+
+# Testing
+reports
+coverage
+*.lcov
+.nyc_output
+
+# VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Intellij idea
+*.iml
+.idea
+
+# OSX
+.DS_Store
+.AppleDouble
+.LSOverride
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk

.npmrc

@@ -0,0 +1 @@
+enable-pre-post-scripts=true

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "eslint.experimental.useFlatConfig": true
+}

README.md

@@ -0,0 +1,171 @@
+# Nuxt Better Auth
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Nuxt module for [Better Auth](https://better-auth.com) integration with route protection, session management, and role-based access.
+
+## Features
+
+- Route Protection - Declarative access rules via `routeRules`
+- Session Management - Server and client plugins that sync auth state
+- Role-Based Access - Support for `admin`, `user`, and custom roles
+- Tier Gating - Generic tier system for subscription/premium features
+- Auto-Imports - `useUserSession`, `usePageAccess`, `requireUserSession`, `getUserSession`
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pnpm add nuxt-better-auth better-auth drizzle-orm
+```
+
+### 2. Create Server Config
+
+Create `server/auth.config.ts`:
+
+```ts
+import { admin } from 'better-auth/plugins'
+import { defineServerAuth } from 'nuxt-better-auth'
+
+export default defineServerAuth(({ runtimeConfig, db }) => ({
+  appName: 'My App',
+  plugins: [admin()],
+  emailAndPassword: { enabled: true },
+}))
+```
+
+### 3. Create Client Config
+
+Create `app/auth.client.ts`:
+
+```ts
+import { adminClient } from 'better-auth/client/plugins'
+import { createAuthClient } from 'better-auth/vue'
+
+export function createAppAuthClient(baseURL: string) {
+  return createAuthClient({
+    baseURL,
+    plugins: [adminClient()],
+  })
+}
+
+export type AppAuthClient = ReturnType<typeof createAppAuthClient>
+```
+
+### 4. Add Type Extensions
+
+Create `shared/types/auth.d.ts`:
+
+```ts
+import '#nuxt-better-auth'
+
+declare module '#nuxt-better-auth' {
+  interface AuthUser {
+    role?: string | null
+    banned?: boolean | null
+  }
+}
+```
+
+### 5. Configure Nuxt
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-better-auth'],
+
+  runtimeConfig: {
+    betterAuthSecret: '', // BETTER_AUTH_SECRET env var
+    public: { siteUrl: 'http://localhost:3000' },
+  },
+
+  routeRules: {
+    '/app/**': { auth: 'user' },
+    '/admin/**': { auth: 'user', requiresAdmin: true },
+    '/login': { auth: 'guest' },
+  },
+})
+```
+
+### 6. Setup Database
+
+Set the global database instance in a server plugin:
+
+```ts
+// server/plugins/db.ts
+export default defineNitroPlugin(() => {
+  ;(globalThis as any).__nuxt_better_auth_db = yourDrizzleInstance
+})
+```
+
+## Route Rules
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `auth` | `boolean \| 'guest' \| 'user'` | Auth requirement |
+| `role` | `string \| string[]` | Required role(s) |
+| `requiresAdmin` | `boolean` | Shorthand for `role: 'admin'` |
+| `tier` | `string \| string[]` | Required tier |
+
+## Composables
+
+### `useUserSession()`
+
+```ts
+const { user, session, loggedIn, ready, client, signIn, signUp, signOut, fetchSession, updateUser } = useUserSession()
+```
+
+### `usePageAccess()`
+
+```ts
+const { hasAccess, showPaywall, paywallConfig } = usePageAccess()
+```
+
+## Server Utils
+
+```ts
+// Require auth
+const { user, session } = await requireUserSession(event)
+
+// Require admin
+const { user } = await requireUserSession(event, { role: 'admin' })
+
+// Optional session
+const session = await getUserSession(event)
+```
+
+## Module Aliases
+
+| Alias | Points To |
+|-------|-----------|
+| `#auth/server` | `server/auth.config.ts` |
+| `#auth/client` | `app/auth.client.ts` |
+| `#nuxt-better-auth` | Module type augmentation |
+
+## Development
+
+```bash
+pnpm install
+pnpm dev:prepare
+pnpm dev
+```
+
+## License
+
+MIT
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-better-auth/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-better-auth
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-better-auth.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/nuxt-better-auth
+
+[license-src]: https://img.shields.io/npm/l/nuxt-better-auth.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-better-auth
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

eslint.config.mjs

@@ -0,0 +1,20 @@
+// @ts-check
+import { createConfigForNuxt } from '@nuxt/eslint-config/flat'
+
+// Run `npx @eslint/config-inspector` to inspect the resolved config interactively
+export default createConfigForNuxt({
+  features: {
+    // Rules for module authors
+    tooling: true,
+    // Rules for formatting
+    stylistic: true,
+  },
+  dirs: {
+    src: [
+      './playground',
+    ],
+  },
+})
+  .append(
+    // your custom flat config here...
+  )

package.json

@@ -0,0 +1,53 @@
+{
+  "name": "nuxt-better-auth",
+  "version": "0.1.0",
+  "description": "Nuxt module for Better Auth integration with route protection, session management, and role-based access",
+  "repository": "your-org/nuxt-better-auth",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": { "types": "./dist/types.d.mts", "import": "./dist/module.mjs" }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": { "*": { ".": ["./dist/types.d.mts"] } },
+  "files": ["dist"],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "pnpm dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxi prepare playground",
+    "release": "pnpm lint && pnpm test && pnpm prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.2.2",
+    "defu": "^6.1.4",
+    "radix3": "^1.1.2"
+  },
+  "peerDependencies": {
+    "better-auth": ">=1.0.0",
+    "drizzle-orm": ">=0.30.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/eslint-config": "^1.11.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.2.2",
+    "@nuxt/test-utils": "^3.21.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "latest",
+    "better-auth": "^1.2.8",
+    "better-sqlite3": "^11.9.1",
+    "changelogen": "^0.6.2",
+    "consola": "^3.4.2",
+    "drizzle-orm": "^0.38.4",
+    "eslint": "^9.39.1",
+    "nuxt": "^4.2.2",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.15",
+    "vue-tsc": "^3.1.7"
+  }
+}