npm - @insforge/nextjs - Versions diffs - 0.5.6 → 0.6.6 - Mend

@insforge/nextjs 0.5.6 → 0.6.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md CHANGED Viewed

@@ -1,44 +1,45 @@
 # @insforge/nextjs
-Pre-built authentication UI components for Next.js applications using Insforge backend. This package provides a Clerk-like experience with drop-in components that connect directly to your Insforge backend, reducing token usage for AI agents.
+**Zero-configuration authentication for Next.js** using Insforge backend. Authentication pages are hosted on your backend by default—no UI code needed.
+## Why Built-in Auth?
+✅ **Zero UI Code** - No SignIn/SignUp pages to create
+✅ **5-Minute Setup** - Provider + API route + callback page = done
+✅ **Production Ready** - Battle-tested auth UI maintained by Insforge
+✅ **Auto OAuth** - 11 providers configured automatically from backend
+✅ **AI-Friendly** - Minimal code generation = fewer tokens
+**Use custom components only if you need highly customized branding or custom fields.**
 ## Features
-- **Drop-in UI Components**: Pre-styled SignIn, SignUp, and UserButton components
-- **Auth Primitives (v0.5.0+)**: 10 low-level components for building custom auth UIs
-- **React Hooks**: Easy access to auth state with `useAuth()`, `useUser()`, `useSession()`
-- **Control Components**: `<SignedIn>`, `<SignedOut>`, `<Protect>` for conditional rendering
+- **Built-in Authentication**: Backend-hosted sign-in/sign-up pages (default)
+- **OAuth Support**: Google, GitHub, Discord, Facebook, LinkedIn, Microsoft, Apple, X, Instagram, TikTok, Spotify
+- **React Hooks**: `useAuth()`, `useUser()`, `useSession()`
+- **Control Components**: `<SignedIn>`, `<SignedOut>`, `<Protect>`
 - **Next.js Middleware**: Server-side route protection
-- **OAuth Support**: 11 providers (Google, GitHub, Discord, Facebook, LinkedIn, Microsoft, Apple, X, Instagram, TikTok, Spotify)
-- **Smart OAuth Layout**: Adaptive grid (1/2/3 columns) based on provider count
-- **TypeScript**: Full type safety out of the box
-- **Customizable**: Override styles with the `appearance` prop or build from primitives
+- **TypeScript**: Full type safety
 ## Installation
 ```bash
 npm install @insforge/nextjs
-# or
-yarn add @insforge/nextjs
 ```
 ## Quick Start
-### 1. Wrap your app with InsforgeProvider
+### 1. Add InsforgeProvider
 ```tsx
 // app/layout.tsx
 import { InsforgeProvider } from '@insforge/nextjs';
-import '@insforge/nextjs/styles.css';
 export default function RootLayout({ children }: { children: React.ReactNode }) {
-  const baseUrl = process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!;
   return (
     <html lang="en">
       <body>
-        <InsforgeProvider baseUrl={baseUrl}>
+        <InsforgeProvider baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}>
           {children}
         </InsforgeProvider>
       </body>
@@ -47,11 +48,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
-**That's it!** No Tailwind configuration needed. The package uses standalone CSS.
-### 2. Set up API route for authentication (Required for SSR)
-Create an API route to handle authentication cookies. This is **essential** for Next.js server-side rendering and middleware to work properly.
+### 2. Create API route (enables SSR)
 ```tsx
 // app/api/auth/route.ts
@@ -67,16 +64,9 @@ export const GET = handlers.GET;
 export const DELETE = handlers.DELETE;
 ```
-**Why is this needed?**
-Next.js middleware runs on the server and cannot access `localStorage` (which is browser-only). This API route:
-- Syncs tokens from `localStorage` to HTTP-only cookies
-- Enables server-side authentication in middleware
-- Provides server-side sign-in/sign-up endpoints
+> **Why?** Syncs auth tokens to HTTP-only cookies for server-side middleware.
-### 3. Add authentication callback page (Required for Next.js SSR)
-Create a callback page to handle post-authentication token synchronization. This is **required for all authentication methods** (email/password and OAuth) when using Next.js middleware:
+### 3. Create callback page
 ```tsx
 // app/auth/callback/page.tsx
