React 模式接入

@rootauth/react 为 React 18+ 提供 RootAuth hosted 完整认证页面，包括登录、注册、重置密码、MFA 和第三方登录。hosted 运行时和样式会按需加载，无需手动导入 CSS。

前置条件

在 RootAuth 工作台 创建应用，并复制 app_id（格式如 app_******）。

请在项目根目录的 .npmrc 文件中添加下面这行配置：

@rootauth:registry=http://gitlab.standard-software.co/api/v4/projects/12421/packages/npm/

1. 安装

@rootauth/react 将完整 RootAuth 认证页面封装为 React SDK，并依赖 React 18。

npm install @rootauth/react react react-dom

2. 初始化

RootAuthClient 接收 API、应用、OIDC、Hosted 路径和成功回调配置。客户端可传给 React 组件，也可通过命令式 API 挂载。

import { RootAuthClient } from '@rootauth/react'

export const rootAuth = new RootAuthClient({
  app_id: 'your-app-id',
  api_base_url: 'https://rootauth-api.rootauth.com',
  redirect_uri: window.location.origin,
  scope: ['openid'],
  base_path: '/auth',
})

3. 配置参数

配置对象统一控制应用标识、API 地址、回调地址、认证路径、语言和登录注册成功行为。

4. 使用 RootAuthMount

RootAuthMount 在 React 生命周期内创建 Hosted 应用，并在组件卸载时自动清理。组件接收已初始化的 RootAuth 客户端。

import { RootAuthMount } from '@rootauth/react'
import { rootAuth } from './rootauth'

export function AuthPage() {
  return (
    <RootAuthMount
      client={rootAuth}
      containerId="rootauth-sdk"
      className="auth-page"
      style={{ minHeight: '100vh' }}
    />
  )
}

RootAuthMount 参数：

组件会在 React 生命周期内自动创建和清理 Hosted 页面。

5. 路由

React Router 可通过通配路径承载 RootAuthMount，由 RootAuth 客户端根据 base_path 管理内部登录、注册和重置密码页面。

React 路由由宿主应用管理，在对应路由页面渲染 RootAuthMount 即可。需要共享的 hosted 路径列表时可调用：

import { getAuthRoutePaths } from '@rootauth/react'

const paths = getAuthRoutePaths('/auth')

getAuthRoutePaths('/auth') 返回 /auth、/auth/login、/auth/register、/auth/reset-password。宿主路由通常使用 /auth/* 承载 RootAuthMount。

登录和注册方式不通过客户端 type 配置，而由 RootAuth 后台应用开关决定。页面会按后台配置展示邮箱密码、邮箱验证码、手机号密码、手机号验证码或用户名密码方式。

6. 回调示例

onLoginSuccess 和 onRegisterSuccess 可接收成功结果并覆盖默认跳转。回调返回 false 时，SDK 不再执行后续默认导航。

const rootAuth = new RootAuthClient({
  app_id: 'your-app-id',
  onLoginSuccess(data) {
    console.log('登录成功', data)
    return false
  },
  onRegisterSuccess(data) {
    console.log('注册成功', data)
  },
})

7. Core 能力

React 客户端继承 Core API，可直接调用 login()、sendCode()、register()、resetPassword()、verifyLoginMfa()、logout() 和第三方登录方法。包同时重新导出 @rootauth/core 的类型及辅助函数。

9. 相关模式

• @rootauth/core：无 UI API
• @rootauth/web-components：框架无关表单组件
• @rootauth/vue：Vue 3 hosted 完整页面