React Admin Starter

A mock-first React admin starter with shadcn/ui, Tailwind CSS, React Hook Form, Zod, TanStack Table, and Vite — no backend required for the happy path.

🔍 Project Overview

This React admin starter is mock-first: an Axios in-memory adapter powers login, RBAC, and CRUD without a backend on the happy path. The stack combines shadcn/ui (Base UI + Tailwind), React Hook Form + Zod, TanStack Table, Zustand, TanStack Query, and React Router (history mode) on Vite.

The dashboard shell includes sidebar navigation, theme switching (light/dark + color presets), i18n (pt-BR and en-US), permission-driven routes and menus, a 403 page for unauthorized deep links, mock user management, and a read-only roles view. Smoke tests run with Vitest and GitHub Actions on every push.

🌟 Key Features

• 🏛️ Dashboard layout: Sidebar, header, settings sheet, breadcrumb, and authenticated routing.
• 🎨 Theme switching: Light/dark mode, 8 primary color presets, layout modes — persisted via Zustand.
• 🌍 i18n: pt-BR and en-US for login, chrome, management screens, and error pages.
• 🔐 RBAC: Permission tree drives dynamic routes and menu filtering; viewer vs admin roles.
• 🚫 403 handling: Unauthorized deep links under /management show a clear forbidden page.
• 👥 Mock user CRUD: Paginated TanStack Table, RHF+Zod modals, deactivate — gated by permissions.
• 🏷️ Roles list: Read-only view of roles and nested permissions in a Sheet.
• 🧩 B2B SaaS examples: Workbench analytics, Customers, Subscriptions, Invoices, Support tickets, API keys, and Audit logs under a recursive permission-driven menu.
• 📊 Analytics: Native Apache ECharts visualizations for revenue, MRR, plan mix, and acquisition; charts are intentionally read-only and do not use cross-filter state.
• 🗂️ Responsive data views: Shared listings can switch between table, card grid, and compact list modes. The selected mode is represented by the URL and follows responsive defaults on narrow screens.
• 🧪 Vitest tests: Mock adapter, stores, RBAC, admin components, and Zod schemas.
• ✅ CI: GitHub Actions runs lint, build, and tests on every push.
• 🚀 Vercel-ready: SPA rewrite for the history router; mock adapter in production demo builds.

📋 Prerequisites

• Node.js 20 or newer.
• pnpm 8.15.4 (see packageManager in package.json).

🚀 Running the Project

pnpm install
cp .env.example .env   # Windows: copy .env.example .env
pnpm dev

Open http://localhost:3001.

Script	What it does
pnpm dev	Start Vite dev server (port 3001)
pnpm build	Typecheck + production build
pnpm preview	Preview the production build locally
pnpm lint	ESLint on src/
pnpm format	Prettier write
pnpm test	Vitest (mock adapter + component tests)

🧪 Running Tests

pnpm test

Tests exercise the mock Axios adapter, Zustand stores, RBAC hooks, admin UI components, and Zod validation schemas.

🎭 Mock Data and Demo Accounts

User	Password	Access
admin	admin123	Workbench + system management (users CRUD, roles)
viewer	viewer123	Workbench only; management deep links return 403

Examples and mock reset

The Examples catalogue demonstrates a B2B SaaS operating model: Customers, Revenue (Subscriptions and Invoices), Support (Tickets), and Platform (API Keys and Audit Logs). Admin accounts can run the available mutations; viewer accounts can browse the business data in read-only mode while platform administration remains admin-only. Each list demonstrates the shared table, card-grid, and list presentation modes, and Invoices also exercises the third-level menu at Examples > Revenue > Invoices > List/New invoice.

All example data lives in the in-memory mock store. Changes remain available while the application is running and reset to the bundled seed data whenever the page is fully reloaded or the dev server is restarted. No data is sent to an external service; payment processing, email delivery, PDF generation, and backend persistence are intentionally out of scope.

Environment variables

Variable	Default	Purpose
VITE_USE_MOCK	true	true = Axios mock adapter; false = real API
VITE_APP_BASE_API	(empty)	API base URL when VITE_USE_MOCK=false
VITE_APP_HOMEPAGE	/workbench/overview	Post-login redirect target

UI Architecture

Application (pages, layouts)
    ↓
Admin Components (components/admin)
    ↓
UI Components (components/ui — shadcn source-owned)
    ↓
Base UI (@base-ui/react) + Tailwind CSS + CSS variables

Source available

This repository is a personal starter shared as a gift. Clone it, fork it, or copy it into your project and adapt it there — that is what the MIT license is for.

It is not a community project. I am not looking for pull requests, feature requests, or a contributor community. If you want to change something, do it in your own copy. Happy coding!