pierre/shacn-dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
shacn-dashboard/PLAN.md
Pierre Wessman 59bc2fadf3 init
2025-12-12 09:53:53 +01:00

14 KiB
Raw Blame History

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

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

npx shadcn@latest init

Choose: Default style, Slate base color, CSS variables ✓

3. Install Dependencies

npm install chart.js react-chartjs-2 next-themes lucide-react date-fns
npm install -D @types/node

4. Install shadcn/ui Components

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

  • Wrap next-themes provider
  • Export ThemeProvider component

6. Configure Root Layout

File: 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

  • 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

  • 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

  • Avatar with dropdown menu
  • Options: Profile, Settings, Sign out

9. Create Header Component

File: 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

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

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

  • 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

  • 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

  • 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

  • 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

  • Use LineChart component
  • Dual-line display (Revenue + Subscriptions)
  • Wrap in Card with title

17. Build Sales Activity Chart

File: 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

  • 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

  • Use Table components
  • Columns: Member (Avatar + name), Email, Role
  • Wrap in Card with title

20. Create Dashboard Tabs

File: 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

  • 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

  • Import Inter from next/font/google
  • Apply to body with className

23. Add Custom Styling

File: app/globals.css

  • Smooth transitions for theme changes
  • Custom scrollbar styling
  • Hover effects
  • Focus states

24. Create Avatar Placeholders

Directory: 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

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

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 - Root layout with providers
  2. app/page.tsx - Main dashboard page
  3. app/globals.css - Global styles

Theme & Layout

  1. components/theme-provider.tsx
  2. components/layout/app-sidebar.tsx
  3. components/layout/header.tsx
  4. components/layout/theme-toggle.tsx
  5. components/layout/user-nav.tsx

Dashboard Components

  1. components/dashboard/metric-card.tsx
  2. components/dashboard/revenue-chart.tsx
  3. components/dashboard/sales-chart.tsx
  4. components/dashboard/payments-table.tsx
  5. components/dashboard/team-table.tsx
  6. components/dashboard/dashboard-tabs.tsx

Charts

  1. components/charts/line-chart.tsx
  2. components/charts/bar-chart.tsx

Data Layer

  1. lib/mock-data.ts
  2. lib/chart-config.ts
  3. lib/utils.ts - Auto-generated by shadcn

Types

  1. types/dashboard.ts

Assets

21-28. public/avatars/01-08.png - 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