Nuxt Users

https://github.com/rrd108/nuxt-users
Admin
A user authentication module for Nuxt 3 and 4 with database support, role-based access control, and...
Tokens:156,184
Snippets:1,283
Trust Score:8.3
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Start Development Server

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/getting-started.md

Starts the development server to test the setup. After running this command, navigate to the login page and log in with the user created during setup (admin@example.com / password123) to see the user information displayed.

```bash
npm run dev
```

--------------------------------

### Essential Commands

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/examples/basic-setup.md

Commands to install the module, set up the database, create a user, and start the development server.

```bash
# Install module
npm install nuxt-users

# Set up database
npx nuxt-users migrate

# Create user
npx nuxt-users create-user -e email@example.com -n "Name" -p password

# Start development
npm run dev
```

--------------------------------

### Setup Development Environment Commands

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/contributing.md

Commands to clone the repository, install dependencies with yarn, and build the module using yarn dev:prepare.

```bash
# Clone the repository
git clone <repository-url>
cd nuxt-users

# Install dependencies
yarn install

# Build the module
yarn dev:prepare
```

--------------------------------

### Example .env file with database and mailer variables

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/troubleshooting.md

Example .env file with database and mailer configuration variables.

```bash
# .env
DB_HOST=localhost
DB_PORT=3306
DB_USER=myuser
DB_PASSWORD=mypassword
DB_NAME=mydatabase

MAILER_HOST=smtp.gmail.com
MAILER_PORT=587
MAILER_USER=your-email@gmail.com
MAILER_PASS=your-app-password
```

--------------------------------

### Unit test example with mocked dependencies

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/testing.md

Shows how to write unit tests with Vitest, mocking external dependencies like 'h3' and '#imports'. Includes setup and teardown with beforeEach and afterEach.

```ts
import { describe, it, expect, beforeEach, vi } from 'vitest'

// Mock external dependencies
vi.mock('h3', () => ({
  defineEventHandler: vi.fn(handler => handler),
  readBody: vi.fn(),
  createError: vi.fn()
}))

vi.mock('#imports', () => ({
  useRuntimeConfig: vi.fn()
}))

describe('User API Routes', () => {
  let mockReadBody: ReturnType<typeof vi.fn>
  let mockCreateError: ReturnType<typeof vi.fn>

  beforeEach(async () => {
    vi.clearAllMocks()
    
    const h3 = await import('h3')
    mockReadBody = h3.readBody as ReturnType<typeof vi.fn>
    mockCreateError = h3.createError as ReturnType<typeof vi.fn>
  })

  it('should create a user successfully', async () => {
    const newUser = { email: 'new@example.com', name: 'New User', password: 'password123' }
    mockReadBody.mockResolvedValue(newUser)

    // Test implementation
    expect(mockReadBody).toHaveBeenCalled()
  })
})
```

--------------------------------

### Test Setup Utilities

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/testing.md

Provides functions to create a test database connection, get test options for different database types, retrieve database configuration, and clean up after tests. Use these utilities to set up isolated test environments.

```TypeScript
// Create test database connection and configuration
const settings = await createTestSetup({
  dbType: 'sqlite',
  dbConfig: { path: './_test-db' },
  tableName: 'users',
  cleanupFiles: ['./_test-db']
})

// Get test options for different database types
const testOptions = getTestOptions(dbType, dbConfig)

// Get database configuration
const dbConfig = getDatabaseConfig('mysql')

// Cleanup after tests
await cleanupTestSetup(dbType, db, cleanupFiles, tableName)
```

--------------------------------

### Install and initialize Nuxt Users (bash)

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/examples/basic-setup.md

Install the module and peer dependencies, then run migrations and create an initial admin user.

```bash
npm install nuxt-users
npm install db0 better-sqlite3 bcrypt nodemailer

npx nuxt-users migrate

npx nuxt-users create-user -e admin@example.com -n "Admin User" -p password123 -r admin
```

--------------------------------

### Start development server (playground or docs)

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/development-setup.md

Starts the playground development server or the documentation server. The playground runs at http://localhost:3000 and the docs at http://localhost:5173.

```bash
# Start the playground application
yarn dev

# Or start the documentation
yarn docs:dev
```

--------------------------------

### Database test setup with createTestSetup and cleanupTestSetup

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/testing.md

Shows how to set up and tear down database tests using the test setup utilities. Includes mocking of external dependencies and creating necessary tables.

```ts
import { createTestSetup, cleanupTestSetup } from './test-setup'
import type { Database } from 'db0'
import type { ModuleOptions, DatabaseType, DatabaseConfig } from '../src/types'

describe('Database Tests', () => {
  let db: Database
  let testOptions: ModuleOptions
  let dbType: DatabaseType
  let dbConfig: DatabaseConfig

  beforeEach(async () => {
    dbType = process.env.DB_CONNECTOR as DatabaseType || 'sqlite'
    
    if (dbType === 'sqlite') {
      dbConfig = { path: './_test-db' }
    }
    // ... other database configurations

    const settings = await createTestSetup({
      dbType,
      dbConfig,
    })

    db = settings.db
    testOptions = settings.testOptions

    // Create necessary tables
    await createUsersTable(testOptions)
  })

  afterEach(async () => {
    await cleanupTestSetup(dbType, db, [testOptions.connector!.options.path!], testOptions.tables.users)
  })
})
```

