@mdxui/auth 1.1.1 → 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/dist/{auth-Ba2f778e.d.ts → auth-maeYSYU_.d.ts}

@@ -46,7 +46,7 @@ interface AuthGateProps {
     /** Component to show when not authenticated (landing page) */
     landingComponent?: ReactNode;
     /** What to do when unauthenticated */
-    onUnauthenticated?: 'landing' | 'redirect' | 'allow';
+    onUnauthenticated?: 'landing' | 'redirect' | 'allow' | 'signIn';
     /** URL to redirect to when unauthenticated (if onUnauthenticated is 'redirect') */
     redirectUrl?: string;
 }
@@ -54,6 +54,9 @@ interface AuthGateProps {
  * Props for WidgetsProvider
  *
  * Extends the schema type with React-specific fields.
+ *
+ * Note: Widgets always use api.workos.com - WorkOS custom domains do NOT
+ * support widget endpoints. Only authentication uses custom domains.
  */
 interface WidgetsProviderProps {
     /** Children to render */

package/dist/hooks/index.d.ts

@@ -1,5 +1,5 @@
 export { useAuth } from '@workos-inc/authkit-react';
-import { U as UseWidgetTokenOptions, b as UseWidgetTokenResult } from '../auth-Ba2f778e.js';
+import { U as UseWidgetTokenOptions, b as UseWidgetTokenResult } from '../auth-maeYSYU_.js';
 import { V as VaultItem, a as VaultField } from '../types-8tixck1H.js';
 import 'react';
 

package/dist/{index-DGthQxCM.d.ts → index-BOMpMKyG.d.ts}

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { I as IdentityProviderProps, A as AuthGateProps, W as WidgetsProviderProps } from './auth-Ba2f778e.js';
+import { I as IdentityProviderProps, A as AuthGateProps, W as WidgetsProviderProps } from './auth-maeYSYU_.js';
 import { ReactNode } from 'react';
 import { V as VaultItem, a as VaultField } from './types-8tixck1H.js';
 

package/dist/index.d.ts

@@ -1,14 +1,17 @@
-export { A as AuthGate, I as IdentityProvider, a as IdentityProviderMinimal, d as VaultClient, e as VaultContextState, V as VaultProvider, f as VaultProviderProps, W as WidgetsProvider, u as useThemeDetection, b as useVaultContext, c as useVaultContextOptional } from './index-DGthQxCM.js';
+export { A as AuthGate, I as IdentityProvider, a as IdentityProviderMinimal, d as VaultClient, e as VaultContextState, V as VaultProvider, f as VaultProviderProps, W as WidgetsProvider, u as useThemeDetection, b as useVaultContext, c as useVaultContextOptional } from './index-BOMpMKyG.js';
 export { ApiKeys, OrganizationSwitcher, Pipes, UserProfile, UserSecurity, UserSessions, UsersManagement } from './widgets/index.js';
 export { Secret, SecretForm, SecretsManager, SecretsManagerProps, VaultDeleteDialog, VaultEmptyState, VaultInputModal, VaultItemCard, VaultList } from './vault/index.js';
 export { f as VaultDeleteDialogProps, g as VaultEmptyStateProps, a as VaultField, e as VaultInputModalProps, b as VaultIntegration, V as VaultItem, d as VaultItemCardProps, c as VaultListProps } from './types-8tixck1H.js';
 export { SignInButton, SignOutButton, TeamSwitcher, UserMenu } from './components/index.js';
 export { useAuth } from '@workos-inc/authkit-react';
 export { UseVaultResult, useVault, useVaultOptional, useWidgetToken } from './hooks/index.js';
-export { A as AuthGateProps, a as AuthToken, B as BaseWidgetProps, I as IdentityProviderProps, O as OrganizationWidgetProps, U as UseWidgetTokenOptions, b as UseWidgetTokenResult, W as WidgetsProviderProps } from './auth-Ba2f778e.js';
+export { A as AuthGateProps, a as AuthToken, B as BaseWidgetProps, I as IdentityProviderProps, O as OrganizationWidgetProps, U as UseWidgetTokenOptions, b as UseWidgetTokenResult, W as WidgetsProviderProps } from './auth-maeYSYU_.js';
 export { a as AuthOrganization, e as AuthOrganizationSchema, b as AuthSession, d as AuthSessionSchema, A as AuthUser, c as AuthUserSchema, I as Impersonator, f as ImpersonatorSchema } from './auth-organization-CN1WpGnL.js';
 export { AppearanceSchema, AuthGatePropsSchema, AuthTokenSchema, BaseWidgetPropsSchema, IdentityProviderPropsSchema, OrganizationWidgetPropsSchema, RadiusSchema, ScalingSchema, UnauthenticatedActionSchema, UseWidgetTokenOptionsSchema, UseWidgetTokenResultSchema, WidgetsProviderPropsSchema } from './schemas/index.js';
+export { ApiKeysPage, AuthApp, AuthAppConfig, AuthAppProps, AuthAppProvider, AuthAppRoute, AuthAppWithChildren, AuthShell, AuthShellBranding, AuthShellConfigProvider, AuthShellIdentity, AuthShellNav, AuthShellNavProps, AuthShellProps, BreadcrumbItemConfig, BreadcrumbLinkProps, Breadcrumbs, BreadcrumbsProps, IntegrationsPage, ProfilePage, SecurityPage, SessionsPage, SidebarOrgSwitcher, TeamPage, WidgetErrorBoundary, accountRoutes, adminRoutes, defaultGroups, defaultRoutes, developerRoutes, getEnvConfig, integrationRoutes, mergeWithEnvConfig, useAuthShellBranding, useAuthShellConfig, useAuthShellFullPath, useAuthShellRoutes, useAuthShellRoutesByGroup } from './shell/index.js';
+export { AuthShellConfig, ProtectedRoute, RouteGroup, ThemeMode } from 'mdxui';
 import 'react/jsx-runtime';
 import 'react';
 import 'zod/v4/core';
 import 'zod';
+import 'lucide-react';