@authon/react 0.2.1 → 0.3.1

package/README.ko.md

@@ -0,0 +1,95 @@
+[English](./README.md) | **한국어**
+
+# @authon/react
+
+> React 인증 훅 및 컴포넌트 -- 셀프 호스팅 Clerk 대안, Auth0 대안
+
+## 설치
+
+```bash
+npm install @authon/react
+```
+
+## 빠른 시작
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { AuthonProvider, useAuthon, useUser, SignedIn, SignedOut, UserButton } from '@authon/react';
+
+function App() {
+  const { openSignIn, signOut } = useAuthon();
+  const { user } = useUser();
+
+  return (
+    <div>
+      <SignedOut>
+        <button onClick={() => openSignIn()}>로그인</button>
+      </SignedOut>
+      <SignedIn>
+        <p>환영합니다, {user?.email}</p>
+        <UserButton />
+      </SignedIn>
+    </div>
+  );
+}
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <AuthonProvider publishableKey="pk_live_..." config={{ apiUrl: 'https://your-authon-server.com' }}>
+    <App />
+  </AuthonProvider>
+);
+```
+
+## 주요 작업
+
+### Google OAuth 로그인
+
+```tsx
+const { client } = useAuthon();
+<button onClick={() => client?.signInWithOAuth('google')}>Google로 로그인</button>
+```
+
+### 라우트 보호
+
+```tsx
+import { Protect } from '@authon/react';
+
+<Protect fallback={<p>로그인이 필요합니다.</p>}>
+  <Dashboard />
+</Protect>
+```
+
+### 현재 사용자
+
+```tsx
+const { user, isLoading } = useUser();
+```
+
+### 로그아웃
+
+```tsx
+const { signOut } = useAuthon();
+<button onClick={() => signOut()}>로그아웃</button>
+```
+
+## 환경 변수
+
+| 변수 | 필수 | 설명 |
+|------|------|------|
+| `AUTHON_API_URL` | Yes | Authon 서버 URL |
+| `AUTHON_PUBLISHABLE_KEY` | Yes | 프로젝트 퍼블리셔블 키 |
+
+## 비교
+
+| 기능 | Authon | Clerk | Auth.js |
+|------|--------|-------|---------|
+| 셀프 호스팅 | Yes | No | 부분적 |
+| 가격 | 무료 | $25/월+ | 무료 |
+| ShadowDOM 모달 | Yes | No | No |
+| MFA/패스키 | Yes | Yes | 플러그인 |
+| Web3 인증 | Yes | No | No |
+
+## 라이선스
+
+MIT

package/README.md

@@ -1,137 +1,220 @@
+**English** | [한국어](./README.ko.md)
+
 # @authon/react
 
-React SDK for [Authon](https://authon.dev) — Provider, hooks, and pre-built components.
+> Drop-in React authentication with hooks and components — self-hosted Clerk alternative, Auth0 alternative, open-source auth
+
+[![npm version](https://img.shields.io/npm/v/@authon/react?color=6d28d9)](https://www.npmjs.com/package/@authon/react)
+[![License](https://img.shields.io/badge/license-MIT-blue)](../../LICENSE)
+
+## Prerequisites
+
+Before installing the SDK, create an Authon project and get your API keys:
+
+1. **Create a project** at [Authon Dashboard](https://authon.dev/dashboard/overview)
+   - Click "Create Project" and enter your app name
+   - Select the authentication methods you want (Email/Password, OAuth providers, etc.)
+
+2. **Get your API keys** from Project Settings → API Keys
+   - **Publishable Key** (`pk_live_...` or `pk_test_...`) — safe to use in client-side code
+   - **Secret Key** (`sk_live_...` or `sk_test_...`) — server-side only, never expose to clients
+
+3. **Configure OAuth providers** (optional) in Project Settings → OAuth
+   - Add Google, Apple, GitHub, etc. with their respective Client ID and Secret
+   - Set the redirect URL to `https://api.authon.dev/v1/auth/oauth/redirect`
+
+> **Test vs Live keys:** Use `pk_test_...` during development. Switch to `pk_live_...` before deploying to production. Test keys use a sandbox environment with no rate limits.
 
 ## Install
 
 ```bash
 npm install @authon/react
-# or
-pnpm add @authon/react
 ```
 