--------------------------------

### Install dependencies with Yarn

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/development-setup.md

Installs the project dependencies using Yarn.

```bash
yarn install
```

--------------------------------

### Run pnpm install and approve builds

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/installation.md

After adding the allowed-build-scripts, run these commands to install dependencies and approve the build script.

```bash
pnpm install
pnpm approve-builds
```

--------------------------------

### Install optional peer dependency for form components

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/installation.md

Install @formkit/nuxt for better form UX, which is optional but recommended.

```bash
# Form components (recommended for better UX)
npm install @formkit/nuxt
```

--------------------------------

### Install peer dependencies for development

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/development-setup.md

Installs all peer dependencies required for testing different database connectors and other features during development.

```bash
# Install all peer dependencies for comprehensive testing
yarn add db0 better-sqlite3 mysql2 pg bcrypt nodemailer @formkit/nuxt
```

--------------------------------

### Vue Composition API with script setup

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/code-style.md

Shows a Vue component using Composition API with <script setup>, including props, emits, and refs.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { User } from '~/src/types'

interface Props {
  apiEndpoint?: string
  redirectTo?: string
}

interface Emits {
  (e: 'success', user: User): void
  (e: 'error', error: string): void
}

const props = withDefaults(defineProps<Props>(), {
  apiEndpoint: '/api/nuxt-users/session',
  redirectTo: '/'
})

const emit = defineEmits<Emits>()

const isLoading = ref(false)
const error = ref('')

const handleSubmit = async (formData: LoginFormData) => {
  // Implementation
}
</script>
```

--------------------------------

### Zero-config setup for nuxt-users

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/configuration.md

Minimal configuration for the Nuxt Users module. Requires peer dependencies (db0, better-sqlite3, bcrypt, nodemailer) to be installed. Provides SQLite database, secure password validation, 24-hour token expiration, and a ready-to-use authentication system.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-users']
  // That's it! The module works out of the box
})
```

--------------------------------

### Example .env file for nuxt-users

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/configuration.md

Example .env file with environment variables for database, email, password reset URL, and token expiration. Use this with the direct environment variable configuration in nuxt.config.ts.

```bash
# Database
DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=myapp
DB_PASSWORD=secure_password
DB_NAME=myapp_production

# Email
MAILER_HOST=smtp.gmail.com
MAILER_PORT=587
MAILER_SECURE=false
MAILER_USER=noreply@myapp.com
MAILER_PASS=app_specific_password
MAILER_FROM="My App <noreply@myapp.com>"

# URLs
PASSWORD_RESET_URL=/auth/reset-password

# Auth
TOKEN_EXPIRATION=1440
```

--------------------------------

### Install nuxt-api-shield

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/authentication.md

Installs the nuxt-api-shield module to protect authentication endpoints from brute force attacks.

```bash
# Install the rate limiting module
npx nuxi module add nuxt-api-shield
```

--------------------------------

### Start MySQL with Docker

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/testing.md

Use this command to start a MySQL 5.7 container for testing. It sets the root password to 'rrd', creates a database named 'test_db', and maps port 3306.

```bash
docker run --name mysql-test -e MYSQL_ROOT_PASSWORD=rrd -e MYSQL_DATABASE=test_db -p 3306:3306 -d mysql:5.7
```

--------------------------------

### Start PostgreSQL with Docker

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/testing.md

Use this command to start a PostgreSQL 13 container for testing. It sets the password to '123', creates a database named 'test_db', and maps port 5432.

```bash
docker run --name postgres-test -e POSTGRES_PASSWORD=123 -e POSTGRES_DB=test_db -p 5432:5432 -d postgres:13
```

--------------------------------

### Complete NUsersRegisterForm registration page example

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/components.md

Complete registration page example using the NUsersRegisterForm component. It includes a template with header and footer slots, a script setup with useHead for SEO and event handlers for success, error, and submit, and scoped styles for a gradient background and card layout.

