create-nuxt-base 1.0.2 → 1.1.0

package/AUTH.md

@@ -0,0 +1,289 @@
+# Better Auth Integration
+
+This document describes the Better Auth integration in the nuxt-base-starter template.
+
+## Overview
+
+The template uses [Better Auth](https://www.better-auth.com/) for authentication with the following features:
+
+| Feature               | Status | Description                            |
+|-----------------------|--------|----------------------------------------|
+| Email & Password      | ✅      | Standard email/password authentication |
+| Two-Factor Auth (2FA) | ✅      | TOTP-based 2FA with backup codes       |
+| Passkey (WebAuthn)    | ✅      | Passwordless authentication            |
+| Session Management    | ✅      | Cookie-based sessions with SSR support |
+| Password Hashing      | ✅      | Client-side SHA256 hashing             |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        FRONTEND (Nuxt)                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐    ┌─────────────────┐                     │
+│  │   auth-client   │───▶│  useBetterAuth  │                     │
+│  │     (lib/)      │    │  (composable)   │                     │
+│  └────────┬────────┘    └────────┬────────┘                     │
+│           │                      │                              │
+│           │  SHA256 Hashing      │  Cookie-based State          │
+│           │  Plugin Config       │  Session Validation          │
+│           │                      │                              │
+└───────────┼──────────────────────┼──────────────────────────────┘
+            │                      │
+            ▼                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      BACKEND (nest-server)                      │
+├─────────────────────────────────────────────────────────────────┤
+│  /iam/sign-in/email          /iam/session                       │
+│  /iam/sign-up/email          /iam/sign-out                      │
+│  /iam/passkey/*              /iam/two-factor/*                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Files
+
+| File                                 | Purpose                          |
+|--------------------------------------|----------------------------------|
+| `app/lib/auth-client.ts`             | Better Auth client configuration |
+| `app/composables/use-better-auth.ts` | Auth state management composable |
+| `app/pages/auth/login.vue`           | Login page                       |
+| `app/pages/auth/register.vue`        | Registration page                |
+| `app/pages/auth/2fa.vue`             | Two-factor authentication page   |
+| `app/pages/auth/forgot-password.vue` | Password reset request           |
+| `app/pages/auth/reset-password.vue`  | Password reset form              |
+| `app/utils/crypto.ts`                | SHA256 hashing utility           |
+
+## Usage
+
+### Basic Authentication
+
+```typescript
+// In a Vue component
+const { signIn, signUp, signOut, user, isAuthenticated } = useBetterAuth();
+
+// Sign in
+const result = await signIn.email({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// Sign up
+const result = await signUp.email({
+  email: 'user@example.com',
+  name: 'John Doe',
+  password: 'password123',
+});
+
+// Sign out
+await signOut();
+
+// Check auth state
+if (isAuthenticated.value) {
+  console.log('User:', user.value);
+}
+```
+
+### Passkey Authentication
+
+```typescript
+import { authClient } from '~/lib/auth-client';
+
+// Sign in with passkey
+const result = await authClient.signIn.passkey();
+
+if (result.error) {
+  console.error('Passkey login failed:', result.error.message);
+} else {
+  // Validate session to get user data (passkey returns session only)
+  await validateSession();
+  navigateTo('/app');
+}
+```
+
+### Two-Factor Authentication
+
+```typescript
+import { authClient } from '~/lib/auth-client';
+
+// Verify TOTP code
+const result = await authClient.twoFactor.verifyTotp({
+  code: '123456',
+  trustDevice: true,
+});
+
+// Verify backup code
+const result = await authClient.twoFactor.verifyBackupCode({
+  code: 'backup-code-here',
+});
+```
+
+### Session Validation
+
+```typescript
+const { validateSession, user } = useBetterAuth();
+
+// On app init, validate the session
+const isValid = await validateSession();
+
+if (isValid) {
+  console.log('Session valid, user:', user.value);
+} else {
+  console.log('No valid session');
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+```env
+# API URL (required)
+API_URL=http://localhost:3000
+
+# Or via Vite
+VITE_API_URL=http://localhost:3000
+```
+
+### Custom Configuration
+
+```typescript
+import { createBetterAuthClient } from '~/lib/auth-client';
+
+// Create a custom client
+const customClient = createBetterAuthClient({
+  baseURL: 'https://api.example.com',
+  basePath: '/auth',  // Default: '/iam'
+  twoFactorRedirectPath: '/login/2fa',  // Default: '/auth/2fa'
+  enableAdmin: false,
+  enableTwoFactor: true,
+  enablePasskey: true,
+});
+```
+
+## Security
+
+### Password Hashing
+
+Passwords are hashed with SHA256 on the client-side before transmission:
+
+```typescript
+// This happens automatically in auth-client.ts
+const hashedPassword = await sha256(plainPassword);
+// Result: 64-character hex string
+```
+
+**Why client-side hashing?**
+1. Prevents plain text passwords in network logs
+2. Works with nest-server's `normalizePasswordForIam()` which detects SHA256 hashes
+3. Server re-hashes with bcrypt for storage
+
+### Cookie-Based Sessions
+
+Sessions are stored in cookies for SSR compatibility:
+
+| Cookie                      | Purpose                    |
+|-----------------------------|----------------------------|
+| `auth-state`                | User data (SSR-compatible) |
+| `token`                     | Session token              |
+| `better-auth.session_token` | Better Auth native cookie  |
+
+### Cross-Origin Requests
+
+The client is configured with `credentials: 'include'` for cross-origin cookie handling:
+
+```typescript
+// In auth-client.ts
+fetchOptions: {
+  credentials: 'include',
+}
+```
+
+**Backend CORS Configuration:**
+```typescript
+// In nest-server config
+cors: {
+  origin: 'http://localhost:3001',  // Not '*'
+  credentials: true,
+}
+```
+
+## Better Auth Endpoints
+
+The following endpoints are provided by the nest-server backend:
+
+### Authentication
+
+| Endpoint             | Method | Description                 |
+|----------------------|--------|-----------------------------|
+| `/iam/sign-in/email` | POST   | Email/password sign in      |
+| `/iam/sign-up/email` | POST   | Email/password registration |
+| `/iam/sign-out`      | POST   | Sign out                    |
+| `/iam/session`       | GET    | Get current session         |
+
+### Passkey (WebAuthn)
+
+| Endpoint                                     | Method | Description              |
+|----------------------------------------------|--------|--------------------------|
+| `/iam/passkey/generate-register-options`     | GET    | Get registration options |
+| `/iam/passkey/verify-registration`           | POST   | Verify registration      |
+| `/iam/passkey/generate-authenticate-options` | GET    | Get auth options         |
+| `/iam/passkey/verify-authentication`         | POST   | Verify authentication    |
+| `/iam/passkey/list-user-passkeys`            | GET    | List user's passkeys     |
+| `/iam/passkey/delete-passkey`                | POST   | Delete a passkey         |
+
+### Two-Factor Authentication
+
+| Endpoint                             | Method | Description        |
+|--------------------------------------|--------|--------------------|
+| `/iam/two-factor/enable`             | POST   | Enable 2FA         |
+| `/iam/two-factor/disable`            | POST   | Disable 2FA        |
+| `/iam/two-factor/verify-totp`        | POST   | Verify TOTP code   |
+| `/iam/two-factor/verify-backup-code` | POST   | Verify backup code |
+
+## Troubleshooting
+
+### "Passkey not found" Error
+
+1. Ensure the user has registered a passkey first
+2. Check that cookies are being sent (`credentials: 'include'`)
+3. Verify CORS is configured correctly on the backend
+
+### 2FA Redirect Not Working
+
+Ensure the 2FA redirect is handled in the login page:
+
+```typescript
+// Check for 2FA redirect in login response
+if (result.data?.twoFactorRedirect) {
+  await navigateTo('/auth/2fa');
+  return;
+}
+```
+
+### Session Not Persisting After Passkey Login
+
+The passkey response only contains the session, not the user. Call `validateSession()`:
+
+```typescript
+if (result.data?.session) {
+  await validateSession();  // Fetches user data
+}
+```
+
+### Form Not Submitting (Nuxt UI)
+
+Ensure UForm has the `:state` binding:
+
+```vue
+<UForm :schema="schema" :state="formState" @submit="onSubmit">
+  <UInput v-model="formState.field" />
+</UForm>
+```
+
+## References
+
+- [Better Auth Documentation](https://www.better-auth.com/docs)
+- [Better Auth Passkey Plugin](https://www.better-auth.com/docs/plugins/passkey)
+- [Better Auth Two-Factor Plugin](https://www.better-auth.com/docs/plugins/two-factor)
+- [nest-server Better Auth Integration](https://github.com/lenneTech/nest-server)

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.1.0](https://github.com/lenneTech/nuxt-base-starter/compare/v1.0.3...v1.1.0) (2026-01-20)
+
+
+### Features
+
+* add complete Better-Auth integration with Passkey support and comprehensive documentation ([e0d470c](https://github.com/lenneTech/nuxt-base-starter/commit/e0d470c8229c37bed2948d929676620f344f4878))
+
+## [1.2.0](https://github.com/lenneTech/nuxt-base-starter/compare/v1.0.3...v1.2.0) (2026-01-20)
+
+
+### Features
+
+* add complete Better-Auth integration with Passkey support and comprehensive documentation ([70fbec1](https://github.com/lenneTech/nuxt-base-starter/commit/70fbec14e38673c5185195fe05f0cd82bf72a800))
+
+## [1.1.0](https://github.com/lenneTech/nuxt-base-starter/compare/v1.0.3...v1.1.0) (2026-01-20)
+
+### [1.0.3](https://github.com/lenneTech/nuxt-base-starter/compare/v1.0.2...v1.0.3) (2026-01-12)
+
 ### [1.0.2](https://github.com/lenneTech/nuxt-base-starter/compare/v1.0.1...v1.0.2) (2026-01-12)
 
 

package/README.md

@@ -1,9 +1,144 @@
-# Nuxt Starter
+# create-nuxt-base
 
-This is a starter template to create a Nuxt 3 development environment including Tailwind, Pinia, VueUse, Nuxt Base, Eslint, Cypress with Cucumber, Unit Tests.
+A CLI tool to scaffold a production-ready **Nuxt 4** application with TypeScript, Tailwind CSS v4, NuxtUI v4, and modern tooling.
 
-Just run the following command to create your Nuxt environment:
+## Quick Start
 
 ```bash
 npx create-nuxt-base my-awesome-project
+cd my-awesome-project
+npm run dev
 ```
+
+The development server starts at **http://localhost:3001**
+
+## What's Included
+
+### Core Framework
+
+| Technology   | Version | Description                           |
+|--------------|---------|---------------------------------------|
+| Nuxt         | 4.x     | Vue 3 meta-framework with SSR support |
+| TypeScript   | 5.9.x   | Strict type checking enabled          |
+| Tailwind CSS | 4.x     | Utility-first CSS with Vite plugin    |
+| NuxtUI       | 4.x     | Component library with dark mode      |
+
+### Authentication (Better Auth)
+
+Complete authentication system using [Better Auth](https://www.better-auth.com/):
+
+| Feature            | Description                                           |
+|--------------------|-------------------------------------------------------|
+| Email/Password     | Standard auth with client-side SHA256 hashing         |
+| Two-Factor (2FA)   | TOTP-based 2FA with backup codes                      |
+| Passkey/WebAuthn   | Passwordless authentication (Touch ID, Face ID, etc.) |
+| Password Reset     | Email-based password reset flow                       |
+| Session Management | SSR-compatible cookie-based sessions                  |
+
+Pre-built auth pages: login, register, forgot-password, reset-password, 2fa
+
+📖 **See [AUTH.md](./AUTH.md) for detailed documentation**
+
+### State & Data
+
+| Package               | Purpose                     |
+|-----------------------|-----------------------------|
+| Pinia                 | State management            |
+| VueUse                | Vue composition utilities   |
+| @hey-api/client-fetch | Type-safe API client        |
+| Valibot               | Schema validation for forms |
+
+### SEO & Analytics
+
+- **@nuxtjs/seo** - Sitemap, robots.txt, OG images
+- **@nuxtjs/plausible** - Privacy-friendly analytics
+- **@nuxt/image** - Image optimization with IPX
+
+### Developer Experience
+
+| Tool               | Purpose                            |
+|--------------------|------------------------------------|
+| OxLint             | Fast linting                       |
+| OxFmt              | Code formatting                    |
+| Playwright         | E2E testing                        |
+| @lenne.tech/bug.lt | Bug reporting to Linear (dev only) |
+| dayjs-nuxt         | Date/time handling                 |
+
+### File Upload
+
+- TUS resumable upload support (`tus-js-client`)
+- Pre-built `TusFileUpload.vue` component
+
+### Docker Support
+
+- `Dockerfile.dev` for containerized development
+- Hot reload enabled
+
+## Project Structure
+
+```
+my-project/
+├── app/
+│   ├── assets/css/       # Tailwind CSS
+│   ├── components/       # Vue components (auto-imported)
+│   │   ├── Modal/        # Modal components
+│   │   ├── Transition/   # Transition components
+│   │   └── Upload/       # File upload components
+│   ├── composables/      # Composables (auto-imported)
+│   ├── interfaces/       # TypeScript interfaces
+│   ├── layouts/          # Nuxt layouts
+│   ├── lib/              # Auth client configuration
+│   ├── middleware/       # Route middleware (auth, admin, guest)
+│   ├── pages/            # File-based routing
+│   │   ├── auth/         # Authentication pages
+│   │   └── app/          # Protected app pages
+│   ├── utils/            # Utility functions
+│   └── app.config.ts     # NuxtUI configuration
+├── docs/                 # Dev-only documentation layer
+├── tests/                # Playwright E2E tests
+├── nuxt.config.ts        # Nuxt configuration
+├── openapi-ts.config.ts  # API type generation config
+└── playwright.config.ts  # E2E test configuration
+```
+
+## Available Scripts
+
+| Script                   | Description                            |
+|--------------------------|----------------------------------------|
+| `npm run dev`            | Start development server               |
+| `npm run build`          | Build for production                   |
+| `npm run preview`        | Preview production build               |
+| `npm run generate-types` | Generate TypeScript types from OpenAPI |
+| `npm run test`           | Run Playwright E2E tests               |
+| `npm run lint`           | Run OxLint                             |
+| `npm run format`         | Run OxFmt                              |
+| `npm run check`          | Run lint + format check                |
+| `npm run fix`            | Auto-fix lint + format issues          |
+
+## Environment Variables
+
+Create a `.env` file based on `.env.example`:
+
+```env
+# Required
+SITE_URL=http://localhost:3001
+API_URL=http://localhost:3000
+APP_ENV=development
+NODE_ENV=development
+
+# Optional
+WEB_PUSH_KEY=                # Web push notifications
+LINEAR_API_KEY=              # Bug reporting
+LINEAR_TEAM_NAME=            # Bug reporting
+LINEAR_PROJECT_NAME=         # Bug reporting
+STORAGE_PREFIX=base-dev      # Local storage prefix
+```
+
+## Requirements
+
+- Node.js >= 22
+- npm >= 10
+
+## License
+
+MIT

package/nuxt-base-template/.env.example

@@ -3,9 +3,7 @@ APP_ENV=development
 NODE_ENV=development
 API_URL=http://localhost:3000
 WEB_PUSH_KEY=
-API_SCHEMA=../api/schema.gql
 STORAGE_PREFIX=base-dev
-GENERATE_TYPES=0
 
 LINEAR_API_KEY=
 LINEAR_TEAM_NAME=

package/nuxt-base-template/README.md

@@ -1,6 +1,6 @@
 # Nuxt Base Template
 
-A modern Nuxt 4 SSR starter template with TypeScript, Tailwind CSS v4, and NuxtUI.
+A production-ready Nuxt 4 SSR starter with TypeScript, Tailwind CSS v4, NuxtUI v4, and Better Auth.
 
 ## Requirements
 
@@ -33,6 +33,13 @@ Start the development server on http://localhost:3001
 npm run dev
 ```
 
+### Docker Development
+
+```bash
+docker build -f Dockerfile.dev -t nuxt-app-dev .
+docker run -p 3001:3001 -v $(pwd):/app nuxt-app-dev
+```
+
 ## Production
 
 Build the application for production:
@@ -62,8 +69,8 @@ Run linting and formatting checks before committing:
 ```bash
 npm run check           # Run lint + format check
 npm run fix             # Auto-fix lint + format issues
-npm run lint            # ESLint only
-npm run format          # Prettier format only
+npm run lint            # OxLint only
+npm run format          # OxFmt format only
 ```
 
 ## Testing
@@ -84,33 +91,64 @@ npm run generate-types
 
 ## Tech Stack
 
-- **Framework:** Nuxt 4.1.3 (Vue 3 Composition API)
-- **Language:** TypeScript 5.9.3
-- **Styling:** Tailwind CSS 4.1.14
-- **UI Library:** NuxtUI 4.0.1
-- **State Management:** Pinia
-- **Testing:** Playwright
-- **API Client:** @hey-api/client-fetch
-- **Form Validation:** Valibot
+| Technology | Version | Description |
+|------------|---------|-------------|
+| Nuxt | 4.2.x | Vue 3 meta-framework with SSR |
+| TypeScript | 5.9.x | Strict type checking |
+| Tailwind CSS | 4.1.x | Utility-first CSS (Vite plugin) |
+| NuxtUI | 4.3.x | Component library with dark mode |
+| Pinia | 0.11.x | State management |
+| Better Auth | 1.4.x | Authentication framework |
+| Playwright | 1.57.x | E2E testing |
+| @hey-api/client-fetch | 0.13.x | Type-safe API client |
+| Valibot | 1.2.x | Schema validation |
 
 ## Key Features
 
-- ✅ Full TypeScript support with strict typing
-- ✅ NuxtUI component library with semantic colors
-- ✅ Dark/light mode support
-- ✅ SEO optimization (sitemap, robots.txt, OG images)
-- ✅ Auto-generated API client from OpenAPI schema
-- ✅ E2E testing with Playwright
-- ✅ ESLint + Prettier configuration
-- ✅ Plausible Analytics integration
-- ✅ Image optimization with NuxtImage
-- ✅ Bug reporting to Linear (dev only)
+### Authentication (Better Auth)
+
+- Email/password authentication with client-side SHA256 password hashing
+- Two-factor authentication (2FA/TOTP) with backup codes
+- Passkey/WebAuthn support
+- Password reset flow
+- Pre-built pages: login, register, forgot-password, reset-password, 2fa
+- Route middleware: `auth.global.ts`, `admin.global.ts`, `guest.global.ts`
+
+### UI & Styling
+
+- NuxtUI v4 component library
+- Dark/light mode support
+- Transition components (Fade, Slide, FadeScale)
+- Modal components with `useOverlay` pattern
+
+### SEO & Analytics
+
+- Sitemap generation (`@nuxtjs/seo`)
+- robots.txt configuration
+- OG image generation
+- Plausible Analytics integration
+
+### File Upload
+
+- TUS resumable uploads (`tus-js-client`)
+- Pre-built `TusFileUpload.vue` component
+- Progress tracking and error handling
+
+### Developer Experience
+
+- OxLint for fast linting
+- OxFmt for code formatting
+- Auto-generated API client from OpenAPI
+- Bug reporting to Linear (dev only via `@lenne.tech/bug.lt`)
+- VueUse composition utilities
+- dayjs for date/time handling
 
 ## Environment Variables
 
 Create a `.env` file with the following variables:
 
 ```env
+# Required
 SITE_URL=http://localhost:3001
 API_URL=http://localhost:3000
 APP_ENV=development
@@ -124,7 +162,7 @@ WEB_PUSH_KEY=                # Web push notifications
 LINEAR_API_KEY=              # Bug reporting
 LINEAR_TEAM_NAME=            # Bug reporting
 LINEAR_PROJECT_NAME=         # Bug reporting
-API_SCHEMA=../api/schema.gql # API schema path
+API_SCHEMA=../api/schema.gql # OpenAPI schema path
 STORAGE_PREFIX=base-dev      # Local storage prefix
 ```
 
@@ -132,25 +170,34 @@ STORAGE_PREFIX=base-dev      # Local storage prefix
 
 ```
 app/
-├── assets/          # Tailwind CSS configuration
+├── assets/css/      # Tailwind CSS styles
 ├── components/      # Vue components (auto-imported)
+│   ├── Modal/       # Modal components
+│   ├── Transition/  # Transition animations
+│   └── Upload/      # File upload components
 ├── composables/     # Composables (auto-imported)
-├── interfaces/      # TypeScript interfaces (auto-imported)
-├── layouts/         # Nuxt layouts
+│   ├── use-better-auth.ts   # Auth session helpers
+│   ├── use-file.ts          # File utilities
+│   ├── use-share.ts         # Share API
+│   └── use-tus-upload.ts    # TUS upload logic
+├── interfaces/      # TypeScript interfaces
+├── layouts/         # Nuxt layouts (default, slim)
+├── lib/             # Auth client configuration
+├── middleware/      # Route guards (auth, admin, guest)
 ├── pages/           # File-based routing
+│   ├── auth/        # Authentication pages
+│   └── app/         # Protected app pages
+├── utils/           # Utility functions
 └── app.config.ts    # NuxtUI configuration
 
 docs/                # Dev-only documentation layer
 tests/               # Playwright E2E tests
 ```
 
-## Development Guidelines
-
-For detailed coding standards and architecture information, see [CLAUDE.md](./CLAUDE.md).
-
 ## Documentation
 
 - [Nuxt Documentation](https://nuxt.com/docs)
 - [NuxtUI Documentation](https://ui.nuxt.com)
+- [Better Auth Documentation](https://www.better-auth.com)
 - [Tailwind CSS Documentation](https://tailwindcss.com/docs)
 - [Vue 3 Documentation](https://vuejs.org)

package/nuxt-base-template/app/composables/use-better-auth.ts

@@ -1,25 +1,192 @@
 import { authClient } from '~/lib/auth-client';
 
+/**
+ * User type for Better Auth session
+ */
+interface BetterAuthUser {
+  email: string;
+  emailVerified?: boolean;
+  id: string;
+  name?: string;
+  role?: string;
+  twoFactorEnabled?: boolean;
+}
+
+/**
+ * Stored auth state (persisted in cookie for SSR compatibility)
+ */
+interface StoredAuthState {
+  user: BetterAuthUser | null;
+}
+
+/**
+ * Better Auth composable with client-side state management
+ *
+ * This composable manages auth state using:
+ * 1. Client-side state stored in a cookie (for SSR compatibility)
+ * 2. Better Auth's session endpoint as a validation check
+ *
+ * The state is populated after login and cleared on logout.
+ */
 export function useBetterAuth() {
-  const session = authClient.useSession();
+  // Use useCookie for SSR-compatible persistent state
+  const authState = useCookie<StoredAuthState>('auth-state', {
+    default: () => ({ user: null }),
+    maxAge: 60 * 60 * 24 * 7, // 7 days
+    sameSite: 'lax',
+  });
+
+  // Loading state
+  const isLoading = ref<boolean>(false);
 
-  const user = computed<null | User>(() => (session.value.data?.user as User) ?? null);
+  // Computed properties based on stored state
+  const user = computed<BetterAuthUser | null>(() => authState.value?.user ?? null);
   const isAuthenticated = computed<boolean>(() => !!user.value);
   const isAdmin = computed<boolean>(() => user.value?.role === 'admin');
   const is2FAEnabled = computed<boolean>(() => user.value?.twoFactorEnabled ?? false);
-  const isLoading = computed<boolean>(() => session.value.isPending);
+
+  /**
+   * Set user data after successful login/signup
+   */
+  function setUser(userData: BetterAuthUser | null): void {
+    authState.value = { user: userData };
+  }
+
+  /**
+   * Clear user data on logout
+   */
+  function clearUser(): void {
+    authState.value = { user: null };
+  }
+
+  /**
+   * Validate session with backend (called on app init)
+   * If session is invalid, clear the stored state
+   */
+  async function validateSession(): Promise<boolean> {
+    try {
+      // Try to get session from Better Auth
+      const session = authClient.useSession();
+
+      // Wait for session to load
+      if (session.value.isPending) {
+        await new Promise((resolve) => {
+          const unwatch = watch(
+            () => session.value.isPending,
+            (isPending) => {
+              if (!isPending) {
+                unwatch();
+                resolve(true);
+              }
+            },
+            { immediate: true },
+          );
+        });
+      }
+
+      // If session has user data, update our state
+      if (session.value.data?.user) {
+        setUser(session.value.data.user as BetterAuthUser);
+        return true;
+      }
+
+      // Session not found - check if we have a stored token cookie
+      // If we have auth-state but no session, it might be a mismatch
+      // For now, trust the stored state if token cookie exists
+      const tokenCookie = useCookie('token');
+      if (tokenCookie.value && authState.value?.user) {
+        // We have both token and stored user - trust it
+        return true;
+      }
+
+      // No valid session found - clear state
+      if (authState.value?.user) {
+        clearUser();
+      }
+      return false;
+    } catch (error) {
+      console.debug('Session validation failed:', error);
+      return !!authState.value?.user;
+    }
+  }
+
+  /**
+   * Sign in with email and password
+   */
+  const signIn = {
+    ...authClient.signIn,
+    email: async (params: { email: string; password: string; rememberMe?: boolean }, options?: any) => {
+      isLoading.value = true;
+      try {
+        const result = await authClient.signIn.email(params, options);
+
+        // Check for successful response with user data
+        if (result && 'user' in result && result.user) {
+          setUser(result.user as BetterAuthUser);
+        } else if (result && 'data' in result && result.data?.user) {
+          setUser(result.data.user as BetterAuthUser);
+        }
+
+        return result;
+      } finally {
+        isLoading.value = false;
+      }
+    },
+  };
+
+  /**
+   * Sign up with email and password
+   */
+  const signUp = {
+    ...authClient.signUp,
+    email: async (params: { email: string; name: string; password: string }, options?: any) => {
+      isLoading.value = true;
+      try {
+        const result = await authClient.signUp.email(params, options);
+
+        // Check for successful response with user data
+        if (result && 'user' in result && result.user) {
+          setUser(result.user as BetterAuthUser);
+        } else if (result && 'data' in result && result.data?.user) {
+          setUser(result.data.user as BetterAuthUser);
+        }
+
+        return result;
+      } finally {
+        isLoading.value = false;
+      }
+    },
+  };
+
+  /**
+   * Sign out
+   */
+  const signOut = async (options?: any) => {
+    isLoading.value = true;
+    try {
+      const result = await authClient.signOut(options);
+      // Clear user data on logout
+      clearUser();
+      return result;
+    } finally {
+      isLoading.value = false;
+    }
+  };
 
   return {
+    changePassword: authClient.changePassword,
+    clearUser,
     is2FAEnabled,
     isAdmin,
     isAuthenticated,
-    isLoading,
+    isLoading: computed(() => isLoading.value),
     passkey: authClient.passkey,
-    session,
-    signIn: authClient.signIn,
-    signOut: authClient.signOut,
-    signUp: authClient.signUp,
+    setUser,
+    signIn,
+    signOut,
+    signUp,
     twoFactor: authClient.twoFactor,
     user,
+    validateSession,
   };
 }

package/nuxt-base-template/app/lib/auth-client.ts

@@ -34,102 +34,190 @@ export interface AuthResponse {
   };
 }
 