-Requires `react >= 18.0.0`.
-
 ## Quick Start
 
 ```tsx
-import {
-  AuthonProvider,
-  SignedIn,
-  SignedOut,
-  UserButton,
-  useUser,
-  useAuthon,
-} from '@authon/react';
+// src/main.tsx — complete working file
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { AuthonProvider, useAuthon, useUser, SignedIn, SignedOut, UserButton } from '@authon/react';
 
 function App() {
-  return (
-    <AuthonProvider publishableKey="pk_live_...">
-      <Header />
-      <Main />
-    </AuthonProvider>
-  );
-}
+  const { openSignIn, signOut } = useAuthon();
+  const { user } = useUser();
 
-function Header() {
   return (
-    <nav>
+    <div>
+      <SignedOut>
+        <button onClick={() => openSignIn()}>Sign In</button>
+      </SignedOut>
       <SignedIn>
+        <p>Welcome, {user?.email}</p>
         <UserButton />
+        <button onClick={() => signOut()}>Sign Out</button>
       </SignedIn>
-      <SignedOut>
-        <SignInButton />
-      </SignedOut>
-    </nav>
+    </div>
   );
 }
 
-function SignInButton() {
-  const { openSignIn } = useAuthon();
-  return <button onClick={() => openSignIn()}>Sign In</button>;
-}
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <AuthonProvider
+    publishableKey="pk_live_YOUR_PUBLISHABLE_KEY"
+    config={{ apiUrl: 'https://your-authon-server.com' }}
+  >
+    <App />
+  </AuthonProvider>
+);
+```
 
-function Main() {
-  const { user, isLoading } = useUser();
-  if (isLoading) return <p>Loading...</p>;
-  if (!user) return <p>Please sign in.</p>;
-  return <h1>Welcome, {user.displayName}</h1>;
+## Common Tasks
+
+### Add Google OAuth Login
+
+```tsx
+import { useAuthon } from '@authon/react';
+
+function GoogleLoginButton() {
+  const { client } = useAuthon();
+  return (
+    <button onClick={() => client?.signInWithOAuth('google')}>
+      Sign in with Google
+    </button>
+  );
 }
 ```
 
-## API Reference
+### Protect a Route
+
+```tsx
+import { Protect } from '@authon/react';
+
+function Dashboard() {
+  return (
+    <Protect fallback={<p>Please sign in to view this page.</p>}>
+      <h1>Dashboard</h1>
+    </Protect>
+  );
+}
 
-### `<AuthonProvider>`
+// With role-based condition
+function AdminPanel() {
+  return (
+    <Protect
+      condition={(user) => user.publicMetadata?.role === 'admin'}
+      fallback={<p>Admin access required.</p>}
+    >
+      <h1>Admin Panel</h1>
+    </Protect>
+  );
+}
+```
 
-Wraps your app and provides auth context.
+### Get Current User
 
 ```tsx
-<AuthonProvider
-  publishableKey="pk_live_..."
-  config={{
-    apiUrl: 'https://api.authon.dev',
-    theme: 'auto',
-    locale: 'en',
-    appearance: { primaryColorStart: '#7c3aed' },
-  }}
->
-  {children}
-</AuthonProvider>
+import { useUser } from '@authon/react';
+
+function Profile() {
+  const { user, isLoading } = useUser();
+  if (isLoading) return <p>Loading...</p>;
+  if (!user) return <p>Not signed in</p>;
+  return (
+    <div>
+      <p>Email: {user.email}</p>
+      <p>Name: {user.displayName}</p>
+    </div>
+  );
+}
 ```
 
-### Hooks
+### Add Email/Password Auth
+
+```tsx
+import { useAuthon } from '@authon/react';
+import { useState } from 'react';
+
+function EmailSignIn() {
+  const { client } = useAuthon();
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
 
-#### `useAuthon()`
-
-Returns the full auth context:
-
-```ts
-const {
-  isSignedIn,  // boolean
-  isLoading,   // boolean
-  user,        // AuthonUser | null
-  signOut,     // () => Promise<void>
-  openSignIn,  // () => Promise<void>
-  openSignUp,  // () => Promise<void>
-  getToken,    // () => string | null
-  client,      // Authon instance
-} = useAuthon();
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    await client?.signInWithEmail(email, password);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
+      <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" />
+      <button type="submit">Sign In</button>
+    </form>
+  );
+}
 ```
 
-#### `useUser()`
+### Handle Sign Out
 
-Shorthand for user data:
+```tsx
+import { useAuthon } from '@authon/react';
 
