Nuxt Users スキル

このスキルは nuxt-users モジュールの操作を支援します：ユーザー認証、認可、データベース設定、および Nuxt 3 と Nuxt 4 アプリ用の CLI です。

このスキルを使用する場合

• ユーザーが Nuxt アプリにログイン、登録、またはログアウト機能を追加したい場合
• ユーザーが nuxt-users 用のデータベース（SQLite、MySQL、PostgreSQL）をセットアップまたは変更する必要がある場合
• ユーザーが CLI コマンドを実行したい場合：npx nuxt-users migrate、npx nuxt-users create-user
• ユーザーがパーミッション、ロール、または公開ルート（ホワイトリスト）を設定する必要がある場合
• ユーザーがパスワード検証、セッション期間、またはメーラー（パスワードリセット）をカスタマイズしている場合
• ユーザーが useAuthentication、useUsers、usePublicPaths、usePasswordValidation などのコンポーザブルを使用している場合
• ユーザーが NUsersLoginForm、NUsersLogoutLink、NUsersProfileInfo、NUsersResetPasswordForm、NUsersList、NUsersUserForm などのコンポーネントをスタイリングまたは統合している場合

ステップバイステップ：初期セットアップ

1. モジュールとピアー依存関係をインストール

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

   MySQL または PostgreSQL の場合、必要に応じて better-sqlite3 の代わりに、または追加で対応するドライバー（mysql2 または pg）をインストールしてください。

2. nuxt.config.ts にモジュールを登録

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

3. マイグレーションを実行 プロジェクトルート（nuxt.config.ts が存在する場所）から実行：

   npx nuxt-users migrate
   

4. 少なくとも 1 ユーザーを作成

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

   フラグ：-e メール、-n 名前、-p パスワード、-r ロール（オプション）。

5. パーミッションを設定（保護されたルートで必須） auth.permissions がない場合、認証されたユーザーは保護されたルートにアクセスできません。早期設定を推奨します：

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

6. ページでログインを使用

   • NUsersLoginForm コンポーネントを使用し、@success で useAuthentication() から login(user) を呼び出します。
   • オプションでログイン後にリダイレクト（例：navigateTo('/')）できます。

設定リファレンス（nuxt.config.ts）

すべてのオプションは nuxt.config.ts の nuxtUsers 下にあります。

領域	キー	注記
データベース	connector.name	'sqlite' | 'mysql' | 'postgresql'
データベース	connector.options	path（SQLite）、または host、port、user、password、database（MySQL/PostgreSQL）
API	apiBasePath	デフォルト '/api/nuxt-users'
テーブル	tables.users、tables.personalAccessTokens、tables.passwordResetTokens、tables.migrations	カスタムテーブル名
メーラー	mailer	パスワードリセットメール用の Nodemailer 設定
URL	passwordResetUrl、emailConfirmationUrl	リダイレクト用パス
認証	auth.whitelist	公開ルート（例：['/register']）; /login は常に公開
認証	auth.tokenExpiration	分（デフォルト 1440）
認証	auth.rememberMeExpiration	日（デフォルト 30）
認証	auth.permissions	ロール → パス（例：admin: ['*']、user: ['/profile']）
認証	auth.google	Google OAuth：clientId、clientSecret、callbackUrl など
パスワード	passwordValidation	minLength、requireUppercase、requireLowercase、requireNumbers、requireSpecialChars、preventCommonPasswords
データ	hardDelete	true = 物理削除、false = 論理削除（デフォルト）
ロケール	locale.default、locale.texts、locale.fallbackLocale	ローカライゼーション

ランタイム設定もサポートされます：環境ベースまたはサーバーのみの設定には runtimeConfig.nuxtUsers を使用します。CLI は プロジェクトルート から loadNuxt が成功したときそれをマージします。loadNuxt が失敗した場合（nuxt.config がない、出力のみのデプロイ、または --omit=dev の下に nuxt/@nuxt/kit がない）、CLI は DB_* 環境変数および他のオプションの デフォルト にフォールバックします — 設定からのカスタム tables / passwordValidation は適用されないかもしれません。docs/user-guide/configuration.md（CLI セクション）を参照してください。

