App

The App component is the root container for authenticated SaaS applications. It provides authentication context, theme configuration, and global providers for the entire application.

Type Signature

interface AppProps {
  /** App display name */
  name: string
  /** Authentication configuration */
  auth?: {
    provider: 'workos' | 'clerk' | 'auth0' | 'custom'
    clientId?: string
    loginUrl?: string
    redirectUri?: string
  }
  /** Child content */
  children: React.ReactNode
}

Usage

import type { AppComponents } from 'mdxui'

export const components: AppComponents = {
  App,
  Shell,
  Sidebar,
  Header,
  Dashboard,
  Settings,
}

In your MDX:

<App name="Acme Dashboard" auth={{ provider: 'workos' }}>
  <Shell>
    {/* Your app content */}
  </Shell>
</App>

Props

name

The display name of the application. Used in the browser title, meta tags, and default branding.

<App name="Acme Dashboard">

auth

Authentication provider configuration. Supports multiple providers:

WorkOS

<App
  name="Acme Dashboard"
  auth={{
    provider: 'workos',
    clientId: 'client_...',
    redirectUri: 'https://acme.com/auth/callback'
  }}
>

Clerk

<App
  name="Acme Dashboard"
  auth={{
    provider: 'clerk',
    clientId: 'pk_...',
  }}
>

Auth0

<App
  name="Acme Dashboard"
  auth={{
    provider: 'auth0',
    clientId: 'YOUR_CLIENT_ID',
    loginUrl: 'https://acme.auth0.com/authorize',
    redirectUri: 'https://acme.com/callback'
  }}
>

Custom

For custom authentication implementations:

<App
  name="Acme Dashboard"
  auth={{ provider: 'custom' }}
>

children

The application content, typically wrapped in a <Shell> component.

<App name="Acme Dashboard">
  <Shell>
    <Dashboard />
  </Shell>
</App>

App Hierarchy

The App component is the root of the application hierarchy:

App (Root Container)
├── Shell (Layout)
│   ├── Sidebar (Navigation)
│   ├── Header (Top Bar)
│   └── Main (Content Area)
│       └── View (Dashboard, Settings, etc.)
│           └── Panel (ListPanel, DetailPanel, etc.)
│               └── Component (primitives)

App Type Specializations

Different application types extend the base App with specific features:

DeveloperApp

API-focused application with developer tools.

DeveloperApp
├── DashboardView - API metrics and activity
├── KeysView - API key management
├── WebhooksView - Webhook configuration
├── UsageView - Usage analytics
├── LogsView - Request logs
└── SettingsView - Account settings

AdminApp

Administrative interface for managing collections.

AdminApp
├── DashboardView - System overview
├── CollectionView - CRUD for each collection
├── UsersView - User management
├── RolesView - Permission management
└── SettingsView - System settings

SaaSApp

Multi-tenant SaaS application.

SaaSApp
├── DashboardView - Product dashboard
├── ProductViews - Core product features
├── TeamView - Team management
├── BillingView - Subscription and billing
└── SettingsView - Account settings

CRMApp

Customer relationship management.

CRMApp
├── DashboardView - Sales metrics
├── ContactsView - Contact management
├── DealsView - Deal pipeline
├── ActivitiesView - Activity timeline
└── SettingsView - CRM configuration

See the App Hierarchy page for complete type mappings.

Context Providers

The App component automatically provides these contexts to descendant components:

AuthContext

interface AuthContext {
  user: User | null
  isAuthenticated: boolean
  login: () => void
  logout: () => void
}

ThemeContext

interface ThemeContext {
  mode: 'light' | 'dark' | 'system'
  setMode: (mode: ThemeMode) => void
}

AppContext

interface AppContext {
  name: string
  config: AppConfig
}

Integration with Payload CMS

The App component coordinates with Payload CMS for:

Authentication - Delegates to Payload's auth system
Collection mapping - Auto-wires components to collections
Access control - Enforces collection-level permissions

Best Practices

Single App per Application

Only render one <App> component at the root of your application:

// Good
<App name="Dashboard">
  <Shell>
    <Dashboard />
  </Shell>
</App>

// Bad - don't nest Apps
<App name="Outer">
  <App name="Inner">
    {/* ... */}
  </App>
</App>

Configure Auth Early

Set up authentication before rendering protected content:

<App
  name="Dashboard"
  auth={{
    provider: 'workos',
    clientId: process.env.WORKOS_CLIENT_ID
  }}
>
  {/* Auth is ready before this renders */}
  <Shell>
    <Dashboard />
  </Shell>
</App>

Use Environment Variables

Never hardcode credentials:

// Good
<App
  auth={{
    provider: 'clerk',
    clientId: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
  }}
>

// Bad
<App
  auth={{
    provider: 'clerk',
    clientId: 'pk_test_...' // Don't hardcode!
  }}
>

Shell - App shell layout
Dashboard - Main dashboard view
Settings - Settings page layout

App

On this page