@@ -91,8 +81,7 @@ function CallbackContent() {
   const isProcessingRef = useRef(false);
   useEffect(() => {
-    const processOAuthCallback = async () => {
-      // Prevent double-processing in React Strict Mode
+    const processCallback = async () => {
       if (isProcessingRef.current) return;
       isProcessingRef.current = true;
@@ -100,59 +89,27 @@ function CallbackContent() {
       const error = searchParams.get('error');
       if (error) {
-        console.error('OAuth error:', error);
-        router.push('/sign-in?error=' + encodeURIComponent(error));
+        router.push('/?error=' + encodeURIComponent(error));
         return;
       }
       if (accessToken) {
-        // 1. Store token in localStorage (for SDK client-side operations)
         localStorage.setItem('insforge-auth-token', accessToken);
-        console.log('✅ OAuth token stored in localStorage');
-        // 2. Sync token to HTTP-only cookie (for server-side middleware)
-        try {
-          const syncResponse = await fetch('/api/auth', {
-            method: 'POST',
-            headers: {
-              'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({
-              action: 'sync-token',
-              token: accessToken,
-            }),
-          });
-          if (syncResponse.ok) {
-            console.log('✅ OAuth token synced to cookie');
-          } else {
-            console.warn('⚠️ Failed to sync token to cookie, but localStorage has it');
-          }
-        } catch (syncError) {
-          console.warn('⚠️ Cookie sync failed:', syncError);
-        }
-        // 3. Get the final destination from sessionStorage
-        const finalDestination = sessionStorage.getItem('oauth_final_destination') || '/dashboard';
-        sessionStorage.removeItem('oauth_final_destination');
+        await fetch('/api/auth', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ action: 'sync-token', token: accessToken }),
+        });
-        // 4. Clean up URL to remove OAuth params before redirect
-        window.history.replaceState({}, '', '/auth/callback');
+        const destination = sessionStorage.getItem('auth_destination') || '/dashboard';
+        sessionStorage.removeItem('auth_destination');
-        // 5. Small delay to ensure cookie is set before redirect
-        setTimeout(() => {
-          router.push(finalDestination);
-        }, 100);
-      } else {
-        if (searchParams.toString()) {
-          console.error('No token received from OAuth');
-          router.push('/sign-in?error=no_token');
-        }
+        setTimeout(() => router.push(destination), 100);
       }
     };
-    processOAuthCallback();
+    processCallback();
   }, [searchParams, router]);
   return (
@@ -165,64 +122,35 @@ function CallbackContent() {
   );
 }