```vue
<template>
  <div class="registration-page">
    <div class="registration-container">
      <NUsersRegisterForm 
        redirect-to="/welcome"
        login-link="/login"
        @success="handleSuccess"
        @error="handleError"
        @submit="handleSubmit"
      >
        <template #header>
          <div class="brand-header">
            <img src="/logo.png" alt="Logo" />
            <h1>Create Your Account</h1>
            <p>Join thousands of satisfied users</p>
          </div>
        </template>
        
        <template #footer>
          <div class="register-footer">
            <p>Already have an account? 
              <NuxtLink to="/login" class="login-link">Sign in here</NuxtLink>
            </p>
            <div class="legal-notice">
              <small>
                By creating an account, you agree to our 
                <a href="/terms">Terms of Service</a> and 
                <a href="/privacy">Privacy Policy</a>.
              </small>
            </div>
          </div>
        </template>
      </NUsersRegisterForm>
    </div>
  </div>
</template>

<script setup>
// SEO and meta
useHead({
  title: 'Register - Your App',
  meta: [
    { name: 'description', content: 'Create a new account to get started with Your App' }
  ]
})

const handleSuccess = (data) => {
  // Show success notification
  console.log('Registration successful:', data)
  // The component will auto-redirect if redirectTo prop is set
}

const handleError = (error) => {
  // Handle error (could show toast notification)
  console.error('Registration error:', error)
}

const handleSubmit = (formData) => {
  // Optional: Track registration attempts
  console.log('Registration attempt:', formData.email)
}
</script>

<style scoped>
.registration-page {
  min-height: 100vh;
  display: flex;
  align-items: center;
  justify-content: center;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  padding: 2rem;
}

.registration-container {
  width: 100%;
  max-width: 480px;
  background: white;
  border-radius: 12px;
  box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
  overflow: hidden;
}

.brand-header {
  text-align: center;
  padding: 2rem 2rem 1rem;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

.brand-header img {
  width: 60px;
  height: 60px;
  margin-bottom: 1rem;
}

.brand-header h1 {
  font-size: 1.75rem;
  font-weight: 700;
  margin-bottom: 0.5rem;
}

.register-footer {
  text-align: center;
  padding-top: 1rem;
}

.login-link {
  color: #667eea;
  text-decoration: none;
  font-weight: 600;
}

.login-link:hover {
  text-decoration: underline;
}

.legal-notice {
  margin-top: 1rem;
  padding-top: 1rem;
  border-top: 1px solid #e5e7eb;
}

.legal-notice a {
  color: #6b7280;
  text-decoration: none;
}

.legal-notice a:hover {
  text-decoration: underline;
}
</style>
```

--------------------------------

### Install nuxt-users Agent Skill

Source: https://github.com/rrd108/nuxt-users/blob/main/README.md

One-time installation command to add the nuxt-users Agent Skill so AI coding agents have procedural knowledge for this module.

```bash
npx skills add rrd108/nuxt-users
```

--------------------------------

### Example Usage of Soft and Hard Delete

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/configuration.md

Example usage showing both soft delete (default) and hard delete configurations with comments explaining the behavior of each.

```ts
// Soft delete configuration (default)
nuxtUsers: {
  hardDelete: false,
  // User deletion sets active: false, preserves data
}

// Hard delete configuration 
nuxtUsers: {
  hardDelete: true,
  // User deletion permanently removes record
}
```

--------------------------------

### JSDoc Comment Example for createUser

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/code-style.md

Example of a documented function with JSDoc comments, showing how to hash a password and insert a user into the database using a SQL template.

```ts
/**
 * Creates a new user in the database
 * @param userData - User data to create
 * @param options - Module options
 * @returns Promise<User> - Created user
 */
export const createUser = async (
  userData: CreateUserData,
  options: ModuleOptions
): Promise<User> => {
  // Hash password before storing
  const hashedPassword = await bcrypt.hash(userData.password, 10)
  
  // Insert user into database
  const result = await db.sql`
    INSERT INTO ${options.tables.users} (email, name, password)
    VALUES (${userData.email}, ${userData.name}, ${hashedPassword})
  `
  
  return result
}
```

--------------------------------

### Install required peer dependencies

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/installation.md

Install the mandatory peer dependencies for database support, TypeScript types, password hashing, and email functionality.

```bash
# Database support (choose one or more based on your needs)
npm install db0 better-sqlite3 mysql2 pg

# TypeScript types for SQLite (recommended)
npm install -D @types/better-sqlite3

# Password hashing
npm install bcrypt

# Email functionality (required for password reset features)
npm install nodemailer
```

--------------------------------

### Install nuxt-users with npm, yarn, or pnpm

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/installation.md

Install the nuxt-users module using your preferred package manager. Choose one command based on your environment.

```bash
npm install nuxt-users
# or
yarn add nuxt-users
# or
pnpm add nuxt-users
```

--------------------------------

### Commit Message Examples

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/contributing.md

Examples of commit messages for different types: feat, fix, and docs.

```plaintext
feat(auth): add OAuth2 support

fix(database): resolve MySQL connection timeout

docs(api): update login endpoint documentation
```

--------------------------------

### Install nuxt-users and peer dependencies

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/getting-started.md

Install the nuxt-users module and its required peer dependencies (db0, better-sqlite3, bcrypt, nodemailer) using npm, yarn, or pnpm.