CLI コマンド

プロジェクトルートから実行して、nuxt.config.ts（およびオプションで .env）が検出されるようにしてください。

• マイグレーション

  npx nuxt-users migrate
  

• ユーザー作成

  npx nuxt-users create-user -e <email> -n "<name>" -p <password> [-r <role>]
  

• レガシー/テーブル作成（古いセットアップで必要な場合）

  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
  

本番環境： CLI は .output/ のみに含まれていません；Node を実行する場所に nuxt-users（およびピア）がインストールされている必要があります。npx は不在の場合パッケージをダウンロードする場合があります。package.json スクリプト（"nuxt-users": "nuxt-users"）はローカルバイナリを使用します。完全な設定 には nuxt.config とリゾルバブルな @nuxt/kit を備えたアプリルートが必要です；ビルドのみまたは omit=dev デプロイはしばしば 環境フォールバック（DB_*）に当たります — 設定ドキュメントを参照してください。

コンポーザブル（自動インポート）

• useAuthentication() — user、isAuthenticated、login(user, rememberMe?)、logout()、fetchUser(useSSR?)、initializeUser()
• useUsers() — 管理者：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

コンポーネント

• NUsersLoginForm — ログインフォーム；@success を使用して useAuthentication() から login(user) を呼び出します
• NUsersLogoutLink — ログアウトリンク/ボタン
• NUsersProfileInfo — プロフィール表示
• NUsersResetPasswordForm — パスワードリセットフォーム
• NUsersList — ユーザーリスト表示（管理者）
• NUsersUserForm — ユーザー作成/編集フォーム

よくあるエッジケース

1. ユーザーが保護されたルートでログインページにリダイレクトされる
   nuxtUsers.auth.permissions を設定して、各ロールが必要なルートにアクセスできるようにします（例：admin: ['*']、user: ['/profile']）。

2. CLI が設定が見つからないと言う、または間違ったテーブル/パスワードルールを使用する
   nuxt.config を含むディレクトリから CLI を実行します。.output/ のみをデプロイするか、本番環境で nuxt を除外して実行する場合、loadNuxt は失敗し、CLI は DB_* フォールバックと非コネクタオプションの デフォルト を使用します。DB_* を設定するか（ドキュメントを参照）、完全なアプリチェックアウトで CI から CLI を実行します。

3. マイグレーションテーブルがない
   プロジェクトルートから npx nuxt-users migrate を一度実行します。マイグレーションテーブルがない場合、モジュールは実行時に警告します。

4. パスワード検証が厳しすぎる
   nuxtUsers.passwordValidation を調整します（例：minLength を下げる、requireUppercase/requireNumbers/requireSpecialChars を false に設定）。良い理由なく本番環境で全てのチェックを無効化しないでください。

5. データベースドライバーエラー
   正しいピアをインストールします：SQLite → better-sqlite3、MySQL → mysql2、PostgreSQL → pg。connector.name と connector.options がドライバーと環境（例：正しいホスト、ポート、認証情報）に一致することを確認します。

6. Google OAuth
   nuxtUsers.auth.google を clientId、clientSecret、およびオプションで callbackUrl、successRedirect、errorRedirect、scopes、allowAutoRegistration で設定します。

ファイルリファレンス

• プロジェクト LLM コンテキストと設定タイプ：リポルートの llms.txt
• 完全なドキュメント：https://nuxt-users.webmania.cc/
• はじめに例：../../docs/user-guide/getting-started.md、../../docs/examples/basic-setup.md
• 認可：../../docs/user-guide/authorization.md
• 設定詳細：../../docs/user-guide/configuration.md

nuxtUsers の設定とパーミッションをアプリのロールとルートと同期に保つ；カスタム認証ロジックを実装する際はガード句と早期リターンを使用します。