SDK

React SDK

Name: Authon
Author: Authon

@authon/react — Authon 的 React 组件和 Hooks。适用于 Create React App、Vite 及任何 React 18+ 项目。

npm: @authon/reactReact 18+TypeScript

安装

bash

npm install @authon/react

AuthonProvider

使用 AuthonProvider. 包裹您的应用根节点。所有 Hooks 和组件必须在此 Provider 内部渲染。

src/main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { AuthonProvider } from "@authon/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <AuthonProvider publishableKey="pk_live_your_publishable_key">
      <App />
    </AuthonProvider>
  </StrictMode>
);

Provider 属性

属性	类型	描述
publishableKey	string	Your pk_live_ or pk_test_ key from the dashboard
config.apiUrl	string?	Override the Authon API base URL
config.theme	'light' \| 'dark' \| 'auto'	Color theme for the modal (default: auto)
config.locale	string?	Locale string for the modal UI (default: en)
config.appearance	Partial<BrandingConfig>?	Override branding config programmatically

Hooks

useAuthon()

用于与认证状态交互的主要 Hook。返回包含打开弹窗、获取令牌和退出登录方法的完整上下文值。

tsx

import { useAuthon } from "@authon/react";

function Header() {
  const {
    isSignedIn,
    isLoading,
    user,
    openSignIn,
    openSignUp,
    signOut,
    getToken,
  } = useAuthon();

  if (isLoading) return <Spinner />;

  return (
    <nav>
      {isSignedIn ? (
        <>
          <span>Hello, {user?.displayName}</span>
          <button onClick={() => signOut()}>Sign out</button>
        </>
      ) : (
        <button onClick={() => openSignIn()}>Sign in</button>
      )}
    </nav>
  );
}

useUser()

仅返回用户数据和加载状态的专注型 Hook。在仅需显示用户信息的组件中使用。

tsx

import { useUser } from "@authon/react";

function ProfileCard() {
  const { user, isLoading } = useUser();

  if (isLoading) return <Skeleton />;
  if (!user) return null;

  return (
    <div className="profile-card">
      {user.avatarUrl && (
        <img src={user.avatarUrl} alt={user.displayName ?? ""} />
      )}
      <h2>{user.displayName}</h2>
      <p>{user.email}</p>
      <span>Member since {new Date(user.createdAt).getFullYear()}</span>
    </div>
  );
}

组件

SignedIn / SignedOut

根据认证状态有条件地渲染子元素。这是构建认证感知 UI 而无需手动条件判断的最简单方式。

tsx

import { SignedIn, SignedOut } from "@authon/react";

function App() {
  return (
    <>
      <SignedIn>
        {/* Only rendered when user is signed in */}
        <Dashboard />
        <UserButton />
      </SignedIn>

      <SignedOut>
        {/* Only rendered when user is NOT signed in */}
        <LandingPage />
        <SignInButton />
      </SignedOut>
    </>
  );
}

触发 Authon 弹窗 UI。在 popup 模式下，弹窗在挂载时打开。在 embedded 模式下，表单内联渲染。

tsx

import { SignIn, SignUp } from "@authon/react";

// Popup — opens the modal when mounted
function LoginPage() {
  return <SignIn mode="popup" />;
}

// Embedded — renders a form container in-place
function SignUpPage() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <SignUp mode="embedded" />
    </div>
  );
}

UserButton

即插即用的头像按钮，带有退出登录下拉菜单。如有头像则显示，否则回退到带渐变背景的姓名首字母。未登录时返回 null 。

tsx

import { UserButton } from "@authon/react";

function AppHeader() {
  return (
    <header className="flex items-center justify-between p-4">
      <Logo />
      <UserButton />
    </header>
  );
}

受保护路由

将useAuthon()与 React Router 结合使用以保护私有路由：

components/ProtectedRoute.tsx

import { Navigate } from "react-router-dom";
import { useAuthon } from "@authon/react";

interface ProtectedRouteProps {
  children: React.ReactNode;
  redirectTo?: string;
}

export function ProtectedRoute({
  children,
  redirectTo = "/sign-in",
}: ProtectedRouteProps) {
  const { isSignedIn, isLoading } = useAuthon();

  if (isLoading) return <FullPageSpinner />;
  if (!isSignedIn) return <Navigate to={redirectTo} replace />;

  return <>{children}</>;
}

// Usage in router
const router = createBrowserRouter([
  { path: "/", element: <Home /> },
  {
    path: "/dashboard",
    element: (
      <ProtectedRoute>
        <Dashboard />
      </ProtectedRoute>
    ),
  },
]);

使用令牌

使用getToken() 将 JWT 附加到后端 API 调用：

tsx

import { useAuthon } from "@authon/react";

function useApi() {
  const { getToken } = useAuthon();

  const apiFetch = async (path: string, init?: RequestInit) => {
    const token = getToken();
    return fetch(`/api${path}`, {
      ...init,
      headers: {
        ...init?.headers,
        Authorization: token ? `Bearer ${token}` : "",
        "Content-Type": "application/json",
      },
    });
  };

  return { apiFetch };
}

// In a component
function OrdersList() {
  const { apiFetch } = useApi();
  const [orders, setOrders] = useState([]);

  useEffect(() => {
    apiFetch("/orders").then((r) => r.json()).then(setOrders);
  }, []);

  return <ul>{orders.map((o) => <li key={o.id}>{o.name}</li>)}</ul>;
}