```bash
# Install the module
npm install nuxt-users
# or
yarn add nuxt-users
# or
pnpm add nuxt-users

# Install required peer dependencies
npm install db0 better-sqlite3 bcrypt nodemailer
# or
yarn add db0 better-sqlite3 bcrypt nodemailer
# or
pnpm add db0 better-sqlite3 bcrypt nodemailer
```

--------------------------------

### Customization Examples for NUsersLogoutLink

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/components.md

Customization examples for NUsersLogoutLink. The first shows custom link text, CSS class, and redirect URL. The second disables the confirmation dialog by setting confirm-message to null.

```vue
<!-- Custom styling and text -->
<NUsersLogoutLink 
  link-text="Sign Out"
  class="custom-logout-btn"
  redirect-to="/home"
/>

<!-- No confirmation dialog -->
<NUsersLogoutLink 
  :confirm-message="null"
  link-text="Quick Logout"
/>
```

--------------------------------

### Google OAuth configuration example

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/api/types.md

Example configuration for enabling Google OAuth in nuxt.config.ts. Sets allowAutoRegistration to false, so only existing users can log in; new users are redirected to errorRedirect with error code user_not_registered.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-users'],
  nuxtUsers: {
    auth: {
      google: {
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        allowAutoRegistration: false, // Only existing users can log in
        successRedirect: '/dashboard',
        errorRedirect: '/login?error=oauth_failed'
      }
    }
  }
})
```

--------------------------------

### Create minimal reproduction with nuxi

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/troubleshooting.md

Create a minimal reproduction by initializing a new Nuxt project, installing nuxt-users, and adding minimal configuration.

```bash
# Create a minimal test case
npx nuxi@latest init test-nuxt-users
cd test-nuxt-users
npm install nuxt-users
# Add minimal configuration and test
```

--------------------------------

### Install peer dependencies for nuxt-users

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/troubleshooting.md

Install all required peer dependencies to resolve missing module errors like 'Cannot find module 'bcrypt'' or 'Cannot find module 'mysql2''. Only the packages for your database type are needed; @formkit/nuxt is optional but recommended.

```bash
# Install all required peer dependencies
npm install db0 better-sqlite3 mysql2 pg bcrypt nodemailer

# For specific database types, you only need:
# SQLite: db0 better-sqlite3
# MySQL: db0 mysql2  
# PostgreSQL: db0 pg

# Optional but recommended:
npm install @formkit/nuxt
```

--------------------------------

### Install and reinstall nuxt-users module

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/troubleshooting.md

Resolve 'Cannot resolve module 'nuxt-users'' by ensuring the module is installed. If the issue persists, clear node_modules and package-lock.json and reinstall.

```bash
# Make sure the module is properly installed
npm install nuxt-users

# Clear node_modules and reinstall if needed
rm -rf node_modules package-lock.json
npm install
```

--------------------------------

### Custom Reset URL Example

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/password-reset.md

Example of a reset link generated when the custom passwordResetUrl is set to '/auth/reset-password'. The path is replaced while token and email parameters remain.

```text
https://yourapp.com/auth/reset-password?token=abc123...&email=user@example.com
```

--------------------------------

### Basic runtimeConfig setup for nuxt-users

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/configuration.md

Basic runtimeConfig setup for nuxt-users module. Uses environment variables for sensitive data. Note that environment variables only override undefined values in runtimeConfig.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-users'],
  
  runtimeConfig: {
    nuxtUsers: {
      connector: {
        name: 'mysql',
        options: {
          host: process.env.NUXT_NUXT_USERS_CONNECTOR_OPTIONS_HOST,
          port: 3306,
          user: process.env.NUXT_NUXT_USERS_CONNECTOR_OPTIONS_USER,
          password: process.env.NUXT_NUXT_USERS_CONNECTOR_OPTIONS_PASSWORD,
          database: process.env.NUXT_NUXT_USERS_CONNECTOR_OPTIONS_DATABASE
        }
      },
      mailer: {
        host: process.env.NUXT_NUXT_USERS_MAILER_HOST,
        port: Number(process.env.NUXT_NUXT_USERS_MAILER_PORT),
        secure: false,
        auth: {
          user: process.env.NUXT_NUXT_USERS_MAILER_AUTH_USER,
          pass: process.env.NUXT_NUXT_USERS_MAILER_AUTH_PASS
        },
        defaults: {
          from: process.env.NUXT_NUXT_USERS_MAILER_DEFAULTS_FROM
        }
      }
    }
  }
})
```

--------------------------------

### Vue component for two-factor authentication setup

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/examples/advanced-configuration.md

This Vue component handles the 2FA setup flow: generating a QR code, enabling and disabling 2FA, and checking the current status. It uses $fetch to call the backend API endpoints. The template includes a setup view with QR code display, backup codes, and a verification input, plus a manage view when 2FA is enabled. The scoped styles define the layout and button styles.

