better-auth-nuxt 0.0.6 → 0.0.8

package/README.md

@@ -5,7 +5,7 @@
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-My new Nuxt module for doing amazing things.
+A Nuxt module for simple, flexible authentication in your Nuxt applications.
 
 - [✨  Release Notes](/CHANGELOG.md)
 <!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/my-module?file=playground%2Fapp.vue) -->
@@ -13,49 +13,252 @@ My new Nuxt module for doing amazing things.
 
 ## Features
 
-<!-- Highlight some of the features your module provide here -->
-- ⛰ &nbsp;Foo
-- 🚠 &nbsp;Bar
-- 🌲 &nbsp;Baz
+- ⚙️ &nbsp;Auto-scanning of client and server configs for end-to-end TS support
+- 🚀 &nbsp;Built-in authentication middleware
+- 🔑 &nbsp;Multiple authentication strategies (username, email, ...)
+- 🛡️ &nbsp;Role-based access control
+- 🔄 &nbsp;Session management
+- 🔒 &nbsp;Redirect handling for authenticated/unauthenticated users
 
 ## Quick Setup
 
-Install the module to your Nuxt application with one command:
+1. Install the module:
 
 ```bash
-npx nuxi module add my-module
+# Using npm
+npm install better-auth-nuxt better-auth
+
+# Using yarn
+yarn add better-auth-nuxt better-auth
+
+# Using pnpm
+pnpm add better-auth-nuxt better-auth
+```
+
+2. Add the module to your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['better-auth-nuxt'],
+
+  betterAuth: {
+    // Configure auth endpoints (default: '/api/auth/**')
+    endpoint: '/api/auth/**',
+
+    // Configure redirect paths
+    redirectOptions: {
+      redirectGuestTo: '/auth/login',
+      redirectUserTo: '/',
+      redirectUnauthorizedTo: '/401',
+    },
+
+    // Configure client and server options
+    options: {
+      client: {
+        basePath: '/api/auth',
+        // Optional: baseURL, disableDefaultFetchPlugins
+      },
+      server: {
+        appName: 'My Nuxt App',
+        // Optional: baseURL, basePath, secret
+      },
+    },
+  }
+})
+```
+
+3. Use the module in your pages:
+
+```vue
+<script setup>
+// Protect route for authenticated users only
+definePageMeta({
+  auth: {
+    only: 'user',
+  }
+})
+
+// Access auth functionality
+const { loggedIn, user, signOut } = useUserSession()
+</script>
+
+<template>
+  <div v-if="loggedIn">
+    <h1>Welcome, {{ user?.name }}</h1>
+    <button @click="signOut()">Sign Out</button>
+  </div>
+</template>
+```
+
+## Module Options
+
+### Auth Configuration
+
+```ts
+interface ModuleOptions {
+  // Auth endpoint
+  endpoint: string
+
+  // Patterns to match auth configuration files
+  serverConfigs?: string[]
+  clientConfigs?: string[]
+
+  // Client and server options
+  options: {
+    client?: ModuleClientOptions
+    server?: ModuleServerOptions
+  }
+
+  // Redirect options
+  redirectOptions: {
+    redirectUserTo?: string
+    redirectGuestTo?: string
+    redirectUnauthorizedTo?: string
+  }
+}
+```
+
+### Server Options
+
+```ts
+interface ModuleServerOptions {
+  appName?: string   // Application name
+  baseURL?: string   // Base URL for the auth API
+  basePath?: string  // Base path for the auth API
+  secret?: string    // Secret for JWT/session encryption
+}
+```
+
+### Client Options
+
+```ts
+interface ModuleClientOptions {
+  baseURL?: string                  // Base URL for the auth API
+  basePath?: string                 // Base path for the auth API
+  disableDefaultFetchPlugins?: boolean // Disable default fetch plugins
+}
+```
+
+## API Reference
+
+### Client-side Composables
+
+#### `useUserSession()`
+
+Provides access to the authenticated user session and auth methods.
+
+```ts
+const {
+  // State
+  loggedIn,         // Ref<boolean> - Is the user logged in
+  user,             // Ref<User> - Current user data
+  session,          // Ref<Session> - Current session data
+
+  // Methods
+  fetchSession,     // () => Promise<void> - Fetch current session
+  signIn: {
+    username,       // (credentials) => Promise<void> - Sign in with username
+    email,          // (credentials) => Promise<void> - Sign in with email
+  },
+  signUp: {
+    username,       // (userData) => Promise<void> - Register with username
+    email,          // (userData) => Promise<void> - Register with email
+  },
+  signOut,          // (options?) => Promise<void> - Sign out the user
+
+  // Configuration
+  options,          // Auth configuration options
+} = useUserSession()
+```
+
+### Server-side Utilities
+
+#### `useAuth()`
+
+Access the auth instance on the server.
+
+```ts
+// In API route handlers:
+const auth = useAuth()
 ```
 
-That's it! You can now use My Module in your Nuxt app ✨
+### Route Protection
+
+Use the `auth` meta property to protect routes:
+
+```ts
+definePageMeta({
+  auth: {
+    // Only allow specific roles
+    only: 'user' | 'admin' | 'guest' | ['user', 'admin'],
+
+    // Custom redirect paths (override global config)
+    redirectUserTo: '/dashboard',
+    redirectGuestTo: '/login',
+    redirectUnauthorizedTo: '/unauthorized',
+  }
+})
+```
+
+## Configuration Files
+
+You can create configuration files to customize authentication:
+
+### Server Configuration
+
+Create a `*.better-auth.ts` file to configure server-side auth:
 
+```ts
+// server/my-auth.better-auth.ts
+import type { BetterAuthOptions } from 'better-auth'
+
+export default {
+  // Custom server-side auth configuration
+} satisfies BetterAuthOptions
+```
+
+### Client Configuration
+
+Create a `*.better-auth-client.ts` file to configure client-side auth:
+
+```ts
+// app/my-auth.better-auth-client.ts
+import type { ClientOptions } from 'better-auth'
+
+export default {
+  // Custom client-side auth configuration
+} satisfies ClientOptions
+```
+
+> **Note**: After adding or modifying configuration files, run `pnpm nuxt prepare` to ensure your changes are properly recognized by Nuxt.
 
 ## Contribution
 
 <details>
   <summary>Local development</summary>
-  
+
   ```bash
   # Install dependencies
