nuxt-users

Nuxt Users スキル

初期設定

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 [email protected] -n "Admin User" -p password123 -r admin
   

   フラグ：-e はメールアドレス、-n は名前、-p はパスワード、-r はロール（任意）です。

5. 権限を設定する

   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.allowCustomRoles	デフォルトは false です。true の場合、作成／更新 API と NUsersUserForm では、permissions に記載されていないロールも受け付けます。空の permissions（ブートストラップ時）では、すでに任意のロールを受け付けます。
認証	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 コマンド

nuxt.config.ts（および任意で .env）を見つけられるように、プロジェクトのルートから実行してください。

• マイグレーション

  npx nuxt-users migrate
  

• ユーザーの作成

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

  auth.allowCustomRoles が true（または権限が空）でない限り、ロールは auth.permissions のキーと一致している必要があります。

• レガシー／テーブルの作成

  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 を実行する場所に nuxt-users（およびピア依存関係）がインストールされている必要があります。.output/ 内にはバンドルされません。完全な設定には nuxt.config を含むアプリのルートが必要です。ビルドのみのデプロイや --omit=dev を使ったデプロイでは、DB_* 環境変数にフォールバックします。docs/user-guide/configuration.md を参照してください。

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

• 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 — ログインフォーム。useAuthentication() の login(user) を呼び出すには @success を使用します
• NUsersLogoutLink — ログアウトリンク／ボタン
• NUsersProfileInfo — プロフィールを表示します
• NUsersResetPasswordForm — パスワードリセットフォーム
• NUsersList — ユーザー一覧（管理者向け）
• NUsersUserForm — ユーザーの作成／編集フォーム。ロールの選択肢は auth.permissions のキーから生成されます。カスタムの自由入力ロールを選択肢にするには、auth.allowCustomRoles: true を設定してください

トラブルシューティング

症状	対処法
保護されたルートでログイン画面にリダイレクトされる	各ロールが必要なルートにアクセスできるよう、auth.permissions を設定してください
CLI の設定が見つからない／テーブルが違う	nuxt.config があるディレクトリから CLI を実行してください。上記の本番環境に関する注記を参照してください
マイグレーションテーブルがない	プロジェクトのルートから npx nuxt-users migrate を実行してください
データベースドライバーのエラー	適切なピア依存関係をインストールしてください：SQLite → better-sqlite3、MySQL → mysql2、PostgreSQL → pg

ファイル参照

• プロジェクトの 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 の設定と権限は、アプリのロールやルートと同期させてください。カスタムの認証ロジックを実装する際は、ガード節と早期リターンを使用してください。