```vue
<!-- components/TwoFactorAuth.vue -->
<script setup>
import { ref } from 'vue'

const props = defineProps({
  user: Object,
  required: true
})

const totpCode = ref('')
const qrCodeUrl = ref('')
const backupCodes = ref([])
const isEnabled = ref(false)

const generateQRCode = async () => {
  try {
    const response = await $fetch('/api/auth/2fa/generate', {
      method: 'POST'
    })
    
    qrCodeUrl.value = response.qrCode
    backupCodes.value = response.backupCodes
  } catch (error) {
    console.error('Failed to generate 2FA:', error)
  }
}

const enable2FA = async () => {
  try {
    await $fetch('/api/auth/2fa/enable', {
      method: 'POST',
      body: { token: totpCode.value }
    })
    
    isEnabled.value = true
    console.log('2FA enabled successfully')
  } catch (error) {
    console.error('Failed to enable 2FA:', error)
  }
}

const disable2FA = async () => {
  try {
    await $fetch('/api/auth/2fa/disable', {
      method: 'POST',
      body: { token: totpCode.value }
    })
    
    isEnabled.value = false
    console.log('2FA disabled successfully')
  } catch (error) {
    console.error('Failed to disable 2FA:', error)
  }
}

onMounted(async () => {
  // Check if 2FA is already enabled
  try {
    const status = await $fetch('/api/auth/2fa/status')
    isEnabled.value = status.enabled
  } catch (error) {
    console.error('Failed to check 2FA status:', error)
  }
})
</script>

<template>
  <div class="two-factor-auth">
    <h2>Two-Factor Authentication</h2>
    
    <div v-if="!isEnabled" class="enable-2fa">
      <p>Enhance your account security with two-factor authentication.</p>
      
      <button @click="generateQRCode" class="generate-btn">
        Set Up 2FA
      </button>
      
      <div v-if="qrCodeUrl" class="qr-setup">
        <h3>Scan QR Code</h3>
        <img :src="qrCodeUrl" alt="2FA QR Code" />
        
        <h3>Backup Codes</h3>
        <div class="backup-codes">
          <p>Save these backup codes in a safe place:</p>
          <ul>
            <li v-for="code in backupCodes" :key="code">{{ code }}</li>
          </ul>
        </div>
        
        <div class="verify-setup">
          <label>Enter verification code:</label>
          <input v-model="totpCode" type="text" placeholder="000000" />
          <button @click="enable2FA">Enable 2FA</button>
        </div>
      </div>
    </div>
    
    <div v-else class="manage-2fa">
      <p>✅ Two-factor authentication is enabled</p>
      
      <div class="disable-2fa">
        <label>Enter verification code to disable:</label>
        <input v-model="totpCode" type="text" placeholder="000000" />
        <button @click="disable2FA" class="danger-btn">Disable 2FA</button>
      </div>
    </div>
  </div>
</template>

<style scoped>
.two-factor-auth {
  max-width: 500px;
  margin: 0 auto;
  padding: 2rem;
}

.qr-setup {
  margin-top: 2rem;
  text-align: center;
}

.qr-setup img {
  margin: 1rem 0;
}

.backup-codes {
  background: #f9fafb;
  padding: 1rem;
  border-radius: 8px;
  margin: 1rem 0;
}

.backup-codes ul {
  list-style: none;
  padding: 0;
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 0.5rem;
}

.backup-codes li {
  background: white;
  padding: 0.5rem;
  border-radius: 4px;
  font-family: monospace;
  text-align: center;
}

.verify-setup {
  margin-top: 2rem;
}

.verify-setup input {
  display: block;
  width: 100%;
  padding: 0.75rem;
  margin: 0.5rem 0;
  border: 1px solid #d1d5db;
  border-radius: 4px;
  text-align: center;
  font-family: monospace;
  font-size: 1.25rem;
}

.generate-btn, .verify-setup button {
  background: #3b82f6;
  color: white;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 6px;
  cursor: pointer;
  font-weight: 500;
}

.danger-btn {
  background: #dc2626;
  color: white;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 6px;
  cursor: pointer;
  font-weight: 500;
}
</style>
```

--------------------------------

### Docker Compose Production Setup (docker-compose.prod.yml)

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/examples/advanced-configuration.md

Defines a production Docker Compose setup with app, postgres, and redis services. The app service depends on postgres and redis, and uses environment variables for configuration.

```yaml
# docker-compose.prod.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=postgres
      - DB_USER=myapp
      - DB_PASSWORD=secure_password
      - DB_NAME=myapp_prod
    depends_on:
      - postgres
      - redis
    
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: myapp_prod
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secure_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
      
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:
```

--------------------------------

### Basic NUsersList Usage

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/components.md

Basic usage of the NUsersList component. It works out of the box without additional setup.

```vue
<script setup>
// This component works out of the box without additional setup
</script>

<template>
  <div>
    <NUsersList />
  </div>
</template>
```

--------------------------------

### Run Google OAuth database migration

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/authentication.md

