@proteles/react
v0.1.1
Published
Drop-in React components and hooks (SignInButton, UserButton, SignedIn/SignedOut, useUser, Protect) for the Proteles identity platform. Talks to the @proteles/next BFF, never to the authorization server directly.
Maintainers
aaron_Readme
@proteles/react
Drop-in React components and hooks for Proteles authentication.
They talk only to the @proteles/next BFF's /api/auth/* routes —
never to the authorization server directly — so no secrets or tokens ever reach
the browser. Pair this with @proteles/next in the same app.
Install
npm install @proteles/react @proteles/next @proteles/jsThe five-minute setup
// app/layout.tsx
import { AuthProvider } from "@proteles/react";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<AuthProvider>{children}</AuthProvider>
</body>
</html>
);
}// app/page.tsx
"use client";
import { SignedIn, SignedOut, SignInButton, UserButton, useUser } from "@proteles/react";
export default function Home() {
const { user } = useUser();
return (
<>
<SignedOut>
<SignInButton />
</SignedOut>
<SignedIn>
Hi {user?.email} <UserButton />
</SignedIn>
</>
);
}That's it — <AuthProvider> fetches /api/auth/me, and the components react to
the result.
API
<AuthProvider>
Wrap your app once. Props:
basePath?— the BFF mount path. Defaults toNEXT_PUBLIC_PROTELES_BASE_PATHor/api/auth.initialUser?— a server-known user (fromcurrentUser()in@proteles/next) to avoid a signed-out flash on first paint.undefined= fetch on mount,null= known signed-out, an object = known signed-in.
Hooks
useUser()→{ user, isLoading, isAuthenticated }.useAuth()→ the above plussignIn(opts?),signOut(opts?),reload(),basePath.
Components
| Component | Renders |
| --- | --- |
| <SignedIn> | children when a user is signed in |
| <SignedOut> | children when no user is signed in |
| <Protect fallback={…}> | children when signed in, else fallback (nothing while loading) |
| <SignInButton returnTo? connection?> | a button that starts login (connection picks a social provider, e.g. "google") |
| <SignOutButton returnTo?> | a button that logs out |
| <UserButton> | the user's name/email + a sign-out control |
SignInButton/SignOutButton/UserButton are unstyled by design — pass
className and style them to match your app.
Notes
- All components are client components (
"use client"). Import them into client components, or render them inside your<AuthProvider>tree. useUser/useAuththrow if used outside<AuthProvider>— a clear error instead of a silent null.- Auth failures degrade to the signed-out state; the components never throw on a network error.
Develop
npm install # from the sdk/ workspace root
npm run build # tsc -> dist (preserves the "use client" directives)
npm test # tsx + node:test (pure logic + react-dom/server render tests)