nuxt-users — Claude Code skill: authentication for Nuxt
Skill for Claude Code, Cursor and GitHub Copilot: configures the nuxt-users module — full authentication for Nuxt with roles, password reset and SQLite, MySQL or PostgreSQL support.
MIT 292 installs ★ 730 updated 2026-11-10
npx skills add onmax/nuxt-skills --skill nuxt-users -a claude-codeWhat nuxt-users does
The skill covers nuxtUsers config in nuxt.config.ts (database connector, role-based permissions, public-path whitelist, password validation, mailer for reset), CLI commands (npx nuxt-users migrate, create-user), auto-imported composables (useAuthentication, useUsers, usePublicPaths, usePasswordValidation, useNuxtUsersLocale) and ready-made components (NUsersLoginForm, NUsersLogoutLink, NUsersUserForm, NUsersList).
Requires peer dependencies: db0, better-sqlite3 (or mysql2 / pg for MySQL / PostgreSQL), bcrypt, nodemailer. CLI runs from the project root where nuxt.config.ts lives; production deploys without dev dependencies fall back to DB_* environment variables. Roles are defined as keys in auth.permissions; enable auth.allowCustomRoles: true to accept arbitrary roles.
The skill guides you through migration steps, table structure, handling the @success event from the login form via login(user), Google OAuth setup and guard-based authorization logic.
What it helps with
- set up authentication with roles and access control in Nuxt
- run database migrations and create the first user
- add a login form with composable and
NUsersLoginFormcomponent - configure password reset via nodemailer and tokens
- allow or deny route access by role
Example prompts for the agent
- Add
nuxt-usersto the project, configure SQLite and run migrations - Create an admin user with
npx nuxt-users create-user - Set
auth.permissionsso roleusercan access/profileand/api/nuxt-users/me
How to install nuxt-users
1Skills CLI (Vercel)
npx skills add onmax/nuxt-skills --skill nuxt-users -a claude-code2Manually: put the files in place
~/.claude/skills/nuxt-users/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/nuxt-users/
1Skills CLI (Vercel)
npx skills add onmax/nuxt-skills --skill nuxt-users -a codex2Manually: put the files in place
.agents/skills/nuxt-users/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add onmax/nuxt-skills --skill nuxt-users -a cursor2Manually: put the files in place
.cursor/skills/nuxt-users/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install onmax/nuxt-skills skills/nuxt-users2Manually: put the files in place
.github/skills/nuxt-users/SKILL.md1Skills CLI (Vercel)
npx skills add onmax/nuxt-skills --skill nuxt-users -a gemini-cli2Platform CLI
gemini skills install https://github.com/onmax/nuxt-skills --path skills/nuxt-usersManually: put the files in place
.devin/skills/nuxt-users/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add onmax/nuxt-skills --skill nuxt-users -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about nuxt-users
How to install nuxt-users in Claude Code?
Run npx skills add onmax/nuxt-skills --skill nuxt-users -a claude-code, the skill appears in ~/.claude/skills/nuxt-users/SKILL.md.
What does nuxt-users do?
Adds complete authentication to Nuxt: login, roles, password reset, user management, route authorization and ready-made form components. Supports SQLite, MySQL and PostgreSQL.
What does nuxt-users need to run?
Install peer dependencies: db0, a database driver (better-sqlite3, mysql2 or pg), bcrypt and nodemailer. Run CLI from the project root where nuxt.config.ts is located.
Source text
SKILL.md · MIT
---
name: nuxt-users
description: 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).
license: MIT
metadata:
author: rrd108
version: "1.0"
---
# Nuxt Users skill
## Initial setup
1. **Install the module and peer dependencies**
```bash
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`**
```ts
export default defineNuxtConfig({
modules: ['nuxt-users']
})
```
3. **Run migrations**
From the project root (where `nuxt.config.ts` lives):
```bash
npx nuxt-users migrate
```
4. **Create at least one user**
```bash
npx nuxt-users create-user -e [email protected] -n "Admin User" -p password123 -r admin
```
Flags: `-e` email, `-n` name, `-p` password, `-r` role (optional).
5. **Configure permissions**
```ts
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 | `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**
```bash
npx nuxt-users migrate
```
- **Create user**
```bash
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**
```bash
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
| 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](https://github.com/rrd108/nuxt-users/blob/ace4a22820a1b1a28951cf1819148c260f841df6/llms.txt) in the repo root
- Full docs: [https://nuxt-users.webmania.cc/](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.
© rrd108 · MIT · onmax/nuxt-skills