Run this migration command for existing databases to add Google OAuth fields. New installations include these fields automatically.

```bash
# Add google_id and profile_picture columns to users table
npx nuxt-users add-google-oauth-fields
```

--------------------------------

### Minimal nuxt.config.ts for Nuxt Users

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/examples/basic-setup.md

Zero-config setup: just add the module to your Nuxt config.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-users']
  // That's it! No configuration needed
})
```

--------------------------------

### Permission type and RBAC configuration example

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/architecture.md

Defines the permission type and a configuration example for role-based access control. The admin role has full access, user has specific paths, and moderator has a path with methods and a dashboard path.

```typescript
type Permission = string | {
  path: string
  methods: HttpMethod[]
}
```

```typescript
permissions: {
  admin: ['*'],                    // Full access
  user: ['/profile', '/api/nuxt-users/me'],
  moderator: [
    { path: '/api/users/*', methods: ['GET', 'PATCH'] },
    '/admin/dashboard'
  ]
}
```

--------------------------------

### Vue component using useNuxtUsersLocale

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/composables.md

Example of using the useNuxtUsersLocale composable in a Vue script setup to translate keys with and without parameters, and display them in the template.

```vue
<script setup>
import { useNuxtUsersLocale } from 'nuxt-users/composables'

const { t, currentLocale, fallbackLocale } = useNuxtUsersLocale()

// Translate a simple key
const title = t('login.title')  // "Welcome Back"

// Translate with parameters
const message = t('userCard.deleteConfirm', ['John Doe'])
// "Are you sure you want to delete user John Doe?"
</script>

<template>
  <div>
    <h1>{{ t('login.title') }}</h1>
    <p>{{ t('login.subtitle') }}</p>
  </div>
</template>
```

--------------------------------

### Login page with translation key and NUsersLoginForm

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/localization.md

Example login page using the translation key and the NUsersLoginForm component.

```vue
<!-- pages/login.vue -->
<script setup>
const { t } = useNuxtUsersLocale()
</script>

<template>
  <div>
    <h1>{{ t('login.title') }}</h1>
    <NUsersLoginForm />
  </div>
</template>
```

--------------------------------

### Create German Locale File

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/localization.md

Example of a new locale file for German, defining translations for common and login sections. Place it in src/runtime/locales/.

```typescript
// src/runtime/locales/de.ts
import type { LocaleMessages } from '../../types'

export const de: LocaleMessages = {
  common: {
    email: 'E-Mail',
    password: 'Passwort',
    name: 'Name',
    // ... all common keys
  },
  login: {
    title: 'Willkommen zurück',
    subtitle: 'Melden Sie sich an',
    // ... all login keys
  },
  // ... all other sections
}
```

--------------------------------

### Email Confirmation URL and Response

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/api/index.md

Example URL for GET /api/nuxt-users/confirm-email with token and email query parameters, and the successful response. Token expires after 24 hours and is deleted after confirmation.

```http
GET /api/nuxt-users/confirm-email?token=abc123def456&email=user@example.com
```

```json
{
  "success": true,
  "message": "Email confirmed successfully! Your account is now active. You can now log in."
}
```

--------------------------------

### Run database migrations and create first user

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/installation.md

Run these commands from the project root to set up the database. Use the migrate command for all migrations, or individual commands for specific tables. Create your first user with the create-user command.

```bash
# Run all migrations (recommended)
npx nuxt-users migrate

# Or run individual commands
npx nuxt-users create-users-table
npx nuxt-users create-personal-access-tokens-table
npx nuxt-users create-password-reset-tokens-table

# Create your first user
npx nuxt-users create-user -e user@example.com -n "John Doe" -p password123
```

--------------------------------

### Environment Variables for Production (.env.production)

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/examples/advanced-configuration.md

Defines environment variables for production, including database, email (SendGrid example), URLs, and security settings. These variables are referenced by the nuxt.config.ts production setup.

```bash
# .env.production
NODE_ENV=production

# Database
DB_HOST=your-postgres-host.com
DB_PORT=5432
DB_USER=myapp_user
DB_PASSWORD=secure_random_password_here
DB_NAME=myapp_production

# Email (SendGrid example)
MAILER_HOST=smtp.sendgrid.net
MAILER_PORT=587
MAILER_SECURE=false
MAILER_USER=apikey
MAILER_PASS=SG.your_sendgrid_api_key_here
MAILER_FROM="MyApp <noreply@myapp.com>"

# URLs
PASSWORD_RESET_BASE_URL=https://myapp.com

