frontend-shadcn

Frontend ShadCN Stack

Modern React frontend stack:

• Vite - Build tooling
• React 19 - UI framework
• TypeScript - Type safety
• Tailwind CSS v4 - Utility-first styling (@tailwindcss/vite plugin)
• shadcn/ui - Component library (New York style)
• React Router v7 - Client-side routing

Environment Setup

Use asdf to manage Node.js versions:

# Install Node.js plugin (one-time)
asdf plugin add nodejs

# Set project Node.js version
asdf set nodejs latest:22

This creates a .tool-versions file in the project root that ensures consistent Node.js versions across the team.

Reference Files

File	When to Use
setup-guide.md	Starting a new project from scratch
patterns.md	Implementing features, understanding architecture
maplibre.md	Working with MapLibre GL JS maps
mcp-tools.md	Looking up docs, adding components via MCP

Quick Reference

Commands

# Add shadcn component
npx shadcn@latest add <component> -y

# Dev server
npm run dev

# Type check
npm run type-check

Key Imports

// React Router v7 - use 'react-router' NOT 'react-router-dom'
import { Routes, Route, Link, useLocation, useSearchParams } from 'react-router'

// Path alias - @/ maps to src/
import { Button } from '@/components/ui/button'
import { cn } from '@/lib/utils'

Conditional Classes

import { cn } from '@/lib/utils'

<div className={cn(
  "base-classes",
  condition && "conditional-classes",
  variant === "primary" && "variant-classes"
)} />

Common Components

# Layout
npx shadcn@latest add sidebar card separator -y

# Forms
npx shadcn@latest add button input form select checkbox -y

# Feedback
npx shadcn@latest add dialog alert toast -y

# Navigation
npx shadcn@latest add dropdown-menu tabs tooltip -y

Project Structure

src/
├── components/
│   ├── ui/           # shadcn/ui components (auto-generated)
│   ├── AppShell.tsx  # Main layout with header
│   └── AppSidebar.tsx
├── pages/            # Route page components
├── hooks/            # Custom hooks
├── lib/
│   └── utils.ts      # cn() helper
├── App.tsx           # Route definitions
├── main.tsx          # Entry point with BrowserRouter
└── index.css         # Tailwind + shadcn theme

Tailwind Patterns

// Common utility patterns
"flex items-center gap-4"           // Flexbox with gap
"bg-muted text-muted-foreground"    // Muted backgrounds
"border-b bg-background"            // Borders and backgrounds
"h-screen overflow-auto"            // Full height scrolling
"space-y-4"                         // Vertical spacing

Common Gotchas

• Package management: Use npm install <pkg> not manual package.json edits
• shadcn components: Use npx shadcn@latest add <component> -y
• React Router imports: Use react-router NOT react-router-dom