# @mdxui/app Abstract application framework layer for building admin interfaces and SaaS applications with React. Provides a "Bring Your Own Backend" architecture where you implement the data and auth providers while the framework handles UI composition, navigation, theming, and resource management. ## Installation ```bash npm install @mdxui/app @mdxui/primitives # or pnpm add @mdxui/app @mdxui/primitives # or yarn add @mdxui/app @mdxui/primitives ``` ## Quick Start ```tsx import { App, AppShell, NavMain, NavUser, Resource } from '@mdxui/app' import type { DataProvider, AuthProvider } from '@mdxui/app' import { Users, Package } from 'lucide-react' // 1. Implement your data provider const dataProvider: DataProvider = { getList: async (resource, params) => { const response = await fetch(`/api/${resource}`) const data = await response.json() return { data: data.items, total: data.total } }, getOne: async (resource, { id }) => { const response = await fetch(`/api/${resource}/${id}`) return { data: await response.json() } }, getMany: async (resource, { ids }) => { const response = await fetch(`/api/${resource}?ids=${ids.join(',')}`) return { data: await response.json() } }, create: async (resource, { data }) => { const response = await fetch(`/api/${resource}`, { method: 'POST', body: JSON.stringify(data), }) return { data: await response.json() } }, update: async (resource, { id, data }) => { const response = await fetch(`/api/${resource}/${id}`, { method: 'PUT', body: JSON.stringify(data), }) return { data: await response.json() } }, delete: async (resource, { id }) => { const response = await fetch(`/api/${resource}/${id}`, { method: 'DELETE' }) return { data: await response.json() } }, } // 2. Implement your auth provider const authProvider: AuthProvider = { login: async ({ username, password }) => { await fetch('/api/auth/login', { method: 'POST', body: JSON.stringify({ username, password }), }) }, logout: async () => { await fetch('/api/auth/logout', { method: 'POST' }) }, checkAuth: async () => { const response = await fetch('/api/auth/me') if (!response.ok) throw new Error('Not authenticated') }, checkError: async (error) => { if (error.message === 'Unauthorized') throw error }, getIdentity: async () => { const response = await fetch('/api/auth/me') return response.json() }, getPermissions: async () => { const response = await fetch('/api/auth/permissions') return response.json() }, } // 3. Define your resources const resources = [ { name: 'users', label: 'Users', icon: Users, list: UsersList, edit: UserEdit }, { name: 'products', label: 'Products', icon: Package, list: ProductsList }, ] // 4. Build your app function MyAdmin() { return ( } footer={} > {/* Your routes/content here */} ) } ``` ## Core Concepts ### Bring Your Own Backend `@mdxui/app` doesn't dictate your backend. You implement two interfaces: - **DataProvider**: 6-method interface for CRUD operations - **AuthProvider**: 6-method interface for authentication This lets you connect to any API, database, or backend service. ### Resources Resources are the core building blocks. Each resource represents an entity (users, products, orders) that can be listed, created, edited, and deleted. ```tsx const usersResource: ResourceDefinition = { name: 'users', // Used in URLs and data provider calls label: 'User', // Singular label labelPlural: 'Users', // Plural label icon: Users, // Lucide icon for navigation list: UsersList, // List view component show: UserShow, // Detail view component create: UserCreate, // Create form component edit: UserEdit, // Edit form component } ``` ### Provider Composition The `App` component composes all necessary providers in the correct order: ``` ThemeProvider └─ NavigationProvider └─ DataProviderProvider └─ AuthProvider └─ ResourcesProvider └─ AppProvider └─ Your Content ``` ## API Reference ### Providers #### DataProviderProvider & useDataProvider Provides data access throughout your application. ```tsx import { DataProviderProvider, useDataProvider } from '@mdxui/app' // Wrap your app // Use in components function UsersList() { const dataProvider = useDataProvider() useEffect(() => { dataProvider.getList('users', { pagination: { page: 1, perPage: 10 }, sort: { field: 'name', order: 'ASC' }, filter: { status: 'active' }, }).then(({ data, total }) => { // Handle data }) }, []) } ``` **DataProvider Interface:** | Method | Params | Returns | |--------|--------|---------| | `getList` | `{ pagination?, sort?, filter? }` | `{ data: T[], total?, pageInfo? }` | | `getOne` | `{ id }` | `{ data: T }` | | `getMany` | `{ ids }` | `{ data: T[] }` | | `create` | `{ data }` | `{ data: T }` | | `update` | `{ id, data, previousData? }` | `{ data: T }` | | `delete` | `{ id, previousData? }` | `{ data: T }` | #### AuthProvider & useAuth Manages authentication state and operations. ```tsx import { AuthProvider, useAuth } from '@mdxui/app' // Wrap your app // Use in components function LoginPage() { const { login, isLoading } = useAuth() const handleSubmit = async (data) => { await login({ username: data.email, password: data.password }) } } function Dashboard() { const { isAuthenticated, identity, logout, permissions } = useAuth() if (!isAuthenticated) { return } return

Welcome, {identity?.fullName}!

} ``` **AuthProvider Interface:** | Method | Purpose | |--------|---------| | `login(params)` | Authenticate user with credentials | | `logout()` | End user session | | `checkAuth()` | Verify current auth state (throws if not authenticated) | | `checkError(error)` | Handle auth errors (e.g., 401 responses) | | `getIdentity()` | Get current user info | | `getPermissions()` | Get user permissions/roles | **useAuth Return Value:** ```tsx interface AuthContextValue { isAuthenticated: boolean identity?: UserIdentity permissions?: string[] isLoading: boolean login: (params: LoginParams) => Promise logout: () => Promise refreshAuth: () => Promise } ``` #### NavigationProvider & useNavigation Integrates with your routing library (react-router, Next.js, etc.). ```tsx import { NavigationProvider, useNavigation } from '@mdxui/app' import { Link as RouterLink, useNavigate, useLocation } from 'react-router-dom' // Create adapter for react-router const navigationProvider = { navigate: (to, options) => navigate(to, options), getCurrentPath: () => location.pathname, LinkComponent: ({ href, children, className }) => ( {children} ), } // Use in components function MyComponent() { const { navigate, getCurrentPath, Link } = useNavigation() return (

Go to Dashboard