@55387.ai/uniauth-react

Official React SDK for UniAuth SSO integration. UniAuth 官方 React SDK，用于 SSO 集成。

Features / 功能

• 🔐 SSO Integration / SSO 集成: PKCE authorization code flow with auto-callback handling / 自动处理 PKCE 授权码流程
• 🔄 Reactive State / 响应式状态: user, isAuthenticated, isLoading hooks
• 🛡️ TypeScript: Full type-safe API / 完整类型安全
• 🍪 Token Management / Token 管理: Auto token storage & refresh / 自动存储与刷新

Installation / 安装

npm install @55387.ai/uniauth-react @55387.ai/uniauth-client

Quick Start / 快速开始

1. Configure Provider / 配置 Provider

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { UniAuthProvider, type UniAuthProviderConfig } from '@55387.ai/uniauth-react';
import App from './App';

const config: UniAuthProviderConfig = {
  baseUrl: import.meta.env.VITE_UNIAUTH_BASE_URL || 'https://sso.55387.xyz',
  clientId: import.meta.env.VITE_UNIAUTH_CLIENT_ID,
  redirectUri: window.location.origin + '/callback',
  sso: {
    ssoUrl: 'https://sso.55387.xyz',
    clientId: import.meta.env.VITE_UNIAUTH_CLIENT_ID, // Required / 必填
    redirectUri: window.location.origin + '/callback', // Required / 必填
    usePKCE: true,
  }
};

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <UniAuthProvider config={config} loadingComponent={<div>Loading...</div>}>
      <App />
    </UniAuthProvider>
  </React.StrictMode>
);

[!IMPORTANT] The sso configuration object is REQUIRED if you intend to use the login() method from useUniAuth(). 如果您打算使用 useUniAuth() 中的 login() 方法，sso 配置对象是 必须 的。

2. Use the Hook / 使用 Hook

import { useUniAuth } from '@55387.ai/uniauth-react';

export const LoginButton = () => {
  const { user, isAuthenticated, isLoading, login, logout } = useUniAuth();

  if (isLoading) return <div>Checking session...</div>;

  if (isAuthenticated && user) {
    return (
      <div>
        <img src={user.avatar_url} alt={user.nickname} />
        <span>Welcome, {user.nickname}!</span>
        <button onClick={() => logout()}>Logout</button>
      </div>
    );
  }

  return <button onClick={() => login()}>Login with SSO</button>;
};

API Reference

useUniAuth() Hook

Returns UniAuthContextType:

| Property / 属性 | Type / 类型 | Description / 描述 | |---|---|---| | user | UserInfo \| null | Current user info / 当前用户信息 | | isAuthenticated | boolean | Auth status / 认证状态 | | isLoading | boolean | Loading state / 加载状态 | | error | Error \| null | Error state / 错误状态 | | login(options?) | (opts?) => void | Start SSO login / 发起 SSO 登录 | | logout() | () => Promise<void> | Logout / 退出登录 | | updateProfile(updates) | (updates) => Promise<void> | Update profile (nickname, avatar) / 更新资料 | | client | UniAuthClient | Raw client instance / 原始客户端实例 | | getToken() | () => string \| null | Get access token synchronously / 同步获取 Token |

login() Options

login({ usePKCE: true, usePopup: false });

| Option | Default | Description / 描述 | |---|---|---| | usePKCE | true | Use PKCE flow (recommended for SPA) / 使用 PKCE 流程 | | usePopup | false | Open login in popup / 弹窗登录 |

Advanced Usage / 高级用法

Getting Access Token / 获取 Access Token

const { getToken } = useUniAuth();

const callApi = async () => {
  const token = getToken();
  if (!token) return;

  const res = await fetch('/api/protected', {
    headers: { Authorization: `Bearer ${token}` }
  });
};

Update User Profile / 更新用户资料

const { updateProfile } = useUniAuth();

await updateProfile({ nickname: 'New Name' });

Access Raw Client / 访问原始客户端

const { client } = useUniAuth();

// Use any UniAuthClient method directly
// 直接使用 UniAuthClient 的任何方法
await client.sendCode('+8613800138000');
const result = await client.loginWithCode('+8613800138000', '123456');

Environment Variables / 环境变量

VITE_UNIAUTH_BASE_URL=https://sso.55387.xyz
VITE_UNIAUTH_CLIENT_ID=your-client-id

Troubleshooting / 故障排查

invalid_client Error

• Check clientId matches Console exactly / 检查 clientId 是否与控制台完全一致
• Check redirectUri matches Console exactly / 检查 redirectUri 是否与控制台完全一致

404 on Callback / 回调 404

• Ensure React Router handles /callback route / 确保路由处理了 /callback 路径
• Configure Nginx: try_files $uri /index.html

CORS Errors / 跨域错误

• Add your domain to CORS_ORIGINS on SSO Server / 在 SSO 服务器添加域名到 CORS_ORIGINS
• Or configure Nginx proxy: /api/uni-auth/ → SSO Server / 或配置 Nginx 代理

🤖 AI Agent Prompts / AI 智能体提示词

This package includes an AI-ready integration prompt. Copy it into your AI coding assistant (Claude, Cursor, Copilot, etc.) to generate a complete UniAuth integration automatically.

本包附带 AI 集成提示词。将其复制到 AI 编程助手中，即可自动生成完整的 UniAuth 集成代码。

# After install, find the prompt at:
# 安装后，提示词文件位于：
cat node_modules/@55387.ai/uniauth-react/ai-prompts/react-nextjs.md

[!TIP] Replace placeholders like YOUR_UNIAUTH_URL and YOUR_CLIENT_ID before pasting into your AI assistant. 粘贴到 AI 助手前，请替换 YOUR_UNIAUTH_URL 和 YOUR_CLIENT_ID 等占位符。

See all prompts: docs/ai-prompts/