-// =============================================================================
-// Base Client Configuration
-// =============================================================================
-
-const baseClient = createAuthClient({
-  basePath: '/iam', // IMPORTANT: Must match nest-server betterAuth.basePath, default: '/iam'
-  baseURL: import.meta.env?.VITE_API_URL || process.env.API_URL || 'http://localhost:3000',
-  plugins: [
-    adminClient(),
-    twoFactorClient({
-      onTwoFactorRedirect() {
-        navigateTo('/auth/2fa');
-      },
-    }),
-    passkeyClient(),
-  ],
-});
+/**
+ * Configuration options for the auth client factory
+ * All options have sensible defaults for nest-server compatibility
+ */
+export interface AuthClientConfig {
+  /** API base URL (default: from env or http://localhost:3000) */
+  baseURL?: string;
+  /** Auth API base path (default: '/iam' - must match nest-server betterAuth.basePath) */
+  basePath?: string;
+  /** 2FA redirect path (default: '/auth/2fa') */
+  twoFactorRedirectPath?: string;
+  /** Enable admin plugin (default: true) */
+  enableAdmin?: boolean;
+  /** Enable 2FA plugin (default: true) */
+  enableTwoFactor?: boolean;
+  /** Enable passkey plugin (default: true) */
+  enablePasskey?: boolean;
+}
 
 // =============================================================================
