aether-core-ui

White-label React dashboard UI kit. Provides an app shell, theming, layout components, data components, and a section registry — all driven by a single JSON config.

Install

npm install aether-core-ui

Peer dependencies your app needs:

npm install react react-dom react-router-dom @tanstack/react-query @tanstack/react-table lucide-react nuqs react-hook-form recharts tailwindcss

Quick start

1. Create customer.config.json

{
  "name": "My App",
  "logo": "/logo.png",
  "apiBaseUrl": "https://api.example.com",
  "theme": {
    "colors": {
      "primary": "#6366F1",
      "primaryLight": "#818CF8",
      "primaryDark": "#4F46E5",
      "accent": "#A78BFA",
      "sidebar": "#0A0A0A",
      "sidebarText": "#6B6B6B",
      "sidebarActive": "#6366F1",
      "background": "#111111",
      "surface": "#1A1A1A",
      "text": "#F2F2F2",
      "textMuted": "#888888",
      "border": "#2A2A2A",
      "success": "#22C55E",
      "warning": "#F59E0B",
      "danger": "#EF4444"
    },
    "typography": {
      "fontFamily": "Inter, system-ui, sans-serif",
      "headingFontFamily": "'Poiret One', system-ui, sans-serif"
    }
  },
  "sections": [
    { "id": "dashboard", "label": "Dashboard", "icon": "LayoutDashboard", "home": true },
    { "id": "settings", "label": "Settings", "icon": "Settings", "placement": "bottom" }
  ]
}

2. Register sections and render the app

// App.tsx
import { AetherApp, registerSection } from 'aether-core-ui'
import config from './customer.config.json'
import Home from './pages/Home'
import Settings from './pages/Settings'

registerSection('dashboard', Home)
registerSection('settings', Settings)

export default function App() {
  return <AetherApp config={config} />
}

3. Import styles (Tailwind CSS 4)

/* index.css */
@import "tailwindcss";
@source "../node_modules/aether-core-ui/dist/aether-core-ui.js";
@import "aether-core-ui/styles";

The @source directive tells Tailwind to scan the library bundle for utility classes.

4. Build a section page

Every registered section receives its SectionConfig as a prop:

import type { SectionConfig } from 'aether-core-ui'
import { PageWrapper, StatCard, EmptyState } from 'aether-core-ui'
import { LayoutDashboard } from 'lucide-react'

export default function Home({ section }: { section: SectionConfig }) {
  return (
    <PageWrapper>
      <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
        <StatCard icon={LayoutDashboard} label="Total Items" value="128" />
        <StatCard icon={LayoutDashboard} label="Active" value="42" />
        <StatCard icon={LayoutDashboard} label="Revenue" value="$9,400" />
      </div>
    </PageWrapper>
  )
}

Exports

App shell

| Export | Description | |---|---| | AetherApp | Root shell — routing, auth, toast, initial load experience | | AetherProvider | Context provider (config + theme) | | useAetherConfig | Access the current CustomerConfig | | AuthGate | Auth wrapper, redirects unauthenticated users | | SectionRoute | Resolves a section by id and renders it |

Section registry

| Export | Description | |---|---| | registerSection(id, Component) | Register a React component for a section id | | getSection(section) | Look up a registered section |

Layout

| Export | Description | |---|---| | DashboardLayout | Main layout with sidebar | | Sidebar | Navigation sidebar | | Header | Top header bar | | PageWrapper | Content area wrapper | | CommandPalette | Command palette (Cmd+K) | | resolveIcon / registerIcons | Lucide icon name resolution |

Data components

| Export | Description | |---|---| | DataTable | Sortable/filterable data table | | StatCard | Metric display card | | FilterBar | Filter controls | | EmptyState | Empty state placeholder | | TableSkeleton | Table loading skeleton |

Primitives

| Export | Description | |---|---| | Button | Button component | | Dialog / DialogTrigger / DialogContent / ... | Modal dialog (Radix) | | DropdownMenu / DropdownMenuTrigger / ... | Dropdown menu (Radix) | | Tooltip / TooltipTrigger / TooltipContent / ... | Tooltip (Radix) | | Avatar | Avatar component (Radix) | | Skeleton | Loading placeholder | | ToastProvider / useToast | Toast notifications (Radix) |

API helpers

| Export | Description | |---|---| | createApiFetcher(baseUrl) | Create a fetch wrapper with credentials | | useApi | Access the API fetcher from context | | useMe / useLogin / useLogout | Auth hooks | | useSectionData | Fetch section data | | useSectionMutation | Mutate section data |

Utilities

| Export | Description | |---|---| | cn(...classes) | Class name merger (clsx + tailwind-merge) | | assetPath(path) | Resolve asset URLs | | useCountUp(target) | Count-up animation hook | | applyTheme(theme) | Apply theme config as CSS variables |

Types

import type { CustomerConfig, SectionConfig, ThemeConfig } from 'aether-core-ui'

Theming

All colors are applied as CSS custom properties (--c-primary, --c-background, etc.) via applyTheme. Override them by changing the theme.colors object in your config.

Template

The template/ directory contains a minimal consumer app. Copy it to bootstrap a new project:

cp -r node_modules/aether-core-ui/template my-app
cd my-app
npm install
npm run dev

License

MIT