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.

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 "<name>" -p <password> [-r <role>]

  Role should match a auth.permissions key unless auth.allowCustomRoles is true (or permissions are empty).

• Legacy/table creation

  npx nuxt-users create-users-table
  npx nuxt-users create-personal-access-tokens-table
  npx nuxt-users create-password-reset-tokens-table
  npx nuxt-users create-migrations-table

Production: The CLI requires nuxt-users (and peers) installed where Node runs — it is not bundled inside .output/. Full config needs the app root with nuxt.config; build-only or --omit=dev deploys fall back to DB_* env vars. See docs/user-guide/configuration.md.

Composables (auto-imported)

• useAuthentication() — user, isAuthenticated, login(user, rememberMe?), logout(), fetchUser(useSSR?), initializeUser()
• useUsers() — Admin: users, pagination, loading, error, fetchUsers(page?, limit?), updateUser, addUser, removeUser(userId)
• usePublicPaths() — getPublicPaths(), getAccessiblePaths(), isPublicPath(path), isAccessiblePath(path, method?)
• usePasswordValidation(moduleOptions?, options?) — validate(password), isValid, errors, strength, score, clearValidation()
• useNuxtUsersLocale() — t(key, params?), currentLocale, fallbackLocale

Components

• NUsersLoginForm — Login form; use @success to call login(user) from useAuthentication()
• NUsersLogoutLink — Logout link/button
• NUsersProfileInfo — Display profile
• NUsersResetPasswordForm — Password reset form
• NUsersList — List users (admin)
• NUsersUserForm — Create/edit user form; role select from auth.permissions keys; set auth.allowCustomRoles: true for a custom free-text role option

Troubleshooting

File references

• Project LLM context and config types: llms.txt in the repo root
• Full docs: https://nuxt-users.webmania.cc/
• Getting started and examples: ../../docs/user-guide/getting-started.md, ../../docs/examples/basic-setup.md
• Authorization: ../../docs/user-guide/authorization.md
• Configuration details: ../../docs/user-guide/configuration.md

Keep nuxtUsers config and permissions in sync with the app’s roles and routes; use guard clauses and early returns when implementing custom auth logic.