-// Auth Client with Password Hashing
+// Auth Client Factory
 // =============================================================================
 
 /**
- * Extended auth client that hashes passwords before transmission.
+ * Creates a configured Better-Auth client with password hashing
+ *
+ * This factory function allows creating auth clients with custom configuration,
+ * making it reusable across different projects.
+ *
+ * @example
+ * ```typescript
+ * // Default configuration (works with nest-server defaults)
+ * const authClient = createBetterAuthClient();
+ *
+ * // Custom configuration
+ * const authClient = createBetterAuthClient({
+ *   baseURL: 'https://api.example.com',
+ *   basePath: '/auth',
+ *   twoFactorRedirectPath: '/login/2fa',
+ * });
+ * ```
  *
  * SECURITY: Passwords are hashed with SHA256 client-side to prevent
  * plain text password transmission over the network.
- *
- * The server's normalizePasswordForIam() detects SHA256 hashes (64 hex chars)
- * and processes them correctly.
  */
-export const authClient = {
-  // Spread all base client properties and methods
-  ...baseClient,
-
-  /**
-   * Change password for an authenticated user (both passwords are hashed)
-   */
-  changePassword: async (params: { currentPassword: string; newPassword: string }, options?: any) => {
-    const [hashedCurrent, hashedNew] = await Promise.all([sha256(params.currentPassword), sha256(params.newPassword)]);
-    return baseClient.changePassword?.({ currentPassword: hashedCurrent, newPassword: hashedNew }, options);
-  },
-
-  /**
-   * Reset password with token (new password is hashed before sending)
-   */
-  resetPassword: async (params: { newPassword: string; token: string }, options?: any) => {
-    const hashedPassword = await sha256(params.newPassword);
-    return baseClient.resetPassword?.({ newPassword: hashedPassword, token: params.token }, options);
-  },
-
-  // Override signIn to hash password
-  signIn: {
-    ...baseClient.signIn,
-    /**
-     * Sign in with email and password (password is hashed before sending)
-     */
-    email: async (params: { email: string; password: string; rememberMe?: boolean }, options?: any) => {
-      const hashedPassword = await sha256(params.password);
-      return baseClient.signIn.email({ ...params, password: hashedPassword }, options);
+export function createBetterAuthClient(config: AuthClientConfig = {}) {
+  const {
+    baseURL = import.meta.env?.VITE_API_URL || process.env.API_URL || 'http://localhost:3000',
+    basePath = '/iam',
+    twoFactorRedirectPath = '/auth/2fa',
+    enableAdmin = true,
+    enableTwoFactor = true,
+    enablePasskey = true,
+  } = config;
+
+  // Build plugins array based on configuration
+  const plugins: any[] = [];
+
+  if (enableAdmin) {
+    plugins.push(adminClient());
+  }
+
+  if (enableTwoFactor) {
+    plugins.push(
+      twoFactorClient({
+        onTwoFactorRedirect() {
+          navigateTo(twoFactorRedirectPath);
+        },
+      }),
+    );
+  }
+
+  if (enablePasskey) {
+    plugins.push(passkeyClient());
+  }
+
+  // Create base client with configuration
+  const baseClient = createAuthClient({
+    basePath,
+    baseURL,
+    fetchOptions: {
+      credentials: 'include', // Required for cross-origin cookie handling
     },
-  },
+    plugins,
+  });
 
-  // Explicitly pass through signOut (not captured by spread operator)
-  signOut: baseClient.signOut,
+  // Return extended client with password hashing
+  return {
+    // Spread all base client properties and methods
+    ...baseClient,
+
+    // Explicitly pass through methods not captured by spread operator
+    useSession: baseClient.useSession,
+    passkey: (baseClient as any).passkey,
+    admin: (baseClient as any).admin,
+    $Infer: baseClient.$Infer,
+    $fetch: baseClient.$fetch,
+    $store: baseClient.$store,
 
-  // Override signUp to hash password
-  signUp: {
-    ...baseClient.signUp,
     /**
-     * Sign up with email and password (password is hashed before sending)
+     * Change password for an authenticated user (both passwords are hashed)
      */
-    email: async (params: { email: string; name: string; password: string }, options?: any) => {
-      const hashedPassword = await sha256(params.password);
-      return baseClient.signUp.email({ ...params, password: hashedPassword }, options);
+    changePassword: async (params: { currentPassword: string; newPassword: string }, options?: any) => {
+      const [hashedCurrent, hashedNew] = await Promise.all([sha256(params.currentPassword), sha256(params.newPassword)]);
+      return baseClient.changePassword?.({ currentPassword: hashedCurrent, newPassword: hashedNew }, options);
     },
-  },
 
-  // Override twoFactor to hash passwords
-  twoFactor: {
-    ...baseClient.twoFactor,
     /**
-     * Disable 2FA (password is hashed before sending)
+     * Reset password with token (new password is hashed before sending)
      */
-    disable: async (params: { password: string }, options?: any) => {
-      const hashedPassword = await sha256(params.password);
-      return baseClient.twoFactor.disable({ password: hashedPassword }, options);
+    resetPassword: async (params: { newPassword: string; token: string }, options?: any) => {
+      const hashedPassword = await sha256(params.newPassword);
+      return baseClient.resetPassword?.({ newPassword: hashedPassword, token: params.token }, options);
     },
-    /**
-     * Enable 2FA (password is hashed before sending)
-     */
-    enable: async (params: { password: string }, options?: any) => {
-      const hashedPassword = await sha256(params.password);
-      return baseClient.twoFactor.enable({ password: hashedPassword }, options);
+
+    // Override signIn to hash password (keep passkey method from plugin)
+    signIn: {
+      ...baseClient.signIn,
+      /**
+       * Sign in with email and password (password is hashed before sending)
+       */
+      email: async (params: { email: string; password: string; rememberMe?: boolean }, options?: any) => {
+        const hashedPassword = await sha256(params.password);
+        return baseClient.signIn.email({ ...params, password: hashedPassword }, options);
+      },
+      /**
+       * Sign in with passkey (pass through to base client - provided by passkeyClient plugin)
+       * @see https://www.better-auth.com/docs/plugins/passkey
+       */
+      passkey: (baseClient.signIn as any).passkey,
+    },
+
+    // Explicitly pass through signOut (not captured by spread operator)
+    signOut: baseClient.signOut,
+
+    // Override signUp to hash password
+    signUp: {
+      ...baseClient.signUp,
+      /**
+       * Sign up with email and password (password is hashed before sending)
+       */
+      email: async (params: { email: string; name: string; password: string }, options?: any) => {
+        const hashedPassword = await sha256(params.password);
+        return baseClient.signUp.email({ ...params, password: hashedPassword }, options);
+      },
     },
-  },
-};
 
-export type AuthClient = typeof authClient;
+    // Override twoFactor to hash passwords (provided by twoFactorClient plugin)
+    twoFactor: {
+      ...(baseClient as any).twoFactor,
+      /**
+       * Disable 2FA (password is hashed before sending)
+       */
+      disable: async (params: { password: string }, options?: any) => {
+        const hashedPassword = await sha256(params.password);
+        return (baseClient as any).twoFactor.disable({ password: hashedPassword }, options);
+      },
+      /**
+       * Enable 2FA (password is hashed before sending)
+       */
+      enable: async (params: { password: string }, options?: any) => {
+        const hashedPassword = await sha256(params.password);
+        return (baseClient as any).twoFactor.enable({ password: hashedPassword }, options);
+      },
+      /**
+       * Verify TOTP code (pass through to base client)
+       */
+      verifyTotp: (baseClient as any).twoFactor.verifyTotp,
+      /**
+       * Verify backup code (pass through to base client)
+       */
+      verifyBackupCode: (baseClient as any).twoFactor.verifyBackupCode,
+    },
+  };
+}
+
+// =============================================================================
+// Default Auth Client Instance
+// =============================================================================
+
+/**
+ * Default auth client instance with standard nest-server configuration
+ * Use createBetterAuthClient() for custom configuration
+ */
+export const authClient = createBetterAuthClient();
+
+export type AuthClient = ReturnType<typeof createBetterAuthClient>;

package/nuxt-base-template/app/pages/auth/2fa.vue

@@ -13,6 +13,7 @@ import { authClient } from '~/lib/auth-client';
 // Composables
 // ============================================================================
 const toast = useToast();
+const { setUser, validateSession } = useBetterAuth();
 
 // ============================================================================
 // Page Meta
@@ -28,6 +29,9 @@ const loading = ref<boolean>(false);
 const useBackupCode = ref<boolean>(false);
 const trustDevice = ref<boolean>(false);
 
+// Form state for UForm
+const formState = reactive({ code: '' });
+
 const schema = v.object({
   code: v.pipe(v.string('Code ist erforderlich'), v.minLength(6, 'Code muss mindestens 6 Zeichen haben')),
 });
@@ -41,35 +45,46 @@ async function onSubmit(payload: FormSubmitEvent<Schema>): Promise<void> {
   loading.value = true;
 
   try {
+    let result: any;
+
     if (useBackupCode.value) {
-      const { error } = await authClient.twoFactor.verifyBackupCode({
+      result = await authClient.twoFactor.verifyBackupCode({
         code: payload.data.code,
       });
 
-      if (error) {
+      if (result.error) {
         toast.add({
           color: 'error',
-          description: error.message || 'Backup-Code ungültig',
+          description: result.error.message || 'Backup-Code ungültig',
           title: 'Fehler',
         });
         return;
       }
     } else {
-      const { error } = await authClient.twoFactor.verifyTotp({
+      result = await authClient.twoFactor.verifyTotp({
         code: payload.data.code,
         trustDevice: trustDevice.value,
       });
 
-      if (error) {
+      if (result.error) {
         toast.add({
           color: 'error',
-          description: error.message || 'Code ungültig',
+          description: result.error.message || 'Code ungültig',
           title: 'Fehler',
         });
         return;
       }
     }
 
+    // Update auth state with user data from response
+    const userData = result?.data?.user || result?.user;
+    if (userData) {
+      setUser(userData);
+    } else {
+      // Fallback: validate session to get user data
+      await validateSession();
+    }
+
     await navigateTo('/app');
   } finally {
     loading.value = false;
@@ -92,10 +107,10 @@ function toggleBackupCode(): void {
         </p>
       </div>
 
-      <UForm :schema="schema" class="flex flex-col gap-4" @submit="onSubmit">
+      <UForm :schema="schema" :state="formState" class="flex flex-col gap-4" @submit="onSubmit">
         <UFormField :label="useBackupCode ? 'Backup-Code' : 'Authentifizierungscode'" name="code">
           <UInput
-            name="code"
+            v-model="formState.code"
             :placeholder="useBackupCode ? 'Backup-Code eingeben' : '000000'"
             size="lg"
             class="text-center font-mono text-lg tracking-widest"

package/nuxt-base-template/app/pages/auth/login.vue

@@ -13,6 +13,7 @@ import { authClient } from '~/lib/auth-client';
 // Composables
 // ============================================================================
 const toast = useToast();
+const { signIn, setUser, isLoading, validateSession } = useBetterAuth();
 
 // ============================================================================
 // Page Meta
@@ -51,22 +52,53 @@ const schema = v.object({
 
 type Schema = InferOutput<typeof schema>;
 
+/**
+ * Handle passkey authentication
+ * Uses official Better Auth signIn.passkey() method
+ * @see https://www.better-auth.com/docs/plugins/passkey
+ */
 async function onPasskeyLogin(): Promise<void> {
   passkeyLoading.value = true;
 
   try {
-    const { error } = await authClient.signIn.passkey();
+    // Use official Better Auth client method
+    // This calls: GET /passkey/generate-authenticate-options → POST /passkey/verify-authentication
+    const result = await authClient.signIn.passkey();
 
-    if (error) {
+    // Check for error in response
+    if (result.error) {
       toast.add({
         color: 'error',
-        description: error.message || 'Passkey-Anmeldung fehlgeschlagen',
+        description: result.error.message || 'Passkey-Anmeldung fehlgeschlagen',
         title: 'Fehler',
       });
       return;
     }
 
+    // Update auth state with user data if available
+    if (result.data?.user) {
+      setUser(result.data.user as any);
+    } else if (result.data?.session) {
+      // Passkey auth returns session without user - fetch user via session validation
+      await validateSession();
+    }
+
     await navigateTo('/app');
+  } catch (err: unknown) {
+    // Handle WebAuthn-specific errors
+    if (err instanceof Error && err.name === 'NotAllowedError') {
+      toast.add({
+        color: 'error',
+        description: 'Passkey-Authentifizierung wurde abgebrochen',
+        title: 'Fehler',
+      });
+      return;
+    }
+    toast.add({
+      color: 'error',
+      description: err instanceof Error ? err.message : 'Passkey-Anmeldung fehlgeschlagen',
+      title: 'Fehler',
+    });
   } finally {
     passkeyLoading.value = false;
   }
@@ -79,21 +111,48 @@ async function onSubmit(payload: FormSubmitEvent<Schema>): Promise<void> {
   loading.value = true;
 
   try {
-    const { error } = await authClient.signIn.email({
+    const result = await signIn.email({
       email: payload.data.email,
       password: payload.data.password,
     });
 
-    if (error) {
+    // Check for error in response
+    if ('error' in result && result.error) {
       toast.add({
         color: 'error',
-        description: error.message || 'Anmeldung fehlgeschlagen',
+        description: (result.error as { message?: string }).message || 'Anmeldung fehlgeschlagen',
         title: 'Fehler',
       });
       return;
     }
 
-    await navigateTo('/app');
+    // Check if 2FA is required
+    const resultData = 'data' in result ? result.data : result;
+    if (resultData && 'twoFactorRedirect' in resultData && resultData.twoFactorRedirect) {
+      // Redirect to 2FA page
+      await navigateTo('/auth/2fa');
+      return;
+    }
+
+    // Check if login was successful (user data in response)
+    const userData = 'user' in result ? result.user : ('data' in result ? result.data?.user : null);
+    if (userData) {
+      // Auth state is already stored by useBetterAuth
+      // Navigate to app
+      await navigateTo('/app');
+    } else {
+      toast.add({
+        color: 'error',
+        description: 'Anmeldung fehlgeschlagen - keine Benutzerdaten erhalten',
+        title: 'Fehler',
+      });
+    }
+  } catch (err) {
+    toast.add({
+      color: 'error',
+      description: 'Ein unerwarteter Fehler ist aufgetreten',
+      title: 'Fehler',
+    });
   } finally {
     loading.value = false;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nuxt-base",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Starter to generate a configured environment with VueJS, Nuxt, Tailwind, Eslint, Unit Tests, Playwright etc.",
   "license": "MIT",
   "repository": {