-```ts
-const { user, isLoading } = useUser();
+function SignOutButton() {
+  const { signOut } = useAuthon();
+  return <button onClick={() => signOut()}>Sign Out</button>;
+}
 ```
 
-### Components
+## Environment Variables
 
-| Component | Props | Description |
-|-----------|-------|-------------|
-| `<SignedIn>` | `children` | Renders children only when signed in |
-| `<SignedOut>` | `children` | Renders children only when signed out |
-| `<UserButton>` | none | Avatar dropdown with sign-out action |
-| `<SignIn>` | `mode?` | Opens sign-in modal or renders embedded form |
-| `<SignUp>` | `mode?` | Opens sign-up modal or renders embedded form |
-| `<Protect>` | `fallback?`, `condition?` | Guards content, optionally with a custom condition |
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AUTHON_API_URL` | Yes | Your Authon server URL |
+| `AUTHON_PUBLISHABLE_KEY` | Yes | Project publishable key (`pk_live_...` or `pk_test_...`) |
 
-### `<Protect>` Example
+## API Reference
 
-```tsx
-<Protect
-  fallback={<p>You need admin access.</p>}
-  condition={(user) => user.publicMetadata?.role === 'admin'}
->
-  <AdminPanel />
-</Protect>
-```
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `<AuthonProvider>` | Context provider. Props: `publishableKey`, `config?` |
+| `<SignIn>` | Pre-built sign-in form (`mode="popup"` or `"embedded"`) |
+| `<SignUp>` | Pre-built sign-up form |
+| `<UserButton>` | Avatar dropdown with user info and sign-out |
+| `<UserProfile>` | Full user profile management |
+| `<SignedIn>` | Renders children only when signed in |
+| `<SignedOut>` | Renders children only when signed out |
+| `<Protect>` | Conditional render with `fallback` and `condition` |
+| `<SocialButton>` | Single OAuth provider button |
+| `<SocialButtons>` | All enabled OAuth provider buttons |
 
-## Documentation
+### Hooks
 
-[authon.dev/docs](https://authon.dev/docs)
+| Hook | Returns |
+|------|---------|
+| `useAuthon()` | `{ isSignedIn, isLoading, user, signOut, openSignIn, openSignUp, getToken, client }` |
+| `useUser()` | `{ user, isLoading }` |
+| `useAuthonMfa()` | MFA setup, verification, and management |
+| `useAuthonPasskeys()` | Passkey registration and authentication |
+| `useAuthonPasswordless()` | Magic link and email OTP |
+| `useAuthonWeb3()` | Web3 wallet sign-in and management |
+| `useAuthonSessions()` | List and revoke active sessions |
+| `useOrganization()` | Active organization management |
+| `useOrganizationList()` | List and switch organizations |
+
+## Comparison
+
+| Feature | Authon | Clerk | Auth.js |
+|---------|--------|-------|---------|
+| Self-hosted | Yes | No | Partial |
+| Pricing | Free | $25/mo+ | Free |
+| OAuth providers | 10+ | 20+ | 80+ |
+| ShadowDOM modal | Yes | No | No |
+| MFA/Passkeys | Yes | Yes | Plugin |
+| Web3 auth | Yes | No | No |
+| Organizations | Yes | Yes | No |
 
 ## License
 
-[MIT](../../LICENSE)
+MIT