Getting Started with Sofondo Framework

Quick start guide to build your first admin panel with the Sofondo Framework.

What is Sofondo?

Sofondo is a modern React framework for building beautiful, accessible admin panels and dashboards. It provides:

Pre-built UI components (data grids, progress bars, stat cards, etc.)
Layout components (sidebar, header, admin layout)
Theme system (light/dark/system modes)
Configuration system with TypeScript support
Responsive design out of the box
Accessibility built-in

Prerequisites

Before you start, make sure you have:

Node.js 18+ installed
npm, yarn, or pnpm package manager
Basic knowledge of React and TypeScript
Next.js 15+ (recommended) or React 18+

Quick Start (5 minutes)

Step 1: Create a New Next.js Project

npx create-next-app@latest my-admin-panel
cd my-admin-panel

When prompted, select these options:

TypeScript: Yes
ESLint: Yes
Tailwind CSS: No (Sofondo includes its own styles)
App Router: Yes
Import alias: @/* (or your preference)

Step 2: Install Sofondo Packages

npm install @sofondo/core @sofondo/react @sofondo/styles @sofondo/next

Optional dependencies for icons and animations:

npm install framer-motion lucide-react clsx

Step 3: Configure Next.js

Update next.config.ts to transpile Sofondo packages:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  transpilePackages: [
    '@sofondo/core',
    '@sofondo/react',
    '@sofondo/styles',
    '@sofondo/next'
  ],
};

export default nextConfig;

Step 4: Create Configuration File

Create sofondo.config.ts in your project root:

import { defineConfig } from '@sofondo/core';

export default defineConfig({
  theme: {
    defaultMode: 'system',
    enableSwitcher: true,
  },
  sidebar: {
    defaultCollapsed: false,
    width: 240,
  },
  animations: {
    enabled: true,
  },
});

Step 5: Set Up Providers

Update app/layout.tsx to include Sofondo providers:

import { ConfigProvider, ThemeProvider, ToastProvider } from '@sofondo/react';
import config from '../sofondo.config';
import '@sofondo/styles/global.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ConfigProvider config={config}>
          <ThemeProvider>
            <ToastProvider>
              {children}
            </ToastProvider>
          </ThemeProvider>
        </ConfigProvider>
      </body>
    </html>
  );
}

Step 6: Create Admin Layout

Create app/(admin)/layout.tsx:

import { AdminLayout } from '@sofondo/next';
import { Home, Users, Settings, Database, BarChart } from 'lucide-react';

const menuItems = [
  {
    icon: Home,
    label: 'Dashboard',
    href: '/',
    exact: true,
  },
  {
    icon: Users,
    label: 'Users',
    href: '/users',
  },
  {
    icon: Database,
    label: 'Database',
    href: '/database',
  },
  {
    icon: BarChart,
    label: 'Analytics',
    href: '/analytics',
  },
  {
    icon: Settings,
    label: 'Settings',
    href: '/settings',
  },
];

export default function AdminLayoutWrapper({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <AdminLayout
      menuItems={menuItems}
      user={{
        name: 'John Doe',
        email: 'john@example.com',
      }}
    >
      {children}
    </AdminLayout>
  );
}

Step 7: Create Your Dashboard Page

Create app/(admin)/page.tsx:

import { PageHeader, StatCard, StatGrid } from '@sofondo/react';
import { Users, Activity, DollarSign, TrendingUp } from 'lucide-react';

export default function Dashboard() {
  return (
    <>
      <PageHeader
        title="Dashboard"
        subtitle="Welcome to your admin panel"
      />

      <StatGrid>
        <StatCard
          icon={Users}
          label="Total Users"
          value="1,234"
          change="+12% from last month"
          changeClassName="positive"
        />
        <StatCard
          icon={Activity}
          label="Active Sessions"
          value="89"
          change="Live now"
          changeClassName="positive"
        />
        <StatCard
          icon={DollarSign}
          label="Revenue"
          value="$12,345"
          change="+8% from last month"
          changeClassName="positive"
        />
        <StatCard
          icon={TrendingUp}
          label="Growth Rate"
          value="23%"
          change="+3% from last month"
          changeClassName="positive"
        />
      </StatGrid>
    </>
  );
}

Step 8: Run Your App

npm run dev

Visit http://localhost:3000 and you’ll see your admin panel with:

Collapsible sidebar navigation
Theme switcher (light/dark/system)
Dashboard with statistics
Responsive layout

Understanding the Structure

Route Groups

The (admin) folder is a Next.js route group that applies the admin layout to all pages inside it:

app/
├── layout.tsx          # Root layout with providers
└── (admin)/
    ├── layout.tsx      # Admin layout with sidebar
    ├── page.tsx        # Dashboard page
    ├── users/
    │   └── page.tsx    # Users page
    └── settings/
        └── page.tsx    # Settings page

Providers

Sofondo uses React Context providers for configuration and features:

ConfigProvider - Provides configuration to all components
ThemeProvider - Manages theme state (light/dark/system)
ToastProvider - Enables toast notifications

Always wrap in this order: ConfigProvider → ThemeProvider → ToastProvider

Adding More Pages

Create a Users Page

Create app/(admin)/users/page.tsx:

import { PageHeader, DataGrid } from '@sofondo/react';

const users = [
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com', role: 'User' },
  { id: 3, name: 'Carol Davis', email: 'carol@example.com', role: 'User' },
];

export default function UsersPage() {
  return (
    <>
      <PageHeader
        title="Users"
        subtitle="Manage your users"
        actions={<button>Add User</button>}
      />

      <DataGrid
        data={users}
        keyField="id"
        columns={[
          { key: 'name', header: 'Name', width: '2fr' },
          { key: 'email', header: 'Email', width: '2fr' },
          { key: 'role', header: 'Role', width: '1fr' },
        ]}
      />
    </>
  );
}

Create a Settings Page

Create app/(admin)/settings/page.tsx:

'use client';

import { PageHeader } from '@sofondo/react';
import { useTheme, useToast } from '@sofondo/react';

export default function SettingsPage() {
  const { theme, mode, setMode } = useTheme();
  const { addToast } = useToast();

  const handleSave = () => {
    addToast('Settings saved successfully!', 'success');
  };

  return (
    <>
      <PageHeader
        title="Settings"
        subtitle="Configure your preferences"
      />

      <div style={{ padding: '20px' }}>
        <h3>Theme Mode</h3>
        <p>Current theme: {theme}</p>
        <p>Current mode: {mode}</p>

        <button onClick={() => setMode('light')}>Light Mode</button>
        <button onClick={() => setMode('dark')}>Dark Mode</button>
        <button onClick={() => setMode('system')}>System Mode</button>

        <br /><br />
        <button onClick={handleSave}>Save Settings</button>
      </div>
    </>
  );
}

Common Components

DataGrid

Display tabular data with sorting and custom rendering:

import { DataGrid } from '@sofondo/react';

<DataGrid
  data={items}
  keyField="id"
  columns={[
    { key: 'name', header: 'Name', width: '2fr' },
    { key: 'status', header: 'Status', width: '1fr' },
    {
      key: 'actions',
      header: 'Actions',
      width: '1fr',
      render: (item) => (
        <button onClick={() => handleEdit(item)}>Edit</button>
      ),
    },
  ]}
/>

ProgressBar

Show progress or usage indicators:

import { ProgressBar } from '@sofondo/react';
import { getStorageStatus, getStorageColor } from '@sofondo/core';

const usage = 75;
const max = 100;
const status = getStorageStatus(usage, max);
const color = getStorageColor(status);

<ProgressBar value={usage} max={max} color={color} />

Skeleton

Loading placeholders:

import { Skeleton } from '@sofondo/react';

{loading ? (
  <>
    <Skeleton width="100%" height={40} />
    <Skeleton width="100%" height={40} />
    <Skeleton width="100%" height={40} />
  </>
) : (
  <DataGrid data={data} columns={columns} keyField="id" />
)}

Toast Notifications

'use client';

import { useToast } from '@sofondo/react';

export function MyComponent() {
  const { addToast } = useToast();

  return (
    <button onClick={() => addToast('Action completed!', 'success')}>
      Do Something
    </button>
  );
}

Common Hooks

useTheme

Control theme programmatically:

'use client';

import { useTheme } from '@sofondo/react';

export function ThemeSwitcher() {
  const { theme, mode, setMode, toggleTheme } = useTheme();

  return (
    <div>
      <p>Current theme: {theme}</p>
      <button onClick={toggleTheme}>Toggle Theme</button>
      <button onClick={() => setMode('dark')}>Dark Mode</button>
    </div>
  );
}

useConfig

Access configuration:

import { useConfig, useConfigSection } from '@sofondo/react';

export function MyComponent() {
  const config = useConfig();
  const sidebarConfig = useConfigSection('sidebar');

  return <div>Sidebar width: {sidebarConfig.width}px</div>;
}

useMediaQuery

Responsive behavior:

'use client';

import { useMediaQuery } from '@sofondo/react';

export function ResponsiveComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)');

  return (
    <div>
      {isMobile ? <MobileView /> : <DesktopView />}
    </div>
  );
}

Customization

Custom Theme Colors

Update your sofondo.config.ts:

export default defineConfig({
  theme: {
    defaultMode: 'system',
    enableSwitcher: true,
    colors: {
      light: {
        '--primary': '#0066cc',
        '--background': '#ffffff',
        '--text': '#000000',
      },
      dark: {
        '--primary': '#3399ff',
        '--background': '#0a0a0a',
        '--text': '#ffffff',
      },
    },
  },
});

export default defineConfig({
  sidebar: {
    defaultCollapsed: false,
    width: 280,              // Custom width
    collapsedWidth: 60,
    enableTooltips: true,
  },
});

Disable Animations

export default defineConfig({
  animations: {
    enabled: false,           // Disable all animations
  },
});

TypeScript Support

Sofondo is built with TypeScript and provides full type safety:

import type { MenuItem, Column, BreadcrumbItem } from '@sofondo/core';
import type { StatCardProps } from '@sofondo/react';

const menuItems: MenuItem[] = [
  { icon: Home, label: 'Dashboard', href: '/' },
];

interface User {
  id: number;
  name: string;
  email: string;
}

const columns: Column<User>[] = [
  { key: 'name', header: 'Name' },
  { key: 'email', header: 'Email' },
];

Next Steps

Now that you have a working admin panel:

Explore Components - Check the API Reference for all available components
Customize Configuration - See Configuration Guide for all options
Learn Patterns - Read API Design Standards for best practices
Migrate Existing App - Follow the Migration Strategy guide

Common Issues

Module Not Found

If you see Module not found: Can't resolve '@sofondo/core':

Check transpilePackages in next.config.ts
Restart dev server: npm run dev
Clear cache: rm -rf .next && npm run dev

Styles Not Applied

If components look unstyled:

Make sure you imported @sofondo/styles/global.css in app/layout.tsx
Check that import is before your custom styles
Verify @sofondo/styles is installed

Hook Errors

If you see useConfig must be used within a ConfigProvider:

Make sure <ConfigProvider> wraps your app in app/layout.tsx
Verify providers are in correct order
Check that you’re using hooks inside the provider tree

TypeScript Errors

If you see TypeScript errors:

Import types: import type { MenuItem } from '@sofondo/core'
Restart TypeScript server in your IDE
Check package versions match

Resources

API Reference - Complete component and hook documentation
Configuration Guide - All configuration options
Migration Strategy - Migrate existing projects
API Design Standards - Best practices and patterns
Build System Notes - Production build strategies

Getting Help

If you encounter issues:

Check the Troubleshooting section above
Review the documentation links
Check your configuration matches the examples
Verify all packages are installed correctly

Summary

You now have a working admin panel with:

✅ Responsive sidebar navigation
✅ Theme switching (light/dark/system)
✅ Dashboard with statistics
✅ Data grid for tables
✅ Toast notifications
✅ Loading skeletons
✅ Progress indicators
✅ Full TypeScript support

Start building your admin panel by adding more pages and customizing the components to match your needs!