Skip to content

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.json

Theme System ​

All colors are defined as CSS variables in globals.css. Never hardcode color values — always use the semantic tokens.

Available Tokens ​

TokenUse Case
bg-backgroundPage background
bg-cardCard / panel surfaces
text-foregroundPrimary text
text-muted-foregroundSecondary / label text
bg-primary / text-primaryBrand actions, active states
bg-destructiveDelete / danger actions
border-borderBorders and dividers
bg-sidebar / text-sidebar-foregroundSidebar-specific surfaces
bg-sidebar-accentSidebar hover/active states

Dark mode is handled automatically via the .dark class on <html> (set by next-themes).


Adding a New Page ​

  1. Create the page file under the (panel) route group:

    src/app/(panel)/your-feature/page.tsx
  2. Export a default React component:

    tsx
    export default function YourFeaturePage() {
      return <div>...</div>;
    }
  3. Add a navigation link in Sidebar.tsx:

    tsx
    const 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:

bash
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.

tsx
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 Header shows a hamburger button (MobileSidebar)
  • Clicking it opens the Sidebar inside a Sheet (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:

HeaderValue / purpose
Content-Security-Policydefault-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-OptionsDENY (browsers without CSP frame-ancestors)
X-Content-Type-Optionsnosniff
Referrer-Policystrict-origin-when-cross-origin
Permissions-Policycamera, microphone and geolocation disabled
Strict-Transport-Securitymax-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:

bash
pnpm --filter @vexlyx/dashboard test
pnpm --filter @vexlyx/dashboard test --project components
pnpm --filter @vexlyx/dashboard test --project unit

vitest.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 ​

bash
# 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)

Released under the MIT license.