Dashboard Setup — Developer Guide
Overview
The dashboard is a Next.js 15 App Router application. It uses:
- Tailwind CSS 4 with custom CSS variables for theming
- shadcn/ui (New York style) for all UI primitives
- next-themes for dark/light mode persistence
- Geist Sans + Geist Mono for typography (matches Vercel/Linear aesthetic)
The layout uses a two-panel structure: a fixed sidebar on the left and a scrollable main content area on the right. On mobile, the sidebar collapses and is accessible via a Sheet drawer triggered by a hamburger button in the header.
Project Structure
apps/dashboard/
├── src/
│ ├── app/
│ │ ├── globals.css # Tailwind + all CSS theme variables
│ │ ├── layout.tsx # Root layout: fonts, ThemeProvider
│ │ ├── page.tsx # Redirects / → /dashboard
│ │ ├── (panel)/ # Sidebar + Header shell — dashboard, projects, domains,
│ │ │ # databases, mail, monitoring, backups, firewall, services,
│ │ │ # users, audit-log, settings (one directory each)
│ │ │ └── layout.tsx
│ │ └── (standalone)/ # No sidebar shell — project detail sub-pages
│ │ └── layout.tsx
│ ├── components/ # One directory per feature area, matching (panel)'s routes,
│ │ │ # plus:
│ │ ├── ui/ # shadcn/ui primitives (DO NOT edit manually) — badge, button,
│ │ │ # card, dialog, dropdown-menu, input, label, select, separator,
│ │ │ # sheet, skeleton, switch, table, tabs, textarea, tooltip
│ │ ├── layout/ # Sidebar.tsx, Header.tsx, MobileSidebar.tsx, ThemeToggle.tsx
│ │ ├── quota/ # Shared quota-bar components used across feature pages
│ │ └── providers/
│ │ └── ThemeProvider.tsx # next-themes client wrapper
│ ├── hooks/ # One data-fetching/mutation hook per feature area
│ │ # (useProjects, useDomains, useBackups, useUsers, ...)
│ └── lib/
│ └── utils.ts # cn() helper (clsx + tailwind-merge)
├── components.json # shadcn/ui configuration
├── next.config.ts # transpilePackages: @vexlyx/shared
├── postcss.config.mjs # @tailwindcss/postcss plugin
└── package.jsonTheme System
All colors are defined as CSS variables in globals.css. Never hardcode color values — always use the semantic tokens.
Available Tokens
| Token | Use Case |
|---|---|
bg-background | Page background |
bg-card | Card / panel surfaces |
text-foreground | Primary text |
text-muted-foreground | Secondary / label text |
bg-primary / text-primary | Brand actions, active states |
bg-destructive | Delete / danger actions |
border-border | Borders and dividers |
bg-sidebar / text-sidebar-foreground | Sidebar-specific surfaces |
bg-sidebar-accent | Sidebar hover/active states |
Dark mode is handled automatically via the .dark class on <html> (set by next-themes).
Adding a New Page
Create the page file under the
(panel)route group:src/app/(panel)/your-feature/page.tsxExport a default React component:
tsxexport default function YourFeaturePage() { return <div>...</div>; }Add a navigation link in
Sidebar.tsx:tsxconst navItems = [ // ...existing items { label: "Your Feature", href: "/your-feature", icon: YourIcon }, ];
The page will automatically inherit the sidebar + header layout from (panel)/layout.tsx.
Adding shadcn/ui Components
The project uses shadcn/ui components via the radix-ui unified package (shadcn v4+). To add a new component:
cd apps/dashboard
npx shadcn@latest add [component-name]Import from @/components/ui/[component-name]. Do not edit files in src/components/ui/ — they are regenerated by shadcn.
Currently installed components (apps/dashboard/src/components/ui/): badge, button, card, dialog, dropdown-menu, input, label, select, separator, sheet, skeleton, switch, table, tabs, textarea, tooltip.
Dark Mode
Dark mode uses next-themes with the class strategy. The ThemeProvider wraps the entire app in layout.tsx. suppressHydrationWarning is set on <html> to prevent hydration mismatches.
The ThemeToggle button (Sun/Moon icons) is rendered in the Header and persists the user's choice across sessions via localStorage.
StatCard Component
StatCard is a reusable metric display for the dashboard overview. It supports a loading state that renders skeleton placeholders instead of values.
import { StatCard } from "@/components/dashboard/StatCard";
import { Server } from "lucide-react";
// Normal state
<StatCard title="Active Projects" value="12" description="+2 this week" icon={Server} />
// Loading state (show skeletons while data fetches)
<StatCard title="Active Projects" icon={Server} isLoading />Mobile Behavior
On screens narrower than md (768px):
- The desktop sidebar (
<aside className="hidden md:flex">) is hidden - The
Headershows a hamburger button (MobileSidebar) - Clicking it opens the
Sidebarinside aSheet(slide-in drawer from the left) - Clicking any navigation link closes the sheet automatically
Security Headers (#73)
next.config.ts applies a headers() block to every route, built by buildSecurityHeaders() in src/lib/securityHeaders.ts:
| Header | Value / purpose |
|---|---|
Content-Security-Policy | default-src 'self'; connect-src limited to self plus the API origin (NEXT_PUBLIC_API_URL) over http(s) and ws(s) for Socket.io; frame-src/object-src 'none'; base-uri 'self'; form-action limited to self, https://github.com and the API origin (the GitHub App manifest form posts to GitHub and GitHub redirects back to the API); frame-ancestors 'none' (clickjacking) |
X-Frame-Options | DENY (browsers without CSP frame-ancestors) |
X-Content-Type-Options | nosniff |
Referrer-Policy | strict-origin-when-cross-origin |
Permissions-Policy | camera, microphone and geolocation disabled |
Strict-Transport-Security | max-age=31536000, production only, no includeSubDomains/preload |
Known weakness: script-src keeps 'unsafe-inline' because Next.js emits inline bootstrap scripts and next-themes injects an inline theme script. Tightening it needs per-request nonces, which makes every page render dynamically; that is deliberately out of scope. 'unsafe-eval' is added in development only (React Refresh).
Zod and unsafe-eval: Zod 4 probes for eval support with new Function, and a strict CSP reports every blocked probe as a console error even though Zod falls back to its normal parser. The dashboard therefore sets z.config({ jitless: true }) in src/lib/zodConfig.ts, imported first by the root client provider (QueryProvider.tsx) so it runs before any schema is created. Keep that import first when you touch the provider.
Build-time value: the API origin comes from NEXT_PUBLIC_API_URL, which is fixed at next build (Dockerfile ARG), so the policy always matches the origin the client bundle actually calls. A malformed value fails the build.
If you add a new external resource (a CDN script, an embedded iframe, an image host, another API origin) it will be blocked until its origin is added to the matching directive in securityHeaders.ts. Watch the browser console for Refused to ... messages.
Tests: src/lib/securityHeaders.test.ts.
Component and Utility Tests (#54)
Run all dashboard tests from the monorepo root:
pnpm --filter @vexlyx/dashboard test
pnpm --filter @vexlyx/dashboard test --project components
pnpm --filter @vexlyx/dashboard test --project unitvitest.config.ts defines two test projects: adjacent src/**/*.test.ts files run in Node, while src/**/*.test.tsx files run in jsdom with React's automatic JSX runtime. Both inherit the @/ source alias. Vitest 5 uses projects rather than the removed environmentMatchGlobs option.
Keep jsdom on the 26.x line: it supports the declared Node 22 minimum. Newer major versions require newer Node minor releases; check their engine requirements before upgrading the test environment.
Component tests use @testing-library/react to render real components and @testing-library/user-event for typing and clicks. The component setup file (src/test/setup.ts) unmounts rendered trees after every test; Vitest globals are disabled, so cleanup is registered explicitly. Import test functions from vitest and place new tests next to their page or component.
The initial smoke tests cover the login page's form submission, validation, rejected credentials and two-factor challenge, plus project cards, navigation, loading and empty-list creation. Login tests mock the auth hooks and toast boundary; project tests render the actual cards. These tests need no running API, database or Docker services. Broader UI and end-to-end coverage remains separate work.
The password and two-factor forms in LoginForm.tsx have distinct React keys so uncontrolled input values reset when switching between them. The two-factor test guards against the email address being reused as the authenticator code.
Running Locally
# From monorepo root
pnpm dev # Starts dashboard on http://localhost:3000
# From apps/dashboard only
pnpm dev # Same, but without other packages
pnpm typecheck # TypeScript strict check
pnpm lint # ESLint check
pnpm build # Production build (must pass before any PR)