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：身份验证 provider（默认使用 Passkeys，或 OAuth/password）、服务器配置、客户端 hooks 和登录 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 中添加 provider（默认使用 Passkey；按需使用 Password 或 OAuth，例如 Google）。
无头生成 auth 密钥。不要运行交互式
```
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 对多行 key 进行引号处理。CLI 备选方案：使用 NAME=VALUE 形式（
```
npx convex env set "JWT_PRIVATE_KEY=$JWT"
```
），绝不要使用
```
env set JWT_PRIVATE_KEY "$JWT"
```
（该值以
```
-----BEGIN
```
开头，CLI 会将前导
```
-
```
解析为未知 flag）。SITE_URL 是开发 URL（例如 http://localhost:3000）。完成后删除 .auth-keys.json。
编写 convex/auth.config.ts；如果该文件有误，就会触发无报错但始终处于未登录状态的 bug。
配置客户端：ConvexAuthProvider、登录组件和路由守卫。如果要导入 shadcn/ui primitives（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；仅在明确要求时切换为 Password/OAuth。
提前安装所有要导入的 shadcn/ui primitives（
```
npx shadcn@latest add ...
```
）；缺少 @/components/ui/* 会导致构建失败。
完成前验证真实登录流程可用。