/nuxt-users

name: nuxt-users
description: Configure and use the nuxt-users module for Nuxt 3 and Nuxt 4. Use when adding authentication, user management, roles, password reset, database setup (SQLite/MySQL/PostgreSQL), or CLI commands (migrate, create-user). Covers nuxt.config (nuxtUsers), composables (useAuthentication, useUsers, usePublicPaths, usePasswordValidation, useNuxtUsersLocale), components (NUsersLoginForm, NUsersLogoutLink, etc.), and authorization (whitelist, permissions).
license: MIT
metadata:
  author: rrd108
  version: "1.0"

Nuxt Users skill

Initial setup

1. **Install the module and peer dependencies**

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

For MySQL or PostgreSQL, install the corresponding driver (`mysql2` or `pg`) instead of or in addition to `better-sqlite3` as required.

2. **Register the module in `nuxt.config.ts`**

   export default defineNuxtConfig({
     modules: ['nuxt-users']
   })

3. **Run migrations** From the project root (where `nuxt.config.ts` lives):

   npx nuxt-users migrate

4. **Create at least one user**

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

Flags: `-e` email, `-n` name, `-p` password, `-r` role (optional).

5. **Configure permissions**

   export default defineNuxtConfig({
     modules: ['nuxt-users'],
     nuxtUsers: {
       auth: {
         permissions: {
           admin: ['*'],
           user: ['/profile', '/api/nuxt-users/me']
         }
       }
     }
   })

6. **Use login in a page**

• Use the `NUsersLoginForm` component and handle `@success` by calling `login(user)` from `useAuthentication()`.
• Optionally redirect after login (e.g. `navigateTo('/')`).

Configuration reference (nuxt.config.ts)

All options live under `nuxtUsers` in `nuxt.config.ts`.

| Area | Key | Notes | | -------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | Database | `connector.name` | `'sqlite' \| 'mysql' \| 'postgresql'` | | Database | `connector.options` | `path` (SQLite), or `host`, `port`, `user`, `password`, `database` (MySQL/PostgreSQL) | | API | `apiBasePath` | Default `'/api/nuxt-users'` | | Tables | `tables.users`, `tables.personalAccessTokens`, `tables.passwordResetTokens`, `tables.migrations` | Custom table names | | Mailer | `mailer` | Nodemailer config for password reset emails | | URLs | `passwordResetUrl`, `emailConfirmationUrl` | Paths for redirects | | Auth | `auth.whitelist` | Public routes (e.g. `['/register']`); `/login` is always public | | Auth | `auth.tokenExpiration` | Minutes (default 1440) | | Auth | `auth.rememberMeExpiration` | Days (default 30) | | Auth | `auth.permissions` | Role → paths (e.g. `admin: ['*']`, `user: ['/profile']`) | | Auth | `auth.google` | Google OAuth: `clientId`, `clientSecret`, `callbackUrl`, etc. | | Password | `passwordValidation` | `minLength`, `requireUppercase`, `requireLowercase`, `requireNumbers`, `requireSpecialChars`, `preventCommonPasswords` | | Data | `hardDelete` | `true` = hard delete, `false` = soft delete (default) | | Locale | `locale.default`, `locale.texts`, `locale.fallbackLocale` | Localization |

Runtime config is also supported: use `runtimeConfig.nuxtUsers` for env-based or server-only settings.

CLI commands

Run from the project root so `nuxt.config.ts` (and optionally `.env`) are found.

• **Migrations**

  npx nuxt-users migrate

• **Create user**

  npx nuxt-users create-user -e <email> -n "