446 lines
14 KiB
Markdown
446 lines
14 KiB
Markdown
# Dashboard Recreation Plan: Next.js 14 + shadcn/ui
|
|
|
|
## Overview
|
|
Recreate the main dashboard page from https://shadcnblocks-admin.vercel.app/ using Next.js 14 App Router, shadcn/ui components, TypeScript, Chart.js, Inter font, and dark/light theme support with mock data.
|
|
|
|
## Project Status
|
|
- **Current State**: Empty directory (only readme.md exists)
|
|
- **Target**: Full-featured dashboard with sidebar navigation, metrics, charts, and data tables
|
|
|
|
---
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: Project Foundation (30 min)
|
|
|
|
#### 1. Initialize Next.js 14 Project
|
|
```bash
|
|
cd /e/repos/claude/shadcn-dashboard
|
|
npx create-next-app@latest . --typescript --tailwind --app --no-src-dir --import-alias "@/*"
|
|
```
|
|
Choose: TypeScript ✓, ESLint ✓, Tailwind CSS ✓, App Router ✓, No src/ directory
|
|
|
|
#### 2. Initialize shadcn/ui
|
|
```bash
|
|
npx shadcn@latest init
|
|
```
|
|
Choose: Default style, Slate base color, CSS variables ✓
|
|
|
|
#### 3. Install Dependencies
|
|
```bash
|
|
npm install chart.js react-chartjs-2 next-themes lucide-react date-fns
|
|
npm install -D @types/node
|
|
```
|
|
|
|
#### 4. Install shadcn/ui Components
|
|
```bash
|
|
npx shadcn@latest add button card table dropdown-menu tabs avatar badge separator input sidebar command dialog
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 2: Theme & Layout Foundation (45 min)
|
|
|
|
#### 5. Create Theme Provider
|
|
**File**: [components/theme-provider.tsx](components/theme-provider.tsx)
|
|
- Wrap next-themes provider
|
|
- Export ThemeProvider component
|
|
|
|
#### 6. Configure Root Layout
|
|
**File**: [app/layout.tsx](app/layout.tsx)
|
|
- Import Inter font from next/font/google
|
|
- Wrap with ThemeProvider (attribute="class", defaultTheme="system")
|
|
- Wrap with SidebarProvider
|
|
- Add suppressHydrationWarning to html tag
|
|
|
|
#### 7. Create Theme Toggle Component
|
|
**File**: [components/layout/theme-toggle.tsx](components/layout/theme-toggle.tsx)
|
|
- Use useTheme() hook
|
|
- Dropdown menu: Light, Dark, System options
|
|
- Sun/Moon icons from lucide-react
|
|
|
|
#### 8. Build Sidebar Navigation
|
|
**File**: [components/layout/app-sidebar.tsx](components/layout/app-sidebar.tsx)
|
|
- Use shadcn/ui Sidebar components
|
|
- Navigation structure:
|
|
- **General**: Dashboard (3 sub-items), Tasks, Users
|
|
- **Pages**: Auth, Errors
|
|
- **Other**: Settings, Developers
|
|
- Icons from lucide-react
|
|
- User profile section in footer
|
|
|
|
**File**: [components/layout/user-nav.tsx](components/layout/user-nav.tsx)
|
|
- Avatar with dropdown menu
|
|
- Options: Profile, Settings, Sign out
|
|
|
|
#### 9. Create Header Component
|
|
**File**: [components/layout/header.tsx](components/layout/header.tsx)
|
|
- Left: SidebarTrigger button
|
|
- Center: Command palette button (⌘K)
|
|
- Right: ThemeToggle component
|
|
- Sticky positioning with backdrop blur
|
|
|
|
---
|
|
|
|
### Phase 3: Data Layer (20 min)
|
|
|
|
#### 10. Define TypeScript Interfaces
|
|
**File**: [types/dashboard.ts](types/dashboard.ts)
|
|
```typescript
|
|
interface MetricCard {
|
|
id: string;
|
|
title: string;
|
|
value: string | number;
|
|
change: number;
|
|
changeLabel: string;
|
|
}
|
|
|
|
interface Payment {
|
|
id: string;
|
|
status: 'success' | 'processing' | 'failed';
|
|
email: string;
|
|
amount: number;
|
|
}
|
|
|
|
interface TeamMember {
|
|
id: string;
|
|
name: string;
|
|
email: string;
|
|
role: string;
|
|
avatar: string;
|
|
}
|
|
|
|
interface ChartDataPoint {
|
|
label: string;
|
|
value: number;
|
|
secondaryValue?: number;
|
|
}
|
|
|
|
interface DashboardData {
|
|
metrics: MetricCard[];
|
|
revenueData: ChartDataPoint[];
|
|
salesData: ChartDataPoint[];
|
|
payments: Payment[];
|
|
team: TeamMember[];
|
|
}
|
|
```
|
|
|
|
#### 11. Create Mock Data
|
|
**File**: [lib/mock-data.ts](lib/mock-data.ts)
|
|
|
|
Generate realistic data:
|
|
- **Metrics** (4 cards):
|
|
- New Subscriptions: 4,682 (+15.54%)
|
|
- New Orders: 1,226 (+40.2%)
|
|
- Avg Order Revenue: 1,080 (+10.8%)
|
|
- Total Revenue: $15,231.89 (+20.1%)
|
|
|
|
- **Revenue Chart**: 6 months of trend data
|
|
- **Sales Chart**: 12 months of bar data
|
|
- **Payments Table**: 12-15 transaction entries
|
|
- **Team Table**: 6-8 member entries
|
|
|
|
Export `getDashboardData()` function
|
|
|
|
---
|
|
|
|
### Phase 4: Chart Components (45 min)
|
|
|
|
#### 12. Configure Chart.js
|
|
**File**: [lib/chart-config.ts](lib/chart-config.ts)
|
|
- Register Chart.js components (CategoryScale, LinearScale, PointElement, LineElement, BarElement, Tooltip, Legend)
|
|
- Define default options
|
|
- Export `getChartColors(theme)` for theme-aware styling
|
|
|
|
#### 13. Create Line Chart Component
|
|
**File**: [components/charts/line-chart.tsx](components/charts/line-chart.tsx)
|
|
- Mark as "use client"
|
|
- Use dynamic import with `{ ssr: false }`
|
|
- Accept props: data, options, height
|
|
- Apply theme-aware colors using useTheme()
|
|
|
|
#### 14. Create Bar Chart Component
|
|
**File**: [components/charts/bar-chart.tsx](components/charts/bar-chart.tsx)
|
|
- Similar to LineChart but using Bar from react-chartjs-2
|
|
- "use client" directive
|
|
- Theme-aware colors
|
|
|
|
---
|
|
|
|
### Phase 5: Dashboard Components (90 min)
|
|
|
|
#### 15. Create Metric Card
|
|
**File**: [components/dashboard/metric-card.tsx](components/dashboard/metric-card.tsx)
|
|
- Use Card component
|
|
- Display: title, value, change percentage (colored), change label
|
|
- Add TrendingUp/TrendingDown icon based on change
|
|
|
|
#### 16. Build Revenue Chart Component
|
|
**File**: [components/dashboard/revenue-chart.tsx](components/dashboard/revenue-chart.tsx)
|
|
- Use LineChart component
|
|
- Dual-line display (Revenue + Subscriptions)
|
|
- Wrap in Card with title
|
|
|
|
#### 17. Build Sales Activity Chart
|
|
**File**: [components/dashboard/sales-chart.tsx](components/dashboard/sales-chart.tsx)
|
|
- Use BarChart component
|
|
- 12-month bar display
|
|
- Wrap in Card with title
|
|
|
|
#### 18. Create Payments Table
|
|
**File**: [components/dashboard/payments-table.tsx](components/dashboard/payments-table.tsx)
|
|
- Use Table components
|
|
- Columns: Status (Badge), Email, Amount (formatted), Actions (DropdownMenu)
|
|
- Color-coded status badges (green/yellow/red)
|
|
- Wrap in Card with title
|
|
|
|
#### 19. Create Team Members Table
|
|
**File**: [components/dashboard/team-table.tsx](components/dashboard/team-table.tsx)
|
|
- Use Table components
|
|
- Columns: Member (Avatar + name), Email, Role
|
|
- Wrap in Card with title
|
|
|
|
#### 20. Create Dashboard Tabs
|
|
**File**: [components/dashboard/dashboard-tabs.tsx](components/dashboard/dashboard-tabs.tsx)
|
|
- Use Tabs component
|
|
- Four tabs: Overview (active), Analytics, Reports, Notifications (last 3 disabled)
|
|
- Overview contains all dashboard content
|
|
|
|
---
|
|
|
|
### Phase 6: Assembly & Polish (60 min)
|
|
|
|
#### 21. Build Main Dashboard Page
|
|
**File**: [app/page.tsx](app/page.tsx)
|
|
- Import all dashboard components
|
|
- Call getDashboardData()
|
|
- Layout structure:
|
|
- Page header with title
|
|
- DashboardTabs wrapper
|
|
- Metric cards grid (1→2→4 cols responsive)
|
|
- Charts row (1→2 cols responsive)
|
|
- Tables row (1→2 cols responsive)
|
|
|
|
#### 22. Configure Inter Font
|
|
**File**: [app/layout.tsx](app/layout.tsx)
|
|
- Import Inter from next/font/google
|
|
- Apply to body with className
|
|
|
|
#### 23. Add Custom Styling
|
|
**File**: [app/globals.css](app/globals.css)
|
|
- Smooth transitions for theme changes
|
|
- Custom scrollbar styling
|
|
- Hover effects
|
|
- Focus states
|
|
|
|
#### 24. Create Avatar Placeholders
|
|
**Directory**: [public/avatars/](public/avatars/)
|
|
- Create 01.png through 08.png
|
|
- Use UI Avatars service or placeholder images
|
|
- Ensure Avatar components have fallback initials
|
|
|
|
---
|
|
|
|
### Phase 7: Testing & Refinement (30 min)
|
|
|
|
#### 25. Development Testing
|
|
```bash
|
|
npm run dev
|
|
```
|
|
Test checklist:
|
|
- ✓ Dashboard loads at localhost:3000
|
|
- ✓ Theme toggle works (light/dark/system)
|
|
- ✓ Sidebar collapse/expand
|
|
- ✓ All metric cards display
|
|
- ✓ Charts render with data
|
|
- ✓ Tables show all entries
|
|
- ✓ Responsive design works
|
|
- ✓ Command palette (⌘K) opens
|
|
- ✓ No TypeScript errors
|
|
|
|
#### 26. Build Optimization
|
|
```bash
|
|
npm run build
|
|
npm start
|
|
```
|
|
Verify:
|
|
- No build errors
|
|
- Reasonable bundle size
|
|
- Chart.js code-split properly
|
|
- Production performance good
|
|
|
|
#### 27. Final Polish
|
|
- Add loading states for charts
|
|
- Add empty states for tables
|
|
- Improve accessibility (ARIA labels)
|
|
- Add tooltips where helpful
|
|
- Refine responsive breakpoints
|
|
|
|
---
|
|
|
|
## Critical Files to Create (22 total)
|
|
|
|
### Configuration (Auto-generated)
|
|
- package.json, tsconfig.json, tailwind.config.ts, next.config.js, components.json
|
|
|
|
### Application Core
|
|
1. [app/layout.tsx](app/layout.tsx) - Root layout with providers
|
|
2. [app/page.tsx](app/page.tsx) - Main dashboard page
|
|
3. [app/globals.css](app/globals.css) - Global styles
|
|
|
|
### Theme & Layout
|
|
4. [components/theme-provider.tsx](components/theme-provider.tsx)
|
|
5. [components/layout/app-sidebar.tsx](components/layout/app-sidebar.tsx)
|
|
6. [components/layout/header.tsx](components/layout/header.tsx)
|
|
7. [components/layout/theme-toggle.tsx](components/layout/theme-toggle.tsx)
|
|
8. [components/layout/user-nav.tsx](components/layout/user-nav.tsx)
|
|
|
|
### Dashboard Components
|
|
9. [components/dashboard/metric-card.tsx](components/dashboard/metric-card.tsx)
|
|
10. [components/dashboard/revenue-chart.tsx](components/dashboard/revenue-chart.tsx)
|
|
11. [components/dashboard/sales-chart.tsx](components/dashboard/sales-chart.tsx)
|
|
12. [components/dashboard/payments-table.tsx](components/dashboard/payments-table.tsx)
|
|
13. [components/dashboard/team-table.tsx](components/dashboard/team-table.tsx)
|
|
14. [components/dashboard/dashboard-tabs.tsx](components/dashboard/dashboard-tabs.tsx)
|
|
|
|
### Charts
|
|
15. [components/charts/line-chart.tsx](components/charts/line-chart.tsx)
|
|
16. [components/charts/bar-chart.tsx](components/charts/bar-chart.tsx)
|
|
|
|
### Data Layer
|
|
17. [lib/mock-data.ts](lib/mock-data.ts)
|
|
18. [lib/chart-config.ts](lib/chart-config.ts)
|
|
19. [lib/utils.ts](lib/utils.ts) - Auto-generated by shadcn
|
|
|
|
### Types
|
|
20. [types/dashboard.ts](types/dashboard.ts)
|
|
|
|
### Assets
|
|
21-28. [public/avatars/01-08.png](public/avatars/) - Avatar placeholder images
|
|
|
|
---
|
|
|
|
## Key Technical Decisions
|
|
|
|
### 1. Chart.js Integration
|
|
- Use Chart.js (as requested) with react-chartjs-2
|
|
- Mark chart components as "use client"
|
|
- Use dynamic imports with `{ ssr: false }` to avoid SSR issues
|
|
- Theme-aware colors using useTheme() hook
|
|
|
|
### 2. Sidebar Implementation
|
|
- Use shadcn/ui Sidebar component (official, accessible)
|
|
- Built-in state management with cookie persistence
|
|
- Fully customizable with Tailwind
|
|
|
|
### 3. Theme Management
|
|
- Use next-themes package (industry standard)
|
|
- Zero-flash on load with suppressHydrationWarning
|
|
- CSS class strategy for theme switching
|
|
|
|
### 4. Component Strategy
|
|
- Server Components by default
|
|
- "use client" only when necessary (charts, theme toggle, interactive elements)
|
|
- Feature-based organization in components/ directory
|
|
|
|
### 5. Responsive Design
|
|
- Mobile-first with Tailwind breakpoints
|
|
- Metrics: 1→2→4 column grid
|
|
- Charts/Tables: 1→2 column grid
|
|
- Horizontal scroll for tables on mobile
|
|
|
|
---
|
|
|
|
## Potential Challenges & Solutions
|
|
|
|
### Challenge 1: Chart.js SSR Issues
|
|
**Solution**: Use dynamic imports with `{ ssr: false }` and "use client" directive
|
|
|
|
### Challenge 2: Theme Flash on Load
|
|
**Solution**: Use next-themes with suppressHydrationWarning and disableTransitionOnChange
|
|
|
|
### Challenge 3: Sidebar State Persistence
|
|
**Solution**: shadcn/ui Sidebar has built-in cookie persistence
|
|
|
|
### Challenge 4: Responsive Tables
|
|
**Solution**: Wrap tables in `overflow-x-auto` containers
|
|
|
|
### Challenge 5: Chart Colors in Dark Mode
|
|
**Solution**: Use useTheme() to detect theme and apply color schemes from chart-config.ts
|
|
|
|
---
|
|
|
|
## Project Directory Structure
|
|
|
|
```
|
|
shadcn-dashboard/
|
|
├── app/
|
|
│ ├── layout.tsx # Root layout with providers
|
|
│ ├── page.tsx # Main dashboard page
|
|
│ └── globals.css # Global styles
|
|
├── components/
|
|
│ ├── ui/ # shadcn/ui components (auto-generated)
|
|
│ ├── layout/
|
|
│ │ ├── app-sidebar.tsx # Main sidebar
|
|
│ │ ├── header.tsx # Top header
|
|
│ │ ├── theme-toggle.tsx # Theme switcher
|
|
│ │ └── user-nav.tsx # User profile dropdown
|
|
│ ├── dashboard/
|
|
│ │ ├── metric-card.tsx # Metric display card
|
|
│ │ ├── revenue-chart.tsx # Revenue line chart
|
|
│ │ ├── sales-chart.tsx # Sales bar chart
|
|
│ │ ├── payments-table.tsx # Payments data table
|
|
│ │ ├── team-table.tsx # Team members table
|
|
│ │ └── dashboard-tabs.tsx # Tab navigation
|
|
│ ├── charts/
|
|
│ │ ├── line-chart.tsx # Line chart wrapper
|
|
│ │ └── bar-chart.tsx # Bar chart wrapper
|
|
│ └── theme-provider.tsx # Theme context provider
|
|
├── lib/
|
|
│ ├── utils.ts # Utility functions
|
|
│ ├── mock-data.ts # Mock dashboard data
|
|
│ └── chart-config.ts # Chart.js config
|
|
├── types/
|
|
│ └── dashboard.ts # TypeScript interfaces
|
|
├── public/
|
|
│ └── avatars/ # User avatar images
|
|
├── tailwind.config.ts
|
|
├── tsconfig.json
|
|
├── next.config.js
|
|
├── components.json
|
|
└── package.json
|
|
```
|
|
|
|
---
|
|
|
|
## Estimated Timeline
|
|
- **Phase 1** (Foundation): 30 minutes
|
|
- **Phase 2** (Theme & Layout): 45 minutes
|
|
- **Phase 3** (Data Layer): 20 minutes
|
|
- **Phase 4** (Charts): 45 minutes
|
|
- **Phase 5** (Dashboard Components): 90 minutes
|
|
- **Phase 6** (Assembly & Polish): 60 minutes
|
|
- **Phase 7** (Testing): 30 minutes
|
|
|
|
**Total**: 5-6 hours for complete implementation
|
|
|
|
---
|
|
|
|
## Next Steps After Approval
|
|
|
|
1. Run project initialization commands
|
|
2. Install and configure all dependencies
|
|
3. Create file structure
|
|
4. Implement components in order
|
|
5. Test thoroughly
|
|
6. Polish and optimize
|
|
|
|
## Future Enhancement Possibilities
|
|
|
|
1. **Real API Integration**: Replace mock data with API calls
|
|
2. **Authentication**: Add NextAuth.js or Clerk
|
|
3. **More Pages**: Analytics, Reports, User Management
|
|
4. **Real-time Updates**: WebSocket integration
|
|
5. **Advanced Tables**: Add TanStack Table for sorting/filtering
|
|
6. **Alternative Charts**: Consider shadcn/ui Chart components (Recharts) for better theme integration
|