Authsome UI Overview

Authsome UI is a family of five JavaScript/TypeScript packages that provide authentication UI for any React, Next.js, or Vue application backed by an Authsome API. The packages are layered: each higher-level package builds on the one below it, and you choose the level of abstraction that fits your project.

Package architecture01

@authsome/ui-core          ← HTTP client, AuthManager, TypeScript types
        │
        ├── @authsome/ui-react     ← React hooks + headless render-prop components
        │           │
        │           ├── @authsome/ui-components  ← Styled auth forms (Radix + Tailwind)
        │           │
        │           └── @authsome/ui-nextjs      ← Next.js server utilities + Edge middleware
        │
        └── @authsome/ui-vue       ← Vue 3 composables (uses ui-core directly)

The five packages02

Package	Version	What it provides
`@authsome/ui-core`	—	`AuthManager` class, `AuthClient` HTTP client, TypeScript type definitions (`User`, `Session`, `Organization`, `AuthState`, etc.)
`@authsome/ui-react`	—	`AuthProvider`, `useAuth`, `useUser`, `useOrganizations`, `useSessionToken`, `useClientConfig`, headless `SignInForm`, `SignUpForm`, `MFAChallengeForm`, `AuthGuard`
`@authsome/ui-components`	—	40+ styled components built with Radix UI primitives and Tailwind CSS
`@authsome/ui-nextjs`	—	`getServerSession()` for RSC, `getClientConfig()` for auto-discovery, `createCookieStorage()`, `createAuthMiddleware()` for Edge, `createProxyHandler()` for API proxy, pre-built Next.js auth pages
`@authsome/ui-vue`	—	`createAuthPlugin()`, `useAuth`, `useUser`, `useOrganizations`, `useSessionToken` composables

Installation03

Install the packages appropriate for your framework:

React (headless hooks only):

npm install @authsome/ui-react @authsome/ui-core

React (headless + styled components):

npm install @authsome/ui-react @authsome/ui-core @authsome/ui-components

Next.js (full integration with styled components):

npm install @authsome/ui-nextjs @authsome/ui-react @authsome/ui-core @authsome/ui-components

Vue:

npm install @authsome/ui-vue @authsome/ui-core

Package comparison04

Feature	`ui-core`	`ui-react`	`ui-components`	`ui-nextjs`	`ui-vue`
TypeScript types	Yes	Re-exports	—	Re-exports	—
HTTP client (`AuthClient`)	Yes	Via context	—	Via context	Via composables
State management	`AuthManager`	`AuthProvider`	Uses React	Uses React	`createAuthPlugin`
Hooks / composables	—	Yes	—	Re-exports	Yes
Headless form components	—	Yes	—	Re-exports	—
Styled form components	—	—	Yes	—	—
Server session (`RSC`)	—	—	—	Yes	—
Client config (auto-discovery)	—	`useClientConfig`	—	`getClientConfig`	—
Edge middleware	—	—	—	Yes	—
API proxy handler	—	—	—	Yes	—
Cookie token storage	—	—	—	Yes	—

Core concepts05

AuthManager

AuthManager in @authsome/ui-core is the framework-agnostic state machine that manages authentication lifecycle. It:

Holds session tokens in memory by default; persistence to localStorage or cookies is opt-in (see the security note below)
Hydrates state on page load from stored tokens
Automatically refreshes tokens before expiry
Provides a synchronous getState() and a subscription API for reactive frameworks

import { AuthManager } from "@authsome/ui-core";

const manager = new AuthManager({
  baseURL: "https://api.example.com",
  // Defaults to in-memory. createLocalStorage() persists across reloads but
  // makes the refresh token readable by any script on the page — prefer
  // backend-set httpOnly cookies where you can.
  storage: createLocalStorage(),
});

await manager.initialize(); // Hydrate from storage
await manager.signIn({ email, password });

const state = manager.getState();
// state.status: "loading" | "authenticated" | "unauthenticated" | "error"

AuthClient

AuthClient in @authsome/ui-core is the typed HTTP client that talks to the Authsome API. It wraps all endpoints under /v1/auth:

import { AuthClient } from "@authsome/ui-core";

const client = new AuthClient({ baseURL: "https://api.example.com" });

// All methods are typed and return the exact Authsome API response shape.
const result = await client.signIn({ email, password });
const user = await client.getMe(sessionToken);
const orgs = await client.listOrganizations(sessionToken);

Quick start (React)06

import { AuthProvider, useAuth } from "@authsome/ui-react";
import { SignInForm, SignUpForm } from "@authsome/ui-components";

function App() {
  return (
    <AuthProvider baseURL="https://api.example.com">
      <Routes />
    </AuthProvider>
  );
}

function Dashboard() {
  const { user, isAuthenticated, signOut } = useAuth();

  if (!isAuthenticated) return <SignInForm />;

  return (
    <div>
      <p>Welcome, {user?.name}</p>
      <button onClick={signOut}>Sign out</button>
    </div>
  );
}