nuxt-users
Configure and use the nuxt-users module for Nuxt. 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).
How do I install this agent skill?
npx skills add https://github.com/onmax/nuxt-skills --skill nuxt-usersIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides instructions for setting up and using the nuxt-users module for Nuxt applications. It includes standard package installations, configuration examples, and CLI commands for database management and user creation. No malicious patterns or security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Nuxt Users skill
Initial setup
-
Install the module and peer dependencies
npm install nuxt-users npm install db0 better-sqlite3 bcrypt nodemailerFor MySQL or PostgreSQL, install the corresponding driver (
mysql2orpg) instead of or in addition tobetter-sqlite3as required. -
Register the module in
nuxt.config.tsexport default defineNuxtConfig({ modules: ['nuxt-users'] }) -
Run migrations From the project root (where
nuxt.config.tslives):npx nuxt-users migrate -
Create at least one user
npx nuxt-users create-user -e admin@example.com -n "Admin User" -p password123 -r adminFlags:
-eemail,-nname,-ppassword,-rrole (optional). -
Configure permissions
export default defineNuxtConfig({ modules: ['nuxt-users'], nuxtUsers: { auth: { permissions: { admin: ['*'], user: ['/profile', '/api/nuxt-users/me'] } } } }) -
Use login in a page
- Use the
NUsersLoginFormcomponent and handle@successby callinglogin(user)fromuseAuthentication(). - Optionally redirect after login (e.g.
navigateTo('/')).
- Use the
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 | siteUrl | Public app URL for links in emails (e.g. 'https://example.com'). Required in production; the Host header is only trusted in development |
| 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']). Keys are the predefined roles. |
| Auth | auth.allowCustomRoles | Default false. When true, create/update APIs and NUsersUserForm accept roles not listed in permissions. Empty permissions (bootstrap) already accepts any role. |
| 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 "<name>" -p <password> [-r <role>]Role should match a
auth.permissionskey unlessauth.allowCustomRolesistrue(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 withnuxt.config; build-only or--omit=devdeploys fall back toDB_*env vars. Seedocs/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@successto calllogin(user)fromuseAuthentication()NUsersLogoutLink— Logout link/buttonNUsersProfileInfo— Display profileNUsersResetPasswordForm— Password reset formNUsersList— List users (admin)NUsersUserForm— Create/edit user form; role select fromauth.permissionskeys; setauth.allowCustomRoles: truefor a custom free-text role option
Troubleshooting
| Symptom | Fix |
|---|---|
| Redirected to login on protected routes | Set auth.permissions so each role has access to needed routes |
| CLI config not found / wrong tables | Run CLI from the directory containing nuxt.config; see production note above |
| Migrations table missing | Run npx nuxt-users migrate from project root |
| Database driver errors | Install correct peer: SQLite → better-sqlite3, MySQL → mysql2, PostgreSQL → pg |
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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/onmax/nuxt-skills/nuxt-users">View nuxt-users on skillZs</a>