# Security
TOKEN_EXPIRATION=1440
JWT_SECRET=your_super_secure_jwt_secret_here
```

--------------------------------

### Test Structure with beforeEach and afterEach

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/code-style.md

Shows the recommended structure for a test suite: setup in beforeEach, cleanup in afterEach, and two it blocks covering a success case and an error case. Uses createTestSetup with sqlite and a test database path.

```ts
describe('Feature Name', () => {
  let db: Database
  let testOptions: ModuleOptions

  beforeEach(async () => {
    // Setup test environment
    const settings = await createTestSetup({
      dbType: 'sqlite',
      dbConfig: { path: './_test-db' }
    })
    
    db = settings.db
    testOptions = settings.testOptions
  })

  afterEach(async () => {
    // Cleanup test data
  })

  it('should do something', async () => {
    // Test implementation
    expect(result).toBe(expected)
  })

  it('should handle errors gracefully', async () => {
    // Error test
    await expect(asyncFunction()).rejects.toThrow('Error message')
  })
})
```

--------------------------------

### Example output of check:locale-consistency

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/localization.md

Shows the output when running the check:locale-consistency script, including statistics and a success message when all translations are consistent.

```text
[Nuxt Users] 🔍 Checking Hungarian locale formal/informal consistency...

[Nuxt Users] 📊 Statistics:
   Base keys: 85
   Informal override keys: 20
   Formal override keys: 20

[Nuxt Users] ✅ All formal/informal translations are consistent!
```

--------------------------------

### Set up MySQL for development

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/development-setup.md

Starts a MySQL 5.7 Docker container and sets the environment variables needed for MySQL testing. The container uses port 3306 and the database 'test_db'.

```bash
# Using Docker
docker run --name mysql-test \
  -e MYSQL_ROOT_PASSWORD=rrd \
  -e MYSQL_DATABASE=test_db \
  -p 3306:3306 \
  -d mysql:5.7

# Set environment variables
export DB_CONNECTOR=mysql
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=root
export DB_PASSWORD=rrd
export DB_NAME=test_db
```

--------------------------------

### Prepare development environment with yarn dev:prepare

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/development-setup.md

Builds the module with stubs, prepares the playground application, and sets up the development environment.

```bash
yarn dev:prepare
```

--------------------------------

### Get applied migrations with getAppliedMigrations

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/database-internals.md

Returns a list of migrations already applied to the database. The output is an array of migration names, e.g., ['create_migrations_table', 'create_users_table', ...].

```typescript
import { getAppliedMigrations } from '#nuxt-users/server'

const applied = await getAppliedMigrations(options)
console.log('Applied migrations:', applied)
// Output: ['create_migrations_table', 'create_users_table', ...]
```

--------------------------------

### GET /api/nuxt-users/me

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/api/index.md

Gets the current user's profile information. Requires authentication.

```APIDOC
## GET /api/nuxt-users/me

### Description
Gets the current user's profile information. Requires authentication.

### Method
GET

### Endpoint
/api/nuxt-users/me

### Parameters
No parameters required.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **user** (object) - The current user's profile

#### Response Example
{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}

### Error Responses
- `401 Unauthorized`: No authentication token or invalid token
```

--------------------------------

### GET /api/nuxt-users/inactive

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/api/index.md

Gets a list of all inactive users. Requires authentication and proper authorization.

```APIDOC
## GET /api/nuxt-users/inactive

### Description
Gets a list of all inactive users. Requires authentication and proper authorization.

### Method
GET

### Endpoint
/api/nuxt-users/inactive

### Parameters
No parameters required.

### Request Example
No request body required.

### Response
#### Success Response (200)
Returns a paginated list of user objects.

