@mdxui/auth 1.4.0 → 1.4.1

package/README.md

@@ -10,6 +10,83 @@ pnpm add @mdxui/auth
 
 ## Quick Start
 
+### Zero-Config AuthApp (Recommended)
+
+The easiest way to get started - just set environment variables:
+
+```bash
+# .env
+VITE_WORKOS_CLIENT_ID=client_xxx
+VITE_APP_NAME=My App
+```
+
+```tsx
+import { AuthApp } from '@mdxui/auth/shell'
+
+function App() {
+  return <AuthApp />
+}
+```
+
+That's it! You get a complete authenticated app with:
+- Sidebar navigation with org switcher
+- Profile, Security, Sessions, API Keys, Team, and Integrations pages
+- Error boundaries with friendly messages
+- Theme support
+
+### With Explicit Config
+
+```tsx
+import { AuthApp } from '@mdxui/auth/shell'
+
+function App() {
+  return (
+    <AuthApp
+      config={{
+        branding: { name: 'My App' },
+        identity: {
+          clientId: 'client_xxx',
+          redirectUri: 'https://myapp.com/callback',
+        },
+      }}
+    />
+  )
+}
+```
+
+### Custom Routes
+
+```tsx
+import { AuthApp, accountRoutes, developerRoutes } from '@mdxui/auth/shell'
+import { FileText } from 'lucide-react'
+import { DocsPage } from './pages/DocsPage'
+
+function App() {
+  return (
+    <AuthApp
+      config={{
+        branding: { name: 'My App' },
+        identity: { clientId: 'client_xxx' },
+        routes: [
+          ...accountRoutes,      // Profile, Security, Sessions
+          ...developerRoutes,    // API Keys
+          {
+            key: 'docs',
+            path: '/docs',
+            label: 'Documentation',
+            icon: FileText,
+            component: DocsPage,
+            group: 'developer',
+          },
+        ],
+      }}
+    />
+  )
+}
+```
+
+### Traditional Setup (Without Shell)
+
 ```tsx
 import {
   IdentityProvider,
@@ -42,6 +119,11 @@ function Dashboard() {
 
 ## Features
 
+- **Zero-Config AuthApp** - Complete authenticated app shell with environment variable support
+- **Pre-built Pages** - Profile, Security, Sessions, API Keys, Team, and Integrations pages
+- **Route Presets** - Composable route groups (`accountRoutes`, `developerRoutes`, `adminRoutes`)
+- **SidebarOrgSwitcher** - Auto-wired org switcher with branding fallback
+- **WidgetErrorBoundary** - Friendly, contextual error messages for widget failures
 - **Authentication Providers** - `IdentityProvider` and `AuthGate` for managing auth state
 - **WorkOS Widgets** - Pre-built components for user management (profile, security, API keys)
 - **Vault Components** - UI for managing encrypted secrets with `VaultProvider`
@@ -111,6 +193,56 @@ import type {
 } from '@mdxui/auth'
 ```
 
+### Shell Exports (`@mdxui/auth/shell`)
+
+Complete authenticated app shell with routing:
+
+```tsx
+import {
+  // App Components
+  AuthApp,              // Zero-config app with built-in routing
+  AuthAppWithChildren,  // App shell without routing (bring your own)
+  AuthAppProvider,      // Providers only (for custom layouts)
+  AuthShell,            // Shell layout component
+  AuthShellNav,         // Navigation component
+
+  // Shell Components
+  SidebarOrgSwitcher,   // Org switcher with branding fallback
+  WidgetErrorBoundary,  // Error boundary with friendly messages
+  Breadcrumbs,          // Breadcrumb navigation
+
+  // Pre-built Pages
+  ProfilePage,          // User profile management
+  SecurityPage,         // Password and MFA settings
+  SessionsPage,         // Active sessions management
+  ApiKeysPage,          // API key management
+  TeamPage,             // Team member management (requires org)
+  IntegrationsPage,     // Third-party integrations
+
+  // Route Presets
+  defaultRoutes,        // All default routes
+  defaultGroups,        // Default route groups
+  accountRoutes,        // Profile, Security, Sessions
+  developerRoutes,      // API Keys
+  adminRoutes,          // Team management
+  integrationRoutes,    // Integrations
+
+  // Config Hooks
+  useAuthShellConfig,
+  useAuthShellRoutes,
+  useAuthShellBranding,
+} from '@mdxui/auth/shell'
+
+// Types
+import type {
+  AuthAppConfig,
+  AuthAppProps,
+  AuthAppRoute,
+  AuthShellBranding,
+  AuthShellIdentity,
+} from '@mdxui/auth/shell'
+```
+
 ### Subpath Exports
 
 For more granular imports:
@@ -194,6 +326,97 @@ const sessionResult = AuthSessionSchema.safeParse({
 })
 ```
 
+## AuthApp (Shell)
+
+### Zero-Config with Environment Variables
+
+AuthApp can read configuration from environment variables, perfect for Cloudflare Workers Static Assets:
+
+```bash
+# .env
+VITE_WORKOS_CLIENT_ID=client_xxx        # Required
+VITE_WORKOS_REDIRECT_URI=https://...    # Optional
+VITE_WORKOS_API_HOSTNAME=auth.apis.do   # Optional
+VITE_WORKOS_DEV_MODE=true               # Optional
+VITE_APP_NAME=My App                    # Optional (defaults to "App")
+VITE_APP_TAGLINE=Best app ever          # Optional
+```
+
+```tsx
+import { AuthApp } from '@mdxui/auth/shell'
+
+// That's it - reads config from env vars
+function App() {
+  return <AuthApp />
+}
+```
+
+### Route Presets
+
+Compose routes from presets:
+
+```tsx
+import {
+  AuthApp,
+  accountRoutes,      // Profile, Security, Sessions
+  developerRoutes,    // API Keys
+  adminRoutes,        // Team
+  integrationRoutes,  // Integrations
+  defaultGroups,
+} from '@mdxui/auth/shell'
+
+function App() {
+  return (
+    <AuthApp
+      config={{
+        branding: { name: 'My App' },
+        identity: { clientId: 'client_xxx' },
+        groups: defaultGroups,
+        routes: [
+          ...accountRoutes,
+          ...developerRoutes,
+          // Exclude adminRoutes if you don't need team management
+        ],
+      }}
+    />
+  )
+}
+```
+
+### WidgetErrorBoundary
+
+Wraps WorkOS widgets with friendly error handling:
+
+```tsx
+import { WidgetErrorBoundary } from '@mdxui/auth/shell'
+import { UserProfile } from '@mdxui/auth/widgets'
+
+function ProfilePage() {
+  return (
+    <WidgetErrorBoundary widgetName="profile">
+      <UserProfile authToken={getAccessToken} />
+    </WidgetErrorBoundary>
+  )
+}
+// On error: "Your profile is camera shy right now..."
+// Unknown widgets: "Something went wrong loading your API Keys..."
+```
+
+### Custom Sidebar Header
+
+```tsx
+import { AuthApp, SidebarOrgSwitcher } from '@mdxui/auth/shell'
+
+// Default: SidebarOrgSwitcher is included automatically
+<AuthApp config={config} />
+
+// Custom header content
+<AuthApp
+  config={config}
+  sidebarHeaderContent={<MyCustomHeader />}
+/>
+```
+
 ## Components
 
 ### IdentityProvider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdxui/auth",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Authentication components and WorkOS AuthKit wrappers for mdxui",
   "type": "module",
   "sideEffects": false,