Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add onmax/nuxt-skills --skill nuxt-users -a claude-code
Open on GitHub

What 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 NUsersLoginForm component
  • configure password reset via nodemailer and tokens
  • allow or deny route access by role

Example prompts for the agent

  • Add nuxt-users to the project, configure SQLite and run migrations
  • Create an admin user with npx nuxt-users create-user
  • Set auth.permissions so role user can access /profile and /api/nuxt-users/me

How to install nuxt-users

1Skills CLI (Vercel)

npx skills add onmax/nuxt-skills --skill nuxt-users -a claude-code

2Manually: put the files in place

~/.claude/skills/nuxt-users/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nuxt-users/

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

Similar skills

All skills for Frontend and UI →

From the same set13

The whole set →
nuxthub nuxthub is a Claude Code skill that configures databases, KV storage, and blob handling for NuxtHub v0.10.12 applications. Activates when editing Drizzle schemas, migrations, or cloud bindings. CX Codex +1 2,300installs nuxt-better-auth nuxt-better-auth guides Nuxt authentication with @nuxtjs/better-auth, including route guards, session handling, and Better Auth plugins. CX Codex +1 2,100installs nuxt-studio Walks you through self-hosted Nuxt Studio: auth, media, drafts and Git publishing. Useful when the content editor has to live on your own domain. CX Codex +1 1,700installs nuxt-i18n nuxt-i18n — a skill that walks your coding agent through @nuxtjs/i18n setup: locales, translated routes, language detection and locale SEO. CX Codex +1 741installs comark The comark skill parses markdown with Comark component support and renders it in Vue, React, Svelte or Angular. Fits projects with custom blocks in documentation or content. CX Codex +1 306installs arkenv Helps configure ArkEnv, define typed environment schemas, and add validation to JavaScript and TypeScript projects. CX Codex +1 282installs regle regle is a Claude Code skill for adding and editing Regle-validated forms in Vue 3. It covers field bindings through r$ and displaying validation errors. CX Codex +1 269installs t3-code-continue-thread t3-code-continue-thread resumes work from an earlier T3 Code session by parsing its UUID, checking git worktrees, and writing a fresh handoff document. CX Codex +1 187installs

Project sponsors

Companies that keep this analytics open