convex-auth

アプリにサインインを追加する

現在のアプリに @convex-dev/auth をインストールして接続します。デフォルトではパスキーを使用し、必要に応じて OAuth／パスワードに切り替えます。プロバイダー、サーバー設定、クライアントフック、サインイン UI を正しく設定してください。特に、実際の認証で最もよくある落とし穴である auth.config.ts も忘れずに設定します。

ワークフロー

1. @convex-dev/auth（固定ビルド）をインストールし、convex.config.ts に追加します。pnpm の場合は pnpm add jose も実行してください（それ以外ではホイストされないため）。ステップ 3 で必要になります。
2. convex/auth.ts にプロバイダーを追加します（デフォルトは Passkey。リクエストがあれば Password または Google などの OAuth）。
3. 認証キーをヘッドレスで生成します。対話型の npx @convex-dev/auth ウィザードは実行しないでください。ログイン／TTY が必要で、非対話、匿名、または CI の実行ではハングします（認証で最も時間を浪費する原因です）。jose を使って JWT_PRIVATE_KEY + JWKS を決定論的に生成します。 node -e 'import("jose").then(async({generateKeyPair,exportPKCS8,exportJWK})=>{const k=await generateKeyPair("RS256",{extractable:true});const priv=await exportPKCS8(k.privateKey);const pub=await exportJWK(k.publicKey);process.stdout.write(JSON.stringify({JWT_PRIVATE_KEY:priv.trimEnd().replace(/\n/g," "),JWKS:JSON.stringify({keys:[{use:"sig",...pub}]})}))})' > .auth-keys.json 次に、.auth-keys.json の JWT_PRIVATE_KEY と JWKS、および SITE_URL をデプロイ先に設定します。複数行のキーをシェルで引用するのを避けるため、Convex MCP の envSet ツールを変数ごとに 1 回呼び出す方法を推奨します。CLI を使う場合は NAME=VALUE 形式（npx convex env set "JWT_PRIVATE_KEY=$JWT"）を使用してください。env set JWT_PRIVATE_KEY "$JWT" は絶対に使わないでください（値は -----BEGIN で始まり、CLI が先頭の - を未知のフラグとして解析します）。SITE_URL は開発用 URL（例：http://localhost:3000）です。作成後、.auth-keys.json を削除します。
4. convex/auth.config.ts を作成します（誤っていると、常にサインアウト状態になる不具合が気づかれないまま発生します）。
5. クライアントを接続します。ConvexAuthProvider、サインインコンポーネント、ルートガードを追加します。shadcn/ui のプリミティブ（button、input、textarea、label など）をインポートする場合は、まず npx shadcn@latest add <name> で追加してください。@/components/ui/* が存在しないとビルドエラーになります。
6. 完了とする前に、サインインが往復して正常に動作することを確認します。

ルール

• jose を使って JWT_PRIVATE_KEY／JWKS を生成します（extractable な RS256、PKCS8 の改行はスペースに置換、JWKS = {keys:[{use:"sig", ...publicJwk}]}）。対話型の npx @convex-dev/auth ウィザードは実行しないでください。ヘッドレス／匿名の実行ではハングします。変数は MCP の envSet ツール、または NAME=VALUE 形式の CLI で設定します。
• 必ず auth.config.ts を作成してください。これがない、または設定が誤っていると、エラーなしで常にサインアウト状態になります。
• デフォルトはパスキーです。パスワード／OAuth に切り替えるのは、明示的なリクエストがあった場合のみです。
• インポートする shadcn/ui のプリミティブは、事前に npx shadcn@latest add ... で追加してください。@/components/ui/* が存在しないとビルドに失敗します。
• 完了前に、実際のサインインが正常に動作することを確認してください。