convex-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add sign-in to the app

为应用添加登录功能

Install and wire @convex-dev/auth for the current app: a provider (passkeys by default, or OAuth/password), the server config, the client hooks, and a sign-in UI — correctly, including the auth.config.ts that's the #1 real-world auth footgun.

为当前应用安装并配置@convex-dev/auth：包括身份验证提供商（默认Passkeys，也可选择OAuth/密码登录）、服务端配置、客户端钩子以及登录UI — 确保配置正确，尤其是auth.config.ts，这是实际开发中身份验证最容易踩坑的部分。

Workflow

操作流程

Install @convex-dev/auth (pinned build) and add it to convex.config.ts. With pnpm, also
```
pnpm add jose
```
(it won't hoist otherwise); you need it for step 3.
Add the provider in convex/auth.ts (Passkey by default; Password or OAuth like Google on request).
Generate the auth keys HEADLESSLY. Do NOT run the interactive
```
npx @convex-dev/auth
```
wizard: it needs a login/TTY and hangs in non-interactive, anonymous, or CI runs (the #1 auth time-sink). Generate JWT_PRIVATE_KEY + JWKS deterministically with
```
jose
```
: 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 Then set JWT_PRIVATE_KEY and JWKS (from .auth-keys.json) plus SITE_URL on the deployment. Prefer the Convex MCP
```
envSet
```
tool, one call per var, to avoid shell-quoting the multi-line key. CLI fallback: use the NAME=VALUE form (
```
npx convex env set "JWT_PRIVATE_KEY=$JWT"
```
), NEVER
```
env set JWT_PRIVATE_KEY "$JWT"
```
(the value starts with
```
-----BEGIN
```
and the CLI parses the leading
```
-
```
as an unknown flag). SITE_URL is the dev URL (e.g. http://localhost:3000). Delete .auth-keys.json after.
Write convex/auth.config.ts (the silently-always-signed-out bug lives here if it's wrong).
Wire the client: ConvexAuthProvider, the sign-in component, and route guards. If you import shadcn/ui primitives (button, input, textarea, label, and so on), add them first with
```
npx shadcn@latest add <name>
```
; a missing @/components/ui/* is a hard build error.
Verify a sign-in round-trips before declaring done.

安装@convex-dev/auth（固定版本）并将其添加到convex.config.ts中。如果使用pnpm，还需执行
```
pnpm add jose
```
（否则无法正确提升依赖）；后续步骤3需要用到该依赖。
在convex/auth.ts中添加身份验证提供商（默认使用Passkey；若需密码或Google等OAuth登录可按需配置）。
无交互生成身份验证密钥。请勿运行交互式的
```
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 然后在部署环境中设置JWT_PRIVATE_KEY、JWKS（来自.auth-keys.json）以及SITE_URL。优先使用Convex MCP的
```
envSet
```
工具，每个变量单独调用一次，避免多行密钥的shell转义问题。如果使用CLI作为备选：请使用NAME=VALUE格式（
```
npx convex env set "JWT_PRIVATE_KEY=$JWT"
```
），绝对不要使用
```
env set JWT_PRIVATE_KEY "$JWT"
```
（因为密钥以
```
-----BEGIN
```
开头，CLI会将开头的
```
-
```
解析为未知参数）。SITE_URL为开发环境地址（例如http://localhost:3000）。完成后删除.auth-keys.json。
编写convex/auth.config.ts（如果配置错误，会导致应用静默保持未登录状态且无错误提示）。
配置客户端：ConvexAuthProvider、登录组件以及路由守卫。如果要导入shadcn/ui基础组件（button、input、textarea、label等），请先执行
```
npx shadcn@latest add <name>
```
安装；缺少@/components/ui/*会导致构建失败。
验证登录流程完整可用后再完成配置。

Rules

规则

Generate JWT_PRIVATE_KEY/JWKS with
```
jose
```
(extractable RS256; PKCS8 newlines to spaces; JWKS = {keys:[{use:"sig", ...publicJwk}]}). Do NOT run the interactive
```
npx @convex-dev/auth
```
wizard: it hangs headless/anonymous. Set the vars via the MCP
```
envSet
```
tool or the NAME=VALUE CLI form.
Always write auth.config.ts: a missing/incorrect one makes the app silently always-signed-out with no error.
Passkeys by default; only switch to password/OAuth on explicit request.
Install any shadcn/ui primitive you import up front (
```
npx shadcn@latest add ...
```
); a missing @/components/ui/* is a hard build failure.
Verify a real sign-in works before finishing.

使用
```
jose
```
生成JWT_PRIVATE_KEY/JWKS（可提取的RS256算法；将PKCS8格式的换行符替换为空格；JWKS格式为{keys:[{use:"sig", ...publicJwk}]}）。请勿运行交互式
```
npx @convex-dev/auth
```
向导：它在无交互/匿名环境中会挂起。通过MCP的
```
envSet
```
工具或NAME=VALUE格式的CLI设置变量。
务必编写auth.config.ts：缺失或配置错误会导致应用静默保持未登录状态且无错误提示。
默认使用Passkeys；仅在明确要求时切换为密码/OAuth登录。
提前安装所有要导入的shadcn/ui基础组件（
```
npx shadcn@latest add ...
```
）；缺少@/components/ui/*会导致构建失败。
完成前务必验证实际登录功能可用。