obs-admin-dashboard

A ready-to-use admin dashboard base package for React apps. It provides the core infrastructure — API layer, layouts, sidebar navigation, shared components, and a DashboardProvider — that you can drop into any React application as a starting point.

Installation

npm install obs-admin-dashboard

react and react-dom are peer dependencies — make sure they're installed in your app.

Quick Start

The package ships with two usage styles:

1. Use the DashboardProvider (all-in-one)

Wrap your app with DashboardProvider to get a configured QueryClient, theme, tooltips, and toasts:

import { DashboardProvider, AppLayout } from "obs-admin-dashboard"
import "obs-admin-dashboard/styles.css"

function App() {
  return (
    <DashboardProvider
      config={{
        apiUrl: "https://your-api.example.com",
        theme: "system",
        toastPosition: "top-center",
      }}
    >
      <AppLayout navItems={myNavItems} brandName="My Company" logoUrl="/logo.png">
        {/* your routed content */}
      </AppLayout>
    </DashboardProvider>
  )
}

2. Use individual exports

Import only what you need for tree-shaking:

import { DataTable, DataPagination, SearchBar, ConfirmDialog } from "obs-admin-dashboard"
import { useGetItems } from "./my-feature/hooks" // your feature logic

Exports

Provider

| Export | Description | |--------|-------------| | DashboardProvider | Sets up QueryClient, ThemeProvider, TooltipProvider, and Toaster | | DashboardConfig | Config type (apiUrl, theme, toastPosition, navItems) |

API Layer

| Export | Description | |--------|-------------| | apiClient | Axios instance with Bearer token + refresh queue | | authClient | Axios instance for unauthenticated requests (login/register) | | CrudService<T> | Base class with typed getAll, getById, create, update, delete | | BASE_URL | The configured API base URL | | ApiResponse<T>, PaginatedApiResponse<T>, PaginatedMeta | API response types |

Layout

| Export | Description | |--------|-------------| | AppLayout | Authenticated shell with sidebar + outlet (navItems, brandName, logoUrl, sidebarFooter, redirectPath) | | AuthLayout | Centered card layout for login/OTP/password flows | | AppHeader | Page header with title/total/action button or dropdown | | AppSidebar | Collapsible sidebar with search, nav, and user footer |

Sidebar

| Export | Description | |--------|-------------| | SidebarNav | Navigation menu (items prop overrides defaults) | | SidebarUserFooter | User profile + logout footer | | NavItem, NavChild | Nav item types |

Shared Components

| Export | Description | |--------|-------------| | DataTable | TanStack Table v8 wrapper | | DataPagination | Server-side pagination with page-size selector | | SearchBar | Debounced search input synced to URL params | | ConfirmDialog | Delete/confirm alert dialog | | ErrorBoundary | React error boundary | | ThemeProvider, useTheme | Theme context |

UI Components (shadcn/ui)

Re-exported shadcn primitives: Button, Input, Label, Dialog, AlertDialog, Card, Select, Table, Form, DropdownMenu, Sidebar (+ useSidebar).

Utilities & Hooks

• cn — clsx + tailwind-merge utility
• useIsMobile — responsive breakpoint hook

Styles

Import the package styles in your app's CSS entry (requires Tailwind v4 with the @tailwindcss/vite plugin):

@import "obs-admin-dashboard/styles.css";

API Configuration

Set the API base URL via an environment variable:

VITE_API_URL=https://your-api.example.com

apiClient automatically attaches Bearer tokens from localStorage.accessToken and handles token refresh on 401.

Feature Modules

Business logic lives in src/feature/[name]/ — each feature is self-contained with types.ts, services/, hooks/, components/, page/, and routes/routes.tsx. See src/feature/CLAUDE.md for the two supported patterns (dialog-based and page-based).

Commands

npm run dev          # Start dev server
npm run build        # Type-check + Vite app build
npm run build:lib    # Build ESM + UMD + type declarations for publishing
npm run typecheck    # tsc --noEmit
npm run lint         # ESLint
npm run format       # Prettier
npm pack             # Dry-run check of publishable files

Publishing

npm run build:lib
npm publish