-  npm install
-  
+  pnpm install
+
   # Generate type stubs
-  npm run dev:prepare
-  
+  pnpm dev:prepare
+
   # Develop with the playground
-  npm run dev
-  
+  pnpm dev
+
   # Build the playground
-  npm run dev:build
-  
+  pnpm dev:build
+
   # Run ESLint
-  npm run lint
-  
+  pnpm lint
+
   # Run Vitest
-  npm run test
-  npm run test:watch
-  
+  pnpm test
+  pnpm test:watch
+
   # Release new version
-  npm run release
+  pnpm release
   ```
 
 </details>

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "better-auth",
   "configKey": "betterAuth",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "builder": {
     "@nuxt/module-builder": "1.0.1",
     "unbuild": "3.5.0"

package/dist/runtime/server/handler.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, any>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Response>>;
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-auth-nuxt",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Better Auth Nuxt Module",
   "repository": "productdevbook/better-auth-nuxt",
   "license": "MIT",
@@ -22,35 +22,23 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "prepack": "nuxt-module-build build",
-    "dev": "nuxi dev playground",
-    "dev:build": "nuxi build playground",
-    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
-    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "test": "vitest run",
-    "test:watch": "vitest watch",
-    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
-  },
   "peerDependencies": {
     "better-auth": ">=1.2.7"
   },
   "dependencies": {
     "@fastify/deepmerge": "^3.1.0",
-    "@nuxt/kit": "^3.16.2",
+    "@nuxt/kit": "^3.17.0",
     "defu": "^6.1.4",
     "ohash": "^2.0.11",
     "pathe": "^2.0.3",
     "scule": "^1.3.0",
-    "tinyglobby": "^0.2.12"
+    "tinyglobby": "^0.2.13"
   },
   "devDependencies": {
     "@nuxt/devtools": "^2.4.0",
     "@nuxt/eslint-config": "^1.3.0",
     "@nuxt/module-builder": "^1.0.1",
-    "@nuxt/schema": "^3.16.2",
+    "@nuxt/schema": "^3.17.0",
     "@nuxt/test-utils": "^3.17.2",
     "@tailwindcss/vite": "^4.1.4",
     "@types/better-sqlite3": "^7.6.13",
@@ -58,11 +46,21 @@
     "better-auth": "^1.2.7",
     "better-sqlite3": "^11.9.1",
     "changelogen": "^0.6.1",
-    "eslint": "^9.24.0",
-    "nuxt": "^3.16.2",
+    "eslint": "^9.25.1",
+    "nuxt": "^3.17.0",
     "typescript": "~5.8.3",
-    "vitest": "^3.1.1",
-    "vue-tsc": "^2.2.8"
+    "vitest": "^3.1.2",
+    "vue-tsc": "^2.2.10"
   },
-  "packageManager": "pnpm@10.8.1"
-}
+  "scripts": {
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && pnpm publish --no-git-checks --access public && git push --follow-tags",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  }
+}