-export default function OAuthCallbackPage() {
+export default function CallbackPage() {
   return (
-    <Suspense fallback={
-      <div className="flex items-center justify-center min-h-screen">
-        <div>Loading...</div>
-      </div>
-    }>
+    <Suspense fallback={<div>Loading...</div>}>
       <CallbackContent />
     </Suspense>
   );
 }
 ```
-**What this does:**
-1. Receives authentication callback with `access_token` from backend (works for both OAuth and email/password)
-2. Stores token in `localStorage` for SDK client-side operations
-3. Syncs token to HTTP-only cookie via `/api/auth` for server-side middleware
-4. Redirects user to their intended destination
-**Note:** This callback page handles returns from:
-- OAuth providers (Google, GitHub, etc.)
-- Email/password sign-in/sign-up when using the pre-built components
+> **Why?** Receives token from backend auth pages and syncs to localStorage + cookie.
-### 4. Add sign-in page
-```tsx
-// app/sign-in/page.tsx
-import { SignIn } from '@insforge/nextjs';
+### 4. Add middleware (protects routes)
-export default function SignInPage() {
-  return (
-    <SignIn
-      afterSignInUrl="/dashboard"
-      title="Welcome to MyApp"
-      subtitle="Sign in to continue"
-    />
-  );
-}
-```
-**OAuth Providers:** The package automatically detects which OAuth providers are configured on your backend. You don't need to specify them manually!
-### 5. Add sign-up page
+```ts
+// middleware.ts
+import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
-```tsx
-// app/sign-up/page.tsx
-import { SignUp } from '@insforge/nextjs';
+export default InsforgeMiddleware({
+  baseUrl: process.env.INSFORGE_BASE_URL!,
+  publicRoutes: ['/auth/callback', '/'],
+  cookieName: 'insforge_token',
+});
-export default function SignUpPage() {
-  return (
-    <SignUp
-      afterSignUpUrl="/dashboard"
-    />
-  );
-}
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
+};
 ```
-### 6. Use conditional components
+### 5. Use in components
 ```tsx
 // app/page.tsx
@@ -231,816 +159,255 @@ import { SignedIn, SignedOut, UserButton } from '@insforge/nextjs';
 export default function Home() {
   return (
     <div>
-      <nav>
-        <SignedOut>
-          <a href="/sign-in">Sign In</a>
-        </SignedOut>
-        <SignedIn>
-          <UserButton afterSignOutUrl="/" />
-        </SignedIn>
-      </nav>
+      <SignedOut>
+        <a href="/sign-in">Sign In</a>
+      </SignedOut>
       <SignedIn>
+        <UserButton afterSignOutUrl="/" />
         <h1>Welcome back!</h1>
       </SignedIn>
-      <SignedOut>
-        <h1>Please sign in</h1>
-      </SignedOut>
     </div>
   );
 }
 ```
-### 7. Protect routes with middleware
-```ts
-// middleware.ts
-import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
-export default InsforgeMiddleware({
-  baseUrl: process.env.INSFORGE_BASE_URL!,
-  publicRoutes: ['/sign-in', '/sign-up', '/', '/auth/callback'],  // Include callback!
-  signInUrl: '/sign-in',
-  cookieName: 'insforge_token',  // Must match API route cookie name
-});
-export const config = {
-  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
-};
-```
-**Important:**
-- **Must include** `/auth/callback` in `publicRoutes` to allow authentication returns
-- Use the same `cookieName` in both middleware and API route
-- The `cookieName` must match between middleware and API route configuration
-**Alternative imports:**
-- `InsforgeMiddleware` - Recommended, most descriptive
-- `withInsforgeAuth` - Alternative with Insforge branding
-- `withAuth` - Deprecated but still supported for backward compatibility
+**That's it!** When users click "Sign In", they'll be redirected to your backend's auth page automatically.
 ---
-## Architecture: Why Callback + API Route?
-This package is specifically designed for **Next.js App Router with Server-Side Rendering (SSR)**. Here's why both the callback page and API route are essential:
-### The Challenge
-Next.js has two execution environments:
-- **Client-side**: Browser, can access `localStorage`
-- **Server-side**: Middleware, Server Components, cannot access `localStorage`
-The Insforge SDK stores authentication tokens in `localStorage` (client-side only), but Next.js middleware needs to verify authentication on the server.
-### The Solution
-**Two-Storage Architecture:**
+## How It Works
 ```
-┌─────────────────────────────────────────────────────────────┐
-│ Authentication Flow (Email/Password & OAuth)                 │
-└─────────────────────────────────────────────────────────────┘
-1. User signs in (email/password OR OAuth)
+1. User clicks "Sign In" → Middleware detects no auth
    ↓
-2. Backend redirects to: /auth/callback?access_token=xxx
+2. Redirects to: https://backend.insforge.app/auth/signin?redirect=yourapp.com/auth/callback
    ↓
-3. Callback Page (Client-side)
-   ├─ Stores token in localStorage (for SDK)
-   └─ Calls /api/auth with "sync-token" action
+3. User signs in on backend's hosted page
    ↓
-4. API Route (Server-side)
-   ├─ Validates token with backend
-   └─ Sets HTTP-only cookie
+4. Backend redirects: yourapp.com/auth/callback?access_token=xxx
    ↓
-5. Middleware (Server-side)
-   └─ Reads cookie to protect routes
+5. Callback stores token (localStorage + cookie) → User sees /dashboard
 ```
-**Why this matters:**
-- **Client-side operations** (SDK calls) use `localStorage`
-- **Server-side operations** (middleware, SSR) use HTTP-only cookies
-- Both storages stay synchronized through the `/api/auth` endpoint
-### What Each Component Does
+**Why API route + callback?**
+- **API route**: Syncs tokens to HTTP-only cookies (enables server-side middleware)
+- **Callback page**: Receives tokens from backend auth pages (OAuth + email/password)
-| Component | Purpose | Runs On |
-|-----------|---------|---------|
-| **Callback Page** | Receives auth token (any method), stores in localStorage, syncs to cookie | Client |
-| **API Route** | Validates tokens, manages cookies, provides server-side auth | Server |
-| **Middleware** | Protects routes, reads cookies, validates sessions | Server |
-| **SDK** | Makes API calls, reads from localStorage | Client |
-This architecture enables full-stack authentication in Next.js while maintaining security with HTTP-only cookies.
-**Note:** All authentication methods (email/password, OAuth) use this same flow for consistency and SSR support.
-## API Reference
-### Components
+---
-#### `<InsforgeProvider>`
+## Local Development
-Wraps your application and provides auth context. Automatically fetches OAuth provider configuration from your backend.
+Backend typically runs on different port during local dev:
-```tsx
-<InsforgeProvider
-  baseUrl="https://your-backend.insforge.app"
-  onAuthChange={(user) => console.log('Auth changed:', user)}
->
-  {children}
-</InsforgeProvider>
+```bash
+# .env.local
+NEXT_PUBLIC_INSFORGE_BASE_URL=http://localhost:7130       # Backend API
+NEXT_PUBLIC_INSFORGE_FRONTEND_URL=http://localhost:7131   # Backend Frontend (auth pages)
+INSFORGE_BASE_URL=http://localhost:7130                   # For middleware
 ```
-**Props:**
-- `baseUrl` (required): Your Insforge backend URL
-- `onAuthChange`: Optional callback when auth state changes
-**Note:** The provider automatically queries your backend's OAuth configuration, so components like `<SignIn>` and `<SignUp>` will display the correct OAuth buttons without manual configuration.
+Provider automatically uses `NEXT_PUBLIC_INSFORGE_FRONTEND_URL` for auth redirects if set.
 ---
-#### `<SignIn>`
+## Advanced: Custom Components
-Pre-built sign-in form with email/password and OAuth.
+Need custom branding? Disable built-in auth:
 ```tsx
-<SignIn
-  afterSignInUrl="/dashboard"
-  appearance={{
-    container: { background: '#f5f5f5' },
-    button: { background: 'blue' }
-  }}
-  onSuccess={(user) => console.log('Signed in:', user)}
-  onError={(error) => console.error('Error:', error)}
-/>
-```
-**Props:**
-- `afterSignInUrl`: Redirect URL after successful sign-in (default: `/`)
-- `appearance`: Custom styles for container, form, and button
-- `onSuccess`: Callback on successful sign-in
-- `onError`: Callback on error
-**Note:** OAuth providers are automatically detected from your backend configuration via `InsforgeProvider`. No need to manually specify them!
----
+// app/layout.tsx
+import { InsforgeProvider } from '@insforge/nextjs';
+import '@insforge/nextjs/styles.css';  // Required for custom components
-#### `<SignUp>`
+export default function RootLayout({ children }) {
+  return (
+    <InsforgeProvider
+      baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
+      useBuiltInAuth={false}
+    >
+      {children}
+    </InsforgeProvider>
+  );
+}
+```
-Pre-built sign-up form with email/password and OAuth.
+### Pre-built Components
 ```tsx
-<SignUp
-  afterSignUpUrl="/onboarding"
-  appearance={{
-    container: { background: '#f5f5f5' }
-  }}
-/>
-```
-**Props:**
-- `afterSignUpUrl`: Redirect URL after successful sign-up (default: `/`)
-- `appearance`: Custom styles for container, form, and button
-- `onSuccess`: Callback on successful sign-up
-- `onError`: Callback on error
+// app/sign-in/page.tsx
+import { SignIn } from '@insforge/nextjs';
-**Note:** OAuth providers are automatically detected from your backend configuration via `InsforgeProvider`. No need to manually specify them!
+export default function SignInPage() {
+  return <SignIn afterSignInUrl="/dashboard" />;
+}
+```
----
+OAuth providers are auto-detected from your backend config.
-### Auth Component Primitives (v0.5.0+)
+### Build from Primitives
-For advanced customization, use the low-level Auth primitives to build your own authentication UI:
+For complete control:
 ```tsx
 import {
   AuthContainer,
   AuthHeader,
-  AuthErrorBanner,
   AuthFormField,
   AuthPasswordField,
   AuthSubmitButton,
-  AuthDivider,
-  AuthLink,
   AuthOAuthProviders,
-  AuthBranding,
 } from '@insforge/nextjs';
-import '@insforge/nextjs/styles.css';
 function CustomSignIn() {
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
-  const [error, setError] = useState('');
-  const [loading, setLoading] = useState(false);
-  async function handleSubmit(e) {
-    e.preventDefault();
-    // Your custom auth logic
-  }
-  return (
-    <AuthContainer>
-      <AuthHeader title="Welcome Back" subtitle="Sign in to continue" />
-      <AuthErrorBanner error={error} />
-      <form onSubmit={handleSubmit} className="insforge-form">
-        <AuthFormField
-          id="email"
-          type="email"
-          label="Email"
-          placeholder="you@example.com"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          required
-        />
-        <AuthPasswordField
-          id="password"
-          label="Password"
-          value={password}
-          onChange={(e) => setPassword(e.target.value)}
-          required
-          forgotPasswordLink={{
-            href: '/forgot-password',
-            text: 'Forgot Password?'
-          }}
-        />
-        <AuthSubmitButton isLoading={loading}>
-          Sign In
-        </AuthSubmitButton>
-      </form>
-      <AuthLink
-        text="Don't have an account?"
-        linkText="Sign up"
-        href="/sign-up"
-      />
-      <AuthDivider text="or" />
-      <AuthOAuthProviders
-        providers={['google', 'github', 'discord']}
-        onClick={(provider) => handleOAuth(provider)}
-        loading={null}
-      />
-      <AuthBranding />
-    </AuthContainer>
-  );
+  // Build your own auth UI with full control
 }
 ```
-#### Available Primitives
-| Component | Description |
-|-----------|-------------|
-| `<AuthContainer>` | Main wrapper with card styling. Accepts `style` prop for customization |
-| `<AuthHeader>` | Displays `title` and optional `subtitle` |
-| `<AuthErrorBanner>` | Shows error messages. Pass `error` string prop |
-| `<AuthFormField>` | Standard input field. Supports all HTML input props + `label` |
-| `<AuthPasswordField>` | Password input with visibility toggle, optional strength indicator, and forgot password link |
-| `<AuthSubmitButton>` | Submit button with loading state. Pass `isLoading` and optional `loadingText` |
-| `<AuthDivider>` | Visual separator with customizable `text` (default: "or") |
-| `<AuthLink>` | Call-to-action link. Props: `text`, `linkText`, `href` |
-| `<AuthOAuthProviders>` | Smart grid of OAuth buttons. Props: `providers`, `onClick`, `loading` |
-| `<AuthBranding>` | "Powered by InsForge" branding. Optional `text` and `href` props |
-**`AuthPasswordField` Props:**
-- All standard input props (`value`, `onChange`, `required`, etc.)
-- `label`: Field label text
-- `id`: Input element ID
-- `showStrengthIndicator`: Show password strength indicator (default: `false`)
-- `forgotPasswordLink`: Object with `{ href: string, text?: string }`
-**`AuthOAuthProviders` Smart Layout:**
-- 1 provider: Full-width button with "Continue with Google"
-- 2 providers: Two columns with short text "Google", "GitHub"
-- 3+ providers: Three columns with icons only
-- Auto-centers incomplete last rows (e.g., 5, 8, 11 providers)
-**When to use primitives vs pre-built components:**
-- Use `<SignIn>` / `<SignUp>` for quick setup with minimal customization
-- Use Auth primitives when you need:
-  - Custom form layouts
-  - Additional fields (username, terms checkbox, etc.)
-  - Integration with your own state management
-  - Unique branding and styling
----
-#### `<UserButton>`
-User profile dropdown with sign-out functionality.
-```tsx
-<UserButton
-  afterSignOutUrl="/"
-  showEmail={true}
-  appearance={{
-    button: { borderRadius: '50%' },
-    dropdown: { minWidth: '250px' }
-  }}
-/>
-```
-**Props:**
-- `afterSignOutUrl`: Redirect URL after sign-out (default: `/`)
-- `showEmail`: Show user email in dropdown (default: `true`)
-- `appearance`: Custom styles for button and dropdown
----
-#### `<SignedIn>`
-Renders children only when user is authenticated.
-```tsx
-<SignedIn>
-  <Dashboard />
-</SignedIn>
-```
----
+**Available primitives**: `AuthContainer`, `AuthHeader`, `AuthErrorBanner`, `AuthFormField`, `AuthPasswordField`, `AuthSubmitButton`, `AuthDivider`, `AuthLink`, `AuthOAuthProviders`, `AuthBranding`.
-#### `<SignedOut>`
+### Update Middleware
-Renders children only when user is NOT authenticated.
-```tsx
-<SignedOut>
-  <LandingPage />
-</SignedOut>
+```ts
+// middleware.ts
+export default InsforgeMiddleware({
+  baseUrl: process.env.INSFORGE_BASE_URL!,
+  publicRoutes: ['/sign-in', '/sign-up', '/auth/callback', '/'],
+  signInUrl: '/sign-in',
+  useBuiltInAuth: false,  // Important!
+});
 ```
 ---
-#### `<Protect>`
-Protects content and optionally redirects unauthenticated users.
-```tsx
-<Protect
-  fallback={<Loading />}
-  redirectTo="/sign-in"
-  condition={(user) => user.role === 'admin'}
->
-  <AdminPanel />
-</Protect>
-```
-**Props:**
-- `fallback`: Component to show while loading or if unauthorized
-- `redirectTo`: URL to redirect to if not authorized (default: `/sign-in`)
-- `condition`: Optional function for custom authorization logic (e.g., role-based access)
----
+## API Reference
 ### Hooks
 #### `useAuth()`
-Access complete auth state and methods.
 ```tsx
 import { useAuth } from '@insforge/nextjs';
 function Component() {
-  const {
-    user,
-    session,
-    isLoaded,
-    isSignedIn,
-    signIn,
-    signUp,
-    signOut,
-    updateUser
-  } = useAuth();
-  if (!isLoaded) return <div>Loading...</div>;
-  if (!isSignedIn) return <div>Please sign in</div>;
-  return <div>Hello {user.email}</div>;
+  const { user, isSignedIn, signOut } = useAuth();
+  return <div>{user?.email}</div>;
 }
 ```
-**Returns:**
-- `user`: Current user object or `null`
-- `session`: Current session object or `null`
-- `isLoaded`: Whether auth state has loaded
-- `isSignedIn`: Whether user is authenticated
-- `signIn(email, password)`: Sign in method
-- `signUp(email, password)`: Sign up method
-- `signOut()`: Sign out method
-- `updateUser(data)`: Update user data
----
+**Returns**: `user`, `session`, `isLoaded`, `isSignedIn`, `signIn()`, `signUp()`, `signOut()`, `updateUser()`
 #### `useUser()`
-Access current user data.
 ```tsx
-import { useUser } from '@insforge/nextjs';
-function Component() {
-  const { user, isLoaded } = useUser();
-  if (!isLoaded) return <div>Loading...</div>;
-  if (!user) return <div>Not signed in</div>;
-  return <div>{user.email}</div>;
-}
+const { user, isLoaded } = useUser();
 ```
----
 #### `useSession()`
-Access current session data.
 ```tsx
-import { useSession } from '@insforge/nextjs';
-function Component() {
-  const { session, isLoaded, isSignedIn } = useSession();
-  return <div>Signed in: {isSignedIn ? 'Yes' : 'No'}</div>;
-}
+const { session, isSignedIn } = useSession();
 ```
----
-### API Route Handlers
+### Components
-#### `createAuthRouteHandlers(config)`
+#### `<SignIn>` / `<SignUp>`
-Creates Next.js App Router API handlers for authentication with HTTP-only cookie management.
+Pre-built auth forms (only with `useBuiltInAuth={false}`):
 ```tsx
-// app/api/auth/route.ts
-import { createAuthRouteHandlers } from '@insforge/nextjs/api';
-const handlers = createAuthRouteHandlers({
-  baseUrl: process.env.INSFORGE_BASE_URL!,
-  cookieName: 'insforge_token',
-  cookieMaxAge: 7 * 24 * 60 * 60, // 7 days
-});
-export const POST = handlers.POST;
-export const GET = handlers.GET;
-export const DELETE = handlers.DELETE;
-```
-**Config:**
-- `baseUrl` (required): Your Insforge backend URL
-- `cookieName`: Cookie name for auth token (default: `insforge_token`)
-- `cookieMaxAge`: Cookie expiration in seconds (default: 7 days)
-- `secure`: Use secure cookies (auto-detected, `true` in production)
-**Supported Actions (POST):**
-- `sign-in`: Email/password sign-in with cookie creation
-- `sign-up`: Email/password sign-up with cookie creation
-- `sync-token`: Sync token from localStorage to cookie (for OAuth)
-**Example: Sync token after OAuth**
-```typescript
-// In your OAuth callback page
-const response = await fetch('/api/auth', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    action: 'sync-token',
-    token: accessToken,
-  }),
-});
+<SignIn afterSignInUrl="/dashboard" />
+<SignUp afterSignUpUrl="/onboarding" />
 ```
-**Endpoints:**
-- `POST /api/auth` - Sign in, sign up, or sync token
-- `GET /api/auth` - Check current session
-- `DELETE /api/auth` - Sign out and clear cookies
----
+**Props**: `afterSignInUrl`/`afterSignUpUrl`, `appearance`, `onSuccess`, `onError`
-### Middleware
-#### `InsforgeMiddleware(config)`
-Create Next.js middleware for route protection.
-```ts
-import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
+#### `<UserButton>`
-export default InsforgeMiddleware({
-  baseUrl: process.env.INSFORGE_BASE_URL!,
-  publicRoutes: ['/sign-in', '/sign-up', '/', '/about'],
-  signInUrl: '/sign-in',
-  cookieName: 'insforge_token',
-});
+```tsx
+<UserButton afterSignOutUrl="/" showEmail={true} />
 ```
-**Config:**
-- `baseUrl` (required): Your Insforge backend URL
-- `publicRoutes`: Array of routes that don't require auth (supports wildcards: `/blog/*`)
-- `signInUrl`: URL to redirect to when not authenticated (default: `/sign-in`)
-- `cookieName`: Cookie name for auth token (default: `insforge_token`)
+#### `<SignedIn>` / `<SignedOut>` / `<Protect>`
-**Alternative exports:**
-- `withInsforgeAuth` - Same as `InsforgeMiddleware` with Insforge branding
-- `withAuth` - Deprecated alias for backward compatibility
----
-#### `getAuthUserId(headers)` and `getAuthToken(headers)`
+```tsx
+<SignedIn><Dashboard /></SignedIn>
+<SignedOut><LandingPage /></SignedOut>
+<Protect condition={(user) => user.role === 'admin'}><AdminPanel /></Protect>
+```
-Get authenticated user ID or token in server components.
+### Server-Side Helpers
 ```tsx
+// app/dashboard/page.tsx (Server Component)
 import { headers } from 'next/headers';
 import { getAuthUserId, getAuthToken } from '@insforge/nextjs/middleware';
-export default async function ServerComponent() {
+export default async function Dashboard() {
   const userId = getAuthUserId(headers());
   const token = getAuthToken(headers());
-  // Fetch user-specific data
-  const data = await fetchUserData(userId, token);
+  // Fetch user data server-side
   return <div>User ID: {userId}</div>;
 }
-```
-**Alternative exports:**
-- `getAuthUser` - Deprecated alias for `getAuthUserId` (backward compatibility)
+```
 ---
-## Styling
-This package uses **standalone CSS** for styling - no Tailwind CSS dependency required! All components come pre-styled and ready to use.
+## Customization
-### Setup
+### Styling (Custom Components Only)
-Simply import the CSS file once in your root layout:
+When using `useBuiltInAuth={false}`, import styles:
 ```tsx
-// app/layout.tsx
 import '@insforge/nextjs/styles.css';
 ```
-That's it! No configuration needed.
-### Typography
-The package includes the **Manrope variable font** for a modern, professional look. The font is automatically loaded and available as a CSS variable:
-```css
-/* Use the font in your own CSS */
-.my-component {
-  font-family: var(--font-manrope);
-}
-```
-The font family includes fallbacks to system fonts for optimal loading:
-- `--font-manrope`: 'Manrope', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
-### Customization
-**Option 1: Text Customization** (Easiest)
-All text elements in the components can be customized via props:
-```tsx
-<SignIn
-  baseUrl="..."
-  // Customize all text
-  title="Welcome Back to MyApp"
-  subtitle="We're happy to see you again"
-  emailLabel="Your Email"
-  emailPlaceholder="you@company.com"
-  passwordLabel="Your Password"
-  forgotPasswordText="Forgot it?"
-  submitButtonText="Log In"
-  loadingButtonText="Logging in..."
-  signUpText="New user?"
-  signUpLinkText="Create an account"
-  signUpUrl="/register"
-  dividerText="or continue with"
-/>
-<SignUp
-  baseUrl="..."
-  // Customize signup text
-  title="Join MyApp Today"
-  subtitle="Create your account in seconds"
-  submitButtonText="Create Account"
-  signInText="Existing user?"
-  signInLinkText="Log in here"
-/>
-```
-**Option 2: Style Customization**
-Override inline styles for specific components:
+Override with `appearance` prop or CSS classes:
 ```tsx
-<SignIn
-  appearance={{
-    container: {
-      background: 'linear-gradient(to right, #4f46e5, #7c3aed)'
-    },
-    form: {
-      padding: '3rem',
-      borderRadius: '16px'
-    },
-    button: {
-      background: '#4f46e5',
-      color: 'white'
-    }
-  }}
-/>
+<SignIn appearance={{ container: { background: '#f5f5f5' } }} />
 ```
-**Option 3: Override CSS Classes**
-All components use semantic CSS class names prefixed with `insforge-`:
 ```css
-/* In your global CSS file */
-/* Customize the primary button */
-.insforge-btn-primary {
-  background: #8b5cf6;
-  border-radius: 12px;
-}
-/* Customize form inputs */
-.insforge-input {
-  border-color: #e0e0e0;
-  border-radius: 8px;
-}
-/* Customize the auth card */
-.insforge-auth-card {
-  box-shadow: 0 20px 50px rgba(0, 0, 0, 0.15);
-}
+.insforge-btn-primary { background: #8b5cf6; }
 ```
-**Available CSS Classes:**
-- `.insforge-auth-container` - Main container
-- `.insforge-auth-card` - Form card
-- `.insforge-input` - Input fields
-- `.insforge-btn-primary` - Primary buttons
-- `.insforge-oauth-btn` - OAuth buttons
-- `.insforge-user-button` - User menu button
-- `.insforge-error-banner` - Error messages
----
-## Advanced Usage
-### Role-Based Access Control
+### Auth Callbacks
 ```tsx
-<Protect condition={(user) => user.role === 'admin'}>
-  <AdminDashboard />
-</Protect>
-```
-### Custom Auth Callbacks
-```tsx
-<InsforgeProvider
+<InsforgeProvider
   baseUrl={baseUrl}
-  onAuthChange={(user) => {
-    if (user) {
-      analytics.identify(user.id);
-    } else {
-      analytics.reset();
-    }
-  }}
->
-  {children}
-</InsforgeProvider>
-```
-### Server-Side User Data
-```tsx
-// app/dashboard/page.tsx
-import { headers } from 'next/headers';
-import { getAuthUserId } from '@insforge/nextjs/middleware';
-import { createClient } from '@insforge/sdk';
-export default async function Dashboard() {
-  const userId = getAuthUserId(headers());
-  const insforge = createClient({
-    baseUrl: process.env.INSFORGE_BASE_URL!
-  });
-  const user = await insforge.auth.getUserById(userId);
-  return <div>Welcome {user.email}</div>;
-}
-```
----
-## Environment Variables
-Create a `.env.local` file:
-```env
-# Public (accessible in browser)
-NEXT_PUBLIC_INSFORGE_BASE_URL=https://your-backend.insforge.app
-# Server-only (middleware)
-INSFORGE_BASE_URL=https://your-backend.insforge.app
+  onAuthChange={(user) => user && analytics.identify(user.id)}
+/>
 ```
 ---
 ## Why @insforge/nextjs?
-### For Developers
-- **Faster Development**: Drop-in components save hours of auth implementation
-- **Best Practices**: Built-in security, session management, and error handling
-- **Flexible**: Fully customizable while providing sensible defaults
-- **Explicit Configuration**: OAuth providers passed as props - no hidden API calls or magic
-### For AI Agents
-- **Reduced Token Usage**: Pre-built components mean agents don't rebuild UI each time
-- **Consistent UX**: Standard patterns across projects
-- **Less Context**: Import and use instead of implementing from scratch
-- **Discoverable**: Query `/api/metadata/auth` via MCP to get OAuth config, then generate code with correct `providers` prop
-### AI Agent Workflow with Insforge MCP
+**For Developers**: 5-minute auth setup instead of hours. Production-ready security and session management included.
-When building Next.js apps with authentication:
-1. **Connect to Insforge MCP** - Access the user's Insforge backend
-2. **Generate code** - Use `<SignIn>` and `<SignUp>` components
-3. **Automatic configuration** - OAuth providers are detected automatically from backend
-**Agent generates:**
-```tsx
-// Step 1: Wrap app with InsforgeProvider
-<InsforgeProvider baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}>
-  {children}
-</InsforgeProvider>
-// Step 2: Add sign-in page (OAuth auto-detected)
-<SignIn afterSignInUrl="/dashboard" />
-```
-**Benefits:**
-- No need to query OAuth configuration manually
-- Components automatically render correct OAuth buttons
-- Backend configuration is the single source of truth
+**For AI Agents**: Minimal code generation (5 files vs 20+ for custom auth). Reduced token usage. Consistent patterns across projects.
 ---
 ## TypeScript
-Full TypeScript support with exported types:
 ```tsx
-import type {
-  InsforgeUser,
-  InsforgeSession,
-  AuthContextValue,
-  SignInProps,
-  ProtectProps
-} from '@insforge/nextjs';
+import type { InsforgeUser, InsforgeSession, AuthContextValue } from '@insforge/nextjs';
 ```
 ---
-## Examples
-Check out the `/examples` directory for:
-- Basic Next.js App Router setup
-- Role-based access control
-- Custom styling
-- Server-side data fetching
+## Support
----
+- **Docs**: https://docs.insforge.dev/introduction
+- **Issues**: https://github.com/InsForge/InsForge/issues
+- **Discord**: https://discord.com/invite/DvBtaEc9Jz
 ## License
 MIT
----
-## Support
-- Documentation: https://docs.insforge.dev/introduction
-- Issues: https://github.com/InsForge/InsForge/issues
-- Discord: https://discord.com/invite/DvBtaEc9Jz