#### Response Example
{
  "users": [
    {
      "id": 1,
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user",
      "active": false,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

### Error Responses
- `401 Unauthorized`: No authentication token or invalid token
- `403 Forbidden`: User doesn't have permission to view inactive users
```

--------------------------------

### Initialize database with npx nuxt-users migrate

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/getting-started.md

Run the migration command from your project root (where nuxt.config lives) to initialize the database.

```bash
npx nuxt-users migrate
```

--------------------------------

### GET /api/nuxt-users/:id

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/api/index.md

Gets a user by ID. Users can only access their own profile unless they have admin permissions.

```APIDOC
## GET /api/nuxt-users/:id

### Description
Gets a user by ID. Users can only access their own profile unless they have admin permissions.

### Method
GET

### Endpoint
/api/nuxt-users/:id

### Parameters
#### Path Parameters
- **id** (integer) - Required - User ID

### Request Example
No request body required.

### Response
#### Success Response (200)
- **user** (object) - The user object

#### Response Example
{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}

### Error Responses
- `400 Bad Request`: Invalid user ID
- `401 Unauthorized`: No authentication token or invalid token
- `403 Forbidden`: User doesn't have permission to access this profile
- `404 Not Found`: User not found
```

--------------------------------

### Set up PostgreSQL for development

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/development-setup.md

Starts a PostgreSQL 13 Docker container and sets the environment variables needed for PostgreSQL testing. The container uses port 5432 and the database 'test_db'.

```bash
# Using Docker
docker run --name postgres-test \
  -e POSTGRES_PASSWORD=123 \
  -e POSTGRES_DB=test_db \
  -p 5432:5432 \
  -d postgres:13

# Set environment variables
export DB_CONNECTOR=postgresql
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=postgres
export DB_PASSWORD=123
export DB_NAME=test_db
```

--------------------------------

### getNestedValue() usage example

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/localization.md

Example usage of getNestedValue() to retrieve a nested value using dot notation.

```typescript
getNestedValue(messages, 'login.title')
// Returns messages.login.title
```

--------------------------------

### Quick Start Test Commands

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/testing.md

Run the default test suite (Nuxt 4: lint, types, unit, all databases) with `yarn test`. Use `yarn test:nuxt3` for Nuxt 3 compatibility, `yarn test:watch` for watch mode, and `yarn test:unit` for unit tests without a database.

```bash
# Run default tests (Nuxt 4: lint + types + unit + all databases)
yarn test

# Run Nuxt 3 compatibility suite manually
yarn test:nuxt3

# Run tests in watch mode
yarn test:watch

# Run only unit tests (no database required)
yarn test:unit
```

--------------------------------

### Example usage of UserWithoutPassword

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/api/types.md

Example usage of UserWithoutPassword in a component or page. It is safe to send the user object to the client.

```typescript
// In your component or page
const user = ref<UserWithoutPassword | null>(null)

// Safe to send to client
return {
  user: user.value
}
```

--------------------------------

### Runtime environment variables for database connections

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/configuration.md

Example environment variables for development and production deployments. These variables are read at runtime via useRuntimeConfig(), allowing the same build to work across environments. Only works with the runtimeConfig pattern, not with top-level nuxtUsers configuration using process.env.

```bash
# Same build, different environments
# Development
NUXT_NUXT_USERS_CONNECTOR_OPTIONS_HOST=localhost
NUXT_NUXT_USERS_CONNECTOR_OPTIONS_DATABASE=myapp_dev

# Production
NUXT_NUXT_USERS_CONNECTOR_OPTIONS_HOST=production-db.example.com
NUXT_NUXT_USERS_CONNECTOR_OPTIONS_DATABASE=myapp_production

# The same application build works in both environments!
```

--------------------------------

### Test Structure Example

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/contributing.md

Example test structure using describe, beforeEach, afterEach, and it blocks for testing features and error handling.

```ts
describe('Feature Name', () => {
  beforeEach(async () => {
    // Setup
  })

  afterEach(async () => {
    // Cleanup
  })

  it('should do something', async () => {
    // Test implementation
  })

  it('should handle errors gracefully', async () => {
    // Error test
  })
})
```

--------------------------------

### Run Database Migration

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/examples/basic-setup.md

Run the migration command to ensure the database schema is set up correctly.

```bash
# Make sure you ran the migration
npx nuxt-users migrate
```

--------------------------------

### Test User Creation

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/examples/basic-setup.md

Create a test user using the CLI and optionally verify the user in the database.

```bash
# Create a test user
npx nuxt-users create-user -e test@example.com -n "Test User" -p password123

# Verify user was created (optional)
sqlite3 ./data/users.sqlite3 "SELECT * FROM users;"
```

--------------------------------

### Let the Module Handle Everything (App.vue)

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/theme-integration.md

Use this pattern for new projects without existing theme systems. The module handles all theme integration automatically, and components follow system preferences without additional code.

```vue
<!-- App.vue -->
<template>
  <div>
    <NUsersLoginForm />
    <!-- Components automatically follow system preferences -->
  </div>
</template>
```

--------------------------------

### Get User Response

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/api/index.md

Response body for GET /api/nuxt-users/:id, returning the user object. Users can only access their own profile unless they have admin permissions.

```json
{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}
```

--------------------------------

### Verify database configuration with npx nuxt-users project-info

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/troubleshooting.md

Use the project-info command to verify your database configuration and module setup. It displays connector type, connection details, table names, migrations table status, and applied migrations count.

```bash
# Check your project configuration and database settings
npx nuxt-users project-info

# This will show:
# - Database connector type (SQLite, MySQL, PostgreSQL)
# - Database connection details (host, port, user, database name)
# - Table names configuration
# - Migrations table status
# - Number of applied migrations
```

--------------------------------

### useDb() - Create database connection

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/developer-guide/server-utilities.md

Creates a database connection using the module's configuration. The example shows importing useDb, creating a connection, and running a SQL query.

```typescript
import { useDb } from '#nuxt-users/server/utils'

const db = await useDb(options)
const result = await db.sql`SELECT * FROM users WHERE active = true`
```

--------------------------------

### Test database connection from production

Source: https://github.com/rrd108/nuxt-users/blob/main/docs/user-guide/troubleshooting.md

Test database connectivity from the production server using MySQL or PostgreSQL commands.

```bash
# Test database connection from production server
# For MySQL:
mysql -h $DB_HOST -u $DB_USER -p$DB_PASSWORD $DB_NAME -e "SELECT 1"

# For PostgreSQL:
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT 1"
